diff options
| author | Loïc Hoguin <[email protected]> | 2017-10-03 13:39:41 +0200 |
|---|---|---|
| committer | Loïc Hoguin <[email protected]> | 2017-10-03 13:39:41 +0200 |
| commit | b5d4cb91f80c833795a2d87050c3674bb7aecdc5 (patch) | |
| tree | 62bf0ad8326006fcd3407fcb7c34c844c0dc0874 /docs/en/ranch | |
| parent | 1f8d51dd2692fc3978080419987bbe4d49a41a90 (diff) | |
| download | ninenines.eu-b5d4cb91f80c833795a2d87050c3674bb7aecdc5.tar.gz ninenines.eu-b5d4cb91f80c833795a2d87050c3674bb7aecdc5.tar.bz2 ninenines.eu-b5d4cb91f80c833795a2d87050c3674bb7aecdc5.zip | |
Update Hugo, docs
Diffstat (limited to 'docs/en/ranch')
34 files changed, 5718 insertions, 5670 deletions
diff --git a/docs/en/ranch/1.2/guide/embedded/index.html b/docs/en/ranch/1.2/guide/embedded/index.html index ac94bf2a..ff2cf499 100644 --- a/docs/en/ranch/1.2/guide/embedded/index.html +++ b/docs/en/ranch/1.2/guide/embedded/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Embedded mode</title> @@ -67,54 +67,57 @@ <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 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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/index.html b/docs/en/ranch/1.2/guide/index.html index 2b1b7e05..cd37ce05 100644 --- a/docs/en/ranch/1.2/guide/index.html +++ b/docs/en/ranch/1.2/guide/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Ranch User Guide</title> @@ -67,48 +67,48 @@ <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 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> diff --git a/docs/en/ranch/1.2/guide/internals/index.html b/docs/en/ranch/1.2/guide/internals/index.html index 88466f8e..0f731816 100644 --- a/docs/en/ranch/1.2/guide/internals/index.html +++ b/docs/en/ranch/1.2/guide/internals/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Internals</title> @@ -67,99 +67,102 @@ <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 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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/introduction/index.html b/docs/en/ranch/1.2/guide/introduction/index.html index 8d2e565c..130721a0 100644 --- a/docs/en/ranch/1.2/guide/introduction/index.html +++ b/docs/en/ranch/1.2/guide/introduction/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Introduction</title> @@ -67,38 +67,41 @@ <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 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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/listeners/index.html b/docs/en/ranch/1.2/guide/listeners/index.html index eff0e0ed..83c092a0 100644 --- a/docs/en/ranch/1.2/guide/listeners/index.html +++ b/docs/en/ranch/1.2/guide/listeners/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Listeners</title> @@ -67,293 +67,296 @@ <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 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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/parsers/index.html b/docs/en/ranch/1.2/guide/parsers/index.html index a0b4e5d1..a5d18388 100644 --- a/docs/en/ranch/1.2/guide/parsers/index.html +++ b/docs/en/ranch/1.2/guide/parsers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Writing parsers</title> @@ -67,115 +67,118 @@ <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 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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/protocols/index.html b/docs/en/ranch/1.2/guide/protocols/index.html index b7918b8c..dffca064 100644 --- a/docs/en/ranch/1.2/guide/protocols/index.html +++ b/docs/en/ranch/1.2/guide/protocols/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Protocols</title> @@ -67,135 +67,138 @@ <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 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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/ssl_auth/index.html b/docs/en/ranch/1.2/guide/ssl_auth/index.html index 18e94d36..3261ddc4 100644 --- a/docs/en/ranch/1.2/guide/ssl_auth/index.html +++ b/docs/en/ranch/1.2/guide/ssl_auth/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: SSL client authentication</title> @@ -67,164 +67,167 @@ <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 [CAcert.org](<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 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 [CAcert.org](<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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/transports/index.html b/docs/en/ranch/1.2/guide/transports/index.html index e45b0d90..b60d99e6 100644 --- a/docs/en/ranch/1.2/guide/transports/index.html +++ b/docs/en/ranch/1.2/guide/transports/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Transports</title> @@ -67,195 +67,198 @@ <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 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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/index.html b/docs/en/ranch/1.2/index.html index d87c4243..0194031a 100644 --- a/docs/en/ranch/1.2/index.html +++ b/docs/en/ranch/1.2/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://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 index 08dcf0ce..eecb6cbe 100644 --- a/docs/en/ranch/1.2/manual/index.html +++ b/docs/en/ranch/1.2/manual/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Ranch Function Reference</title> @@ -67,38 +67,38 @@ <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 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> diff --git a/docs/en/ranch/1.2/manual/ranch/index.html b/docs/en/ranch/1.2/manual/ranch/index.html index 2c72b236..2cbc5dec 100644 --- a/docs/en/ranch/1.2/manual/ranch/index.html +++ b/docs/en/ranch/1.2/manual/ranch/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch(3)</title> @@ -67,423 +67,423 @@ <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 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> diff --git a/docs/en/ranch/1.2/manual/ranch_app/index.html b/docs/en/ranch/1.2/manual/ranch_app/index.html index fd930bf4..a3f2b89c 100644 --- a/docs/en/ranch/1.2/manual/ranch_app/index.html +++ b/docs/en/ranch/1.2/manual/ranch_app/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch(7)</title> @@ -67,43 +67,43 @@ <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 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> diff --git a/docs/en/ranch/1.2/manual/ranch_protocol/index.html b/docs/en/ranch/1.2/manual/ranch_protocol/index.html index e8411a2c..f88fad6c 100644 --- a/docs/en/ranch/1.2/manual/ranch_protocol/index.html +++ b/docs/en/ranch/1.2/manual/ranch_protocol/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_protocol(3)</title> @@ -67,83 +67,83 @@ <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 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> diff --git a/docs/en/ranch/1.2/manual/ranch_ssl/index.html b/docs/en/ranch/1.2/manual/ranch_ssl/index.html index c006d8e6..d1b83d48 100644 --- a/docs/en/ranch/1.2/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.2/manual/ranch_ssl/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_ssl(3)</title> @@ -67,349 +67,349 @@ <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 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> diff --git a/docs/en/ranch/1.2/manual/ranch_tcp/index.html b/docs/en/ranch/1.2/manual/ranch_tcp/index.html index 120010a5..989da87d 100644 --- a/docs/en/ranch/1.2/manual/ranch_tcp/index.html +++ b/docs/en/ranch/1.2/manual/ranch_tcp/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_tcp(3)</title> @@ -67,274 +67,274 @@ <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 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> diff --git a/docs/en/ranch/1.2/manual/ranch_transport/index.html b/docs/en/ranch/1.2/manual/ranch_transport/index.html index a9e1ac4f..fcd30741 100644 --- a/docs/en/ranch/1.2/manual/ranch_transport/index.html +++ b/docs/en/ranch/1.2/manual/ranch_transport/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_transport(3)</title> @@ -67,494 +67,494 @@ <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 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> diff --git a/docs/en/ranch/1.3/guide/embedded/index.html b/docs/en/ranch/1.3/guide/embedded/index.html index eea4e32b..a1d552af 100644 --- a/docs/en/ranch/1.3/guide/embedded/index.html +++ b/docs/en/ranch/1.3/guide/embedded/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Embedded mode</title> @@ -67,54 +67,57 @@ <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/5</code>, that works like <code>ranch:start_listener/5</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 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/5</code>, that works like <code>ranch:start_listener/5</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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/index.html b/docs/en/ranch/1.3/guide/index.html index 11fff995..e9986a13 100644 --- a/docs/en/ranch/1.3/guide/index.html +++ b/docs/en/ranch/1.3/guide/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Ranch User Guide</title> @@ -67,48 +67,48 @@ <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 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> diff --git a/docs/en/ranch/1.3/guide/internals/index.html b/docs/en/ranch/1.3/guide/internals/index.html index 7a08d075..f75bc639 100644 --- a/docs/en/ranch/1.3/guide/internals/index.html +++ b/docs/en/ranch/1.3/guide/internals/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Internals</title> @@ -67,99 +67,102 @@ <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/5</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 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/5</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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/introduction/index.html b/docs/en/ranch/1.3/guide/introduction/index.html index 8997b000..9c795d8b 100644 --- a/docs/en/ranch/1.3/guide/introduction/index.html +++ b/docs/en/ranch/1.3/guide/introduction/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Introduction</title> @@ -67,40 +67,43 @@ <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, FreeBSD, OSX and Windows.</p></div>
-<div class="paragraph"><p>Ranch is developed for Erlang/OTP R16B+.</p></div>
-<div class="paragraph"><p>There are known issues with the SSL application found in Erlang/OTP
-18.3.2 and 18.3.3. These versions are therefore not supported.</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 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, FreeBSD, OSX and Windows.</p></div> +<div class="paragraph"><p>Ranch is developed for Erlang/OTP R16B+.</p></div> +<div class="paragraph"><p>There are known issues with the SSL application found in Erlang/OTP +18.3.2 and 18.3.3. These versions are therefore not supported.</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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/listeners/index.html b/docs/en/ranch/1.3/guide/listeners/index.html index 6cc4d0a1..bb7f3310 100644 --- a/docs/en/ranch/1.3/guide/listeners/index.html +++ b/docs/en/ranch/1.3/guide/listeners/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Listeners</title> @@ -67,373 +67,376 @@ <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 use 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/5</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: #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/5</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: #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: #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: #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>The maximum number of connections is a soft limit. In practice, it
-can reach <code>max_connections</code> + the number of acceptors.</p></div>
-<div class="paragraph"><p>When the maximum number of connections is reached, Ranch will stop
-accepting connections. This will not result in further connections
-being rejected, as the kernel option allows queueing incoming
-connections. The size of this queue is determined by the <code>backlog</code>
-option and defaults to 1024. Ranch does not know about the number
-of connections that are in the backlog.</p></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="_customizing_the_number_of_acceptor_processes">Customizing the number of acceptor processes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default Ranch will use 10 acceptor processes. Their role is
-to accept connections and spawn a connection process for every
-new connection.</p></div>
-<div class="paragraph"><p>This number can be tweaked to improve performance. A good
-number is typically between 10 or 100 acceptors. You must
-measure to find the best value for your application.</p></div>
-<div class="listingblock">
-<div class="title">Specifying a custom number of acceptor processes</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: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">num_acceptors</span>, <span style="color: #993399">42</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_when_running_out_of_file_descriptors">When running out of file descriptors</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Operating systems have limits on the number of sockets
-which can be opened by applications. When this maximum is
-reached the listener can no longer accept new connections. The
-accept rate of the listener will be automatically reduced, and a
-warning message will be logged.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>=ERROR REPORT==== 13-Jan-2016::12:24:38 ===
-Ranch acceptor reducing accept rate: out of file descriptors</code></pre>
-</div></div>
-<div class="paragraph"><p>If you notice messages like this you should increase the number
-of file-descriptors which can be opened by your application. How
-this should be done is operating-system dependent. Please consult
-the documentation of your operating system.</p></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 class="sect1">
-<h2 id="_obtaining_information_about_listeners">Obtaining information about listeners</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch provides two functions for retrieving information about the
-listeners, for reporting and diagnostic purposes.</p></div>
-<div class="paragraph"><p>The <code>ranch:info/0</code> function will return detailed information
-about all listeners.</p></div>
-<div class="listingblock">
-<div class="title">Retrieving detailed information</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:info</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The <code>ranch:procs/2</code> function will return all acceptor or listener
-processes for a given listener.</p></div>
-<div class="listingblock">
-<div class="title">Get all acceptor processes</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:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">acceptors</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Get all connection processes</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:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">connections</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
+<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 use 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/5</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: #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/5</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: #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: #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: #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>The maximum number of connections is a soft limit. In practice, it +can reach <code>max_connections</code> + the number of acceptors.</p></div> +<div class="paragraph"><p>When the maximum number of connections is reached, Ranch will stop +accepting connections. This will not result in further connections +being rejected, as the kernel option allows queueing incoming +connections. The size of this queue is determined by the <code>backlog</code> +option and defaults to 1024. Ranch does not know about the number +of connections that are in the backlog.</p></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="_customizing_the_number_of_acceptor_processes">Customizing the number of acceptor processes</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default Ranch will use 10 acceptor processes. Their role is +to accept connections and spawn a connection process for every +new connection.</p></div> +<div class="paragraph"><p>This number can be tweaked to improve performance. A good +number is typically between 10 or 100 acceptors. You must +measure to find the best value for your application.</p></div> +<div class="listingblock"> +<div class="title">Specifying a custom number of acceptor processes</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: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">num_acceptors</span>, <span style="color: #993399">42</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_when_running_out_of_file_descriptors">When running out of file descriptors</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Operating systems have limits on the number of sockets +which can be opened by applications. When this maximum is +reached the listener can no longer accept new connections. The +accept rate of the listener will be automatically reduced, and a +warning message will be logged.</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>=ERROR REPORT==== 13-Jan-2016::12:24:38 === +Ranch acceptor reducing accept rate: out of file descriptors</code></pre> +</div></div> +<div class="paragraph"><p>If you notice messages like this you should increase the number +of file-descriptors which can be opened by your application. How +this should be done is operating-system dependent. Please consult +the documentation of your operating system.</p></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 class="sect1"> +<h2 id="_obtaining_information_about_listeners">Obtaining information about listeners</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch provides two functions for retrieving information about the +listeners, for reporting and diagnostic purposes.</p></div> +<div class="paragraph"><p>The <code>ranch:info/0</code> function will return detailed information +about all listeners.</p></div> +<div class="listingblock"> +<div class="title">Retrieving detailed information</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:info</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>ranch:procs/2</code> function will return all acceptor or listener +processes for a given listener.</p></div> +<div class="listingblock"> +<div class="title">Get all acceptor processes</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:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">acceptors</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Get all connection processes</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:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">connections</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/parsers/index.html b/docs/en/ranch/1.3/guide/parsers/index.html index 67fef620..41f19b7e 100644 --- a/docs/en/ranch/1.3/guide/parsers/index.html +++ b/docs/en/ranch/1.3/guide/parsers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Writing parsers</title> @@ -67,115 +67,118 @@ <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 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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/protocols/index.html b/docs/en/ranch/1.3/guide/protocols/index.html index 45e13bf7..d42e9d7d 100644 --- a/docs/en/ranch/1.3/guide/protocols/index.html +++ b/docs/en/ranch/1.3/guide/protocols/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Protocols</title> @@ -67,110 +67,113 @@ <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/5</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>Use 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">1</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="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">proc_lib: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: #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="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>Check the <code>tcp_reverse</code> example for a complete example.</p></div>
-</div>
-</div>
+<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/5</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>Use 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">1</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="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">proc_lib: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: #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="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>Check the <code>tcp_reverse</code> example for a complete example.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/ssl_auth/index.html b/docs/en/ranch/1.3/guide/ssl_auth/index.html index b831fbe2..3cc585f2 100644 --- a/docs/en/ranch/1.3/guide/ssl_auth/index.html +++ b/docs/en/ranch/1.3/guide/ssl_auth/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: SSL client authentication</title> @@ -67,164 +67,167 @@ <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: #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 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: #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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/transports/index.html b/docs/en/ranch/1.3/guide/transports/index.html index 56103db3..1b13c696 100644 --- a/docs/en/ranch/1.3/guide/transports/index.html +++ b/docs/en/ranch/1.3/guide/transports/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Transports</title> @@ -67,185 +67,188 @@ <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>.</p></div>
-<div class="paragraph"><p>Ranch depends on <code>ssl</code> by default so any necessary
-dependencies will start when Ranch is started. It is
-possible to remove the dependency when the SSL transport
-will not be used. Refer to your release build tool’s
-documentation for more information.</p></div>
-<div class="paragraph"><p>When embedding Ranch listeners that have an SSL transport,
-your application must depend on the <code>ssl</code> application for
-proper behavior.</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 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>.</p></div> +<div class="paragraph"><p>Ranch depends on <code>ssl</code> by default so any necessary +dependencies will start when Ranch is started. It is +possible to remove the dependency when the SSL transport +will not be used. Refer to your release build tool’s +documentation for more information.</p></div> +<div class="paragraph"><p>When embedding Ranch listeners that have an SSL transport, +your application must depend on the <code>ssl</code> application for +proper behavior.</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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/manual/index.html b/docs/en/ranch/1.3/manual/index.html index a1122ab0..c0d63cf2 100644 --- a/docs/en/ranch/1.3/manual/index.html +++ b/docs/en/ranch/1.3/manual/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Ranch Function Reference</title> @@ -67,38 +67,38 @@ <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 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> diff --git a/docs/en/ranch/1.3/manual/ranch/index.html b/docs/en/ranch/1.3/manual/ranch/index.html index 5c2f9f3e..b8b4b35d 100644 --- a/docs/en/ranch/1.3/manual/ranch/index.html +++ b/docs/en/ranch/1.3/manual/ranch/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch(3)</title> @@ -67,567 +67,567 @@ <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: #FF6600">num_acceptors</span>, <span style="font-weight: bold"><span style="color: #000000">pos_integer</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">
-num_acceptors (10)
-</dt>
-<dd>
-<p>
- Number of processes that accept connections.
-</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_numacceptors_transport_transopts_protocol_protoopts_8594_supervisor_child_spec">child_spec(Ref, NumAcceptors, 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">
-NumAcceptors = 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="_info_8594_ref_key_value">info() → [{Ref, [{Key, Value}]}]</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-Key = atom()
-</dt>
-<dd>
-<p>
-Information key.
-</p>
-</dd>
-<dt class="hdlist1">
-Value = any()
-</dt>
-<dd>
-<p>
-Information value.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return detailed information about all Ranch listeners.</p></div>
-<div class="paragraph"><p>The following keys are defined:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-pid
-</dt>
-<dd>
-<p>
-Pid of the listener’s top-level supervisor.
-</p>
-</dd>
-<dt class="hdlist1">
-ip
-</dt>
-<dd>
-<p>
-Interface Ranch listens on.
-</p>
-</dd>
-<dt class="hdlist1">
-port
-</dt>
-<dd>
-<p>
-Port number Ranch listens on.
-</p>
-</dd>
-<dt class="hdlist1">
-num_acceptors
-</dt>
-<dd>
-<p>
-Number of acceptor processes.
-</p>
-</dd>
-<dt class="hdlist1">
-max_connections
-</dt>
-<dd>
-<p>
-Maximum number of connections.
-</p>
-</dd>
-<dt class="hdlist1">
-active_connections
-</dt>
-<dd>
-<p>
-Number of active connections.
-</p>
-</dd>
-<dt class="hdlist1">
-all_connections
-</dt>
-<dd>
-<p>
-Number of connections, including those removed from the count.
-</p>
-</dd>
-<dt class="hdlist1">
-transport
-</dt>
-<dd>
-<p>
-Transport module.
-</p>
-</dd>
-<dt class="hdlist1">
-transport_options
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-protocol
-</dt>
-<dd>
-<p>
-Protocol module.
-</p>
-</dd>
-<dt class="hdlist1">
-protocol_options
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_procs_ref_acceptors_connections_8594_pid">procs(Ref, acceptors | connections) → [pid()]</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return all acceptor or connection processes for one 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_numacceptors_transport_transopts_protocol_protoopts_8594_ok_pid_error_badarg">start_listener(Ref, NumAcceptors, 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">
-NumAcceptors = 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 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: #FF6600">num_acceptors</span>, <span style="font-weight: bold"><span style="color: #000000">pos_integer</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"> +num_acceptors (10) +</dt> +<dd> +<p> + Number of processes that accept connections. +</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_numacceptors_transport_transopts_protocol_protoopts_8594_supervisor_child_spec">child_spec(Ref, NumAcceptors, 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"> +NumAcceptors = 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="_info_8594_ref_key_value">info() → [{Ref, [{Key, Value}]}]</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +Key = atom() +</dt> +<dd> +<p> +Information key. +</p> +</dd> +<dt class="hdlist1"> +Value = any() +</dt> +<dd> +<p> +Information value. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return detailed information about all Ranch listeners.</p></div> +<div class="paragraph"><p>The following keys are defined:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +pid +</dt> +<dd> +<p> +Pid of the listener’s top-level supervisor. +</p> +</dd> +<dt class="hdlist1"> +ip +</dt> +<dd> +<p> +Interface Ranch listens on. +</p> +</dd> +<dt class="hdlist1"> +port +</dt> +<dd> +<p> +Port number Ranch listens on. +</p> +</dd> +<dt class="hdlist1"> +num_acceptors +</dt> +<dd> +<p> +Number of acceptor processes. +</p> +</dd> +<dt class="hdlist1"> +max_connections +</dt> +<dd> +<p> +Maximum number of connections. +</p> +</dd> +<dt class="hdlist1"> +active_connections +</dt> +<dd> +<p> +Number of active connections. +</p> +</dd> +<dt class="hdlist1"> +all_connections +</dt> +<dd> +<p> +Number of connections, including those removed from the count. +</p> +</dd> +<dt class="hdlist1"> +transport +</dt> +<dd> +<p> +Transport module. +</p> +</dd> +<dt class="hdlist1"> +transport_options +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +protocol +</dt> +<dd> +<p> +Protocol module. +</p> +</dd> +<dt class="hdlist1"> +protocol_options +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +</div> +<div class="sect2"> +<h3 id="_procs_ref_acceptors_connections_8594_pid">procs(Ref, acceptors | connections) → [pid()]</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return all acceptor or connection processes for one 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_numacceptors_transport_transopts_protocol_protoopts_8594_ok_pid_error_badarg">start_listener(Ref, NumAcceptors, 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"> +NumAcceptors = 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> diff --git a/docs/en/ranch/1.3/manual/ranch_app/index.html b/docs/en/ranch/1.3/manual/ranch_app/index.html index 3c834556..2ad98222 100644 --- a/docs/en/ranch/1.3/manual/ranch_app/index.html +++ b/docs/en/ranch/1.3/manual/ranch_app/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch(7)</title> @@ -67,41 +67,41 @@ <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 depends on the <code>ssl</code> application to
-start. It is used for handling secure connections, when the
-transport is <code>ranch_ssl</code>. It can be disabled if SSL is not
-used.</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 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 depends on the <code>ssl</code> application to +start. It is used for handling secure connections, when the +transport is <code>ranch_ssl</code>. It can be disabled if SSL is not +used.</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> diff --git a/docs/en/ranch/1.3/manual/ranch_protocol/index.html b/docs/en/ranch/1.3/manual/ranch_protocol/index.html index 59f945d2..ce82c3f0 100644 --- a/docs/en/ranch/1.3/manual/ranch_protocol/index.html +++ b/docs/en/ranch/1.3/manual/ranch_protocol/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_protocol(3)</title> @@ -67,83 +67,83 @@ <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 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> diff --git a/docs/en/ranch/1.3/manual/ranch_ssl/index.html b/docs/en/ranch/1.3/manual/ranch_ssl/index.html index d923f172..3a466dee 100644 --- a/docs/en/ranch/1.3/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.3/manual/ranch_ssl/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_ssl(3)</title> @@ -67,385 +67,385 @@ <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">beast_mitigation</span>, <span style="color: #FF6600">one_n_minus_one</span> | <span style="color: #FF6600">zero_n</span> | <span style="color: #FF6600">disabled</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">padding_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</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">signature_algs</span>, [{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), <span style="font-weight: bold"><span style="color: #000080">atom</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">v2_hello_compatible</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</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">
-beast_mitigation
-</dt>
-<dd>
-<p>
- Change the BEAST mitigation strategy for SSL-3.0 and TLS-1.0 to interoperate with legacy software.
-</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">
-padding_check
-</dt>
-<dd>
-<p>
- Allow disabling the block cipher padding check for TLS-1.0 to be able to interoperate with legacy software.
-</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">
-signature_algs
-</dt>
-<dd>
-<p>
- The TLS signature algorithm extension may be used, from TLS 1.2, to negotiate which signature algorithm to use during the TLS handshake.
-</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">
-v2_hello_compatible
-</dt>
-<dd>
-<p>
- Accept clients that send hello messages in SSL-2.0 format while offering supported SSL/TLS versions.
-</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 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">beast_mitigation</span>, <span style="color: #FF6600">one_n_minus_one</span> | <span style="color: #FF6600">zero_n</span> | <span style="color: #FF6600">disabled</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">padding_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</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">signature_algs</span>, [{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), <span style="font-weight: bold"><span style="color: #000080">atom</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">v2_hello_compatible</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</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"> +beast_mitigation +</dt> +<dd> +<p> + Change the BEAST mitigation strategy for SSL-3.0 and TLS-1.0 to interoperate with legacy software. +</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"> +padding_check +</dt> +<dd> +<p> + Allow disabling the block cipher padding check for TLS-1.0 to be able to interoperate with legacy software. +</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"> +signature_algs +</dt> +<dd> +<p> + The TLS signature algorithm extension may be used, from TLS 1.2, to negotiate which signature algorithm to use during the TLS handshake. +</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"> +v2_hello_compatible +</dt> +<dd> +<p> + Accept clients that send hello messages in SSL-2.0 format while offering supported SSL/TLS versions. +</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> diff --git a/docs/en/ranch/1.3/manual/ranch_tcp/index.html b/docs/en/ranch/1.3/manual/ranch_tcp/index.html index b33bfd20..60574604 100644 --- a/docs/en/ranch/1.3/manual/ranch_tcp/index.html +++ b/docs/en/ranch/1.3/manual/ranch_tcp/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_tcp(3)</title> @@ -67,283 +67,283 @@ <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">ipv6_v6only</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</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">
-ipv6_v6only (false)
-</dt>
-<dd>
-<p>
- Listen on IPv4 and IPv6 (false) or only on IPv6 (true). Use with inet6.
-</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 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">ipv6_v6only</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</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"> +ipv6_v6only (false) +</dt> +<dd> +<p> + Listen on IPv4 and IPv6 (false) or only on IPv6 (true). Use with inet6. +</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> diff --git a/docs/en/ranch/1.3/manual/ranch_transport/index.html b/docs/en/ranch/1.3/manual/ranch_transport/index.html index aa57afd8..8840daad 100644 --- a/docs/en/ranch/1.3/manual/ranch_transport/index.html +++ b/docs/en/ranch/1.3/manual/ranch_transport/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_transport(3)</title> @@ -67,494 +67,494 @@ <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 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> diff --git a/docs/en/ranch/index.html b/docs/en/ranch/index.html index d87c4243..0194031a 100644 --- a/docs/en/ranch/index.html +++ b/docs/en/ranch/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file |