diff options
Diffstat (limited to 'docs/en/ranch/1.2/guide')
| -rw-r--r-- | docs/en/ranch/1.2/guide/embedded/index.html | 89 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/index.html | 86 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/internals/index.html | 179 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/introduction/index.html | 57 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/listeners/index.html | 567 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/parsers/index.html | 211 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/protocols/index.html | 251 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/ssl_auth/index.html | 309 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/transports/index.html | 371 |
9 files changed, 1072 insertions, 1048 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"> |