diff options
| author | Loïc Hoguin <[email protected]> | 2018-06-13 09:54:12 +0200 |
|---|---|---|
| committer | Loïc Hoguin <[email protected]> | 2018-06-13 09:54:12 +0200 |
| commit | 92b54aacc0de5446dd5497c39897b0bbff72e626 (patch) | |
| tree | c3a98cfec636d1271f5804e5c19b35b208bba00d /docs/en/ranch/1.2 | |
| parent | 8b5c3dc972b99f174750123c9e4abc96259c34a9 (diff) | |
| download | ninenines.eu-92b54aacc0de5446dd5497c39897b0bbff72e626.tar.gz ninenines.eu-92b54aacc0de5446dd5497c39897b0bbff72e626.tar.bz2 ninenines.eu-92b54aacc0de5446dd5497c39897b0bbff72e626.zip | |
Rebuild using Asciideck
Diffstat (limited to 'docs/en/ranch/1.2')
| -rw-r--r-- | docs/en/ranch/1.2/guide/embedded/index.html | 60 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/index.html | 46 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/internals/index.html | 105 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/introduction/index.html | 33 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/listeners/index.html | 347 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/parsers/index.html | 140 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/protocols/index.html | 183 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/ssl_auth/index.html | 188 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/guide/transports/index.html | 229 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/manual/index.html | 36 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/manual/ranch/index.html | 570 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/manual/ranch_app/index.html | 44 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/manual/ranch_protocol/index.html | 90 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/manual/ranch_ssl/index.html | 479 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/manual/ranch_tcp/index.html | 323 | ||||
| -rw-r--r-- | docs/en/ranch/1.2/manual/ranch_transport/index.html | 672 |
16 files changed, 1071 insertions, 2474 deletions
diff --git a/docs/en/ranch/1.2/guide/embedded/index.html b/docs/en/ranch/1.2/guide/embedded/index.html index 39350a45..141bad1e 100644 --- a/docs/en/ranch/1.2/guide/embedded/index.html +++ b/docs/en/ranch/1.2/guide/embedded/index.html @@ -62,48 +62,30 @@ <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"> +<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> <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 +<p>To embed Ranch in your application you can simply add the child specs to your supervision tree. This can all be done in the <code>init/1</code> function of one of your application supervisors.</p> +<p>Ranch 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> +<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> +<p>As for <code>ranch_sup</code>, the child spec is simple enough to not require a convenience function.</p> +<p>The following example adds both <code>ranch_sup</code> and one listener to another application's supervision tree.</p> +<div class="listingblock"><div class="title">Embed Ranch directly in your supervision tree</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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> +<pre><tt><b><font color="#000000">init</font></b>([]) <font color="#990000">-></font> + <font color="#009900">RanchSupSpec</font> <font color="#990000">=</font> {<font color="#FF6600">ranch_sup</font>, {<font color="#FF6600">ranch_sup</font>, <font color="#FF6600">start_link</font>, []}, + <font color="#FF6600">permanent</font>, <font color="#993399">5000</font>, <font color="#FF6600">supervisor</font>, [<font color="#FF6600">ranch_sup</font>]}, + <font color="#009900">ListenerSpec</font> <font color="#990000">=</font> <b><font color="#000000">ranch:child_spec</font></b>(<font color="#FF6600">echo</font>, <font color="#993399">100</font>, + <font color="#FF6600">ranch_tcp</font>, [{<font color="#FF6600">port</font>, <font color="#993399">5555</font>}], + <font color="#FF6600">echo_protocol</font>, [] + ), + {<font color="#FF6600">ok</font>, {{<font color="#FF6600">one_for_one</font>, <font color="#993399">10</font>, <font color="#993399">10</font>}, [<font color="#009900">RanchSupSpec</font>, <font color="#009900">ListenerSpec</font>]}}<font color="#990000">.</font></tt></pre> +</div></div> +<p>Remember, you can add as many listener child specs as needed, but only one <code>ranch_sup</code> spec!</p> +<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> + @@ -160,6 +142,8 @@ more details on how Ranch does it.</p></div> + <li><a href="/docs/en/ranch/1.5/guide">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> diff --git a/docs/en/ranch/1.2/guide/index.html b/docs/en/ranch/1.2/guide/index.html index 7c1cf9ed..8c91582e 100644 --- a/docs/en/ranch/1.2/guide/index.html +++ b/docs/en/ranch/1.2/guide/index.html @@ -62,48 +62,24 @@ <h1 class="lined-header"><span>Ranch User Guide</span></h1> -<div class="ulist"><ul> -<li> -<p> -<a href="introduction/">Introduction</a> -</p> +<ul><li><a href="introduction/">Introduction</a> </li> -<li> -<p> -<a href="listeners/">Listeners</a> -</p> +<li><a href="listeners/">Listeners</a> </li> -<li> -<p> -<a href="transports/">Transports</a> -</p> +<li><a href="transports/">Transports</a> </li> -<li> -<p> -<a href="protocols/">Protocols</a> -</p> +<li><a href="protocols/">Protocols</a> </li> -<li> -<p> -<a href="embedded/">Embedded mode</a> -</p> +<li><a href="embedded/">Embedded mode</a> </li> -<li> -<p> -<a href="parsers/">Writing parsers</a> -</p> +<li><a href="parsers/">Writing parsers</a> </li> -<li> -<p> -<a href="ssl_auth/">SSL client authentication</a> -</p> +<li><a href="ssl_auth/">SSL client authentication</a> </li> -<li> -<p> -<a href="internals/">Internals</a> -</p> +<li><a href="internals/">Internals</a> </li> -</ul></div> +</ul> + @@ -138,6 +114,8 @@ + <li><a href="/docs/en/ranch/1.5/guide">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> diff --git a/docs/en/ranch/1.2/guide/internals/index.html b/docs/en/ranch/1.2/guide/internals/index.html index 5794c4bc..c5926f1e 100644 --- a/docs/en/ranch/1.2/guide/internals/index.html +++ b/docs/en/ranch/1.2/guide/internals/index.html @@ -62,93 +62,34 @@ <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"> +<p>This chapter may not apply to embedded Ranch as embedding allows you to use an architecture specific to your application, which may or may not be compatible with the description of the Ranch application.</p> +<p>Note that for everything related to efficiency and performance, you should perform the benchmarks yourself to get the numbers that matter to you. Generic benchmarks found on the web may or may not be of use to you, you can never know until you benchmark your own system.</p> <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"> +<p>Ranch is an OTP application.</p> +<p>Like all OTP applications, Ranch has a top supervisor. It is responsible for supervising the <code>ranch_server</code> process and all the listeners that will be started.</p> +<p>The <code>ranch_server</code> gen_server is a central process keeping track of the listeners and their acceptors. It does so through the use of a public ets table called <code>ranch_server</code>. The table is owned by the top supervisor to improve fault tolerance. This way if the <code>ranch_server</code> gen_server fails, it doesn't lose any information and the restarted process can continue as if nothing happened.</p> +<p>Ranch uses a custom supervisor for managing connections. This supervisor keeps track of the number of connections and handles connection limits directly. While it is heavily optimized to perform the task of creating connection processes for accepted connections, it is still following the OTP principles and the usual <code>sys</code> and <code>supervisor</code> calls will work on it as expected.</p> +<p>Listeners are grouped into the <code>ranch_listener_sup</code> supervisor and consist of three kinds of processes: the listener gen_server, the acceptor processes and the connection processes, both grouped under their own supervisor. All of these processes are registered to the <code>ranch_server</code> gen_server with varying amount of information.</p> +<p>All socket operations, including listening for connections, go through transport handlers. Accepted connections are given to the protocol handler. Transport handlers are simple callback modules for performing operations on sockets. Protocol handlers start a new process, which receives socket ownership, with no requirements on how the code should be written inside that new process.</p> <h2 id="_number_of_acceptors">Number of acceptors</h2> -<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"> +<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> +<p>First of all, it should not be confused with the maximum number of connections. Acceptor processes are only used for accepting and have nothing else in common with connection processes. Therefore there is nothing to be gained from setting this number too high, in fact it can slow everything else down.</p> +<p>Second, this number should be high enough to allow Ranch to accept connections concurrently. But the number of cores available doesn't seem to be the only factor for choosing this number, as we can observe faster accepts if we have more acceptors than cores. It might be entirely dependent on the protocol, however.</p> +<p>Our observations suggest that using 100 acceptors on modern hardware is a good solution, as it's big enough to always have acceptors ready and it's low enough that it doesn't have a negative impact on the system's performances.</p> <h2 id="_platform_specific_tcp_features">Platform-specific TCP features</h2> -<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 +<p>Some socket options are platform-specific and not supported by <code>inet</code>. They can be of interest because they generally are related to optimizations provided by the underlying OS. They can still be enabled thanks to the <code>raw</code> option, for which we will see an example.</p> +<p>One of these features is <code>TCP_DEFER_ACCEPT</code> on Linux. It is a simplified accept mechanism which will wait for application data to come in before handing out the connection to the Erlang process.</p> +<p>This is especially useful if you expect many connections to be mostly idle, perhaps part of a connection pool. They can be handled by the kernel directly until they send any real data, instead of allocating resources to idle connections.</p> +<p>To enable this mechanism, the following option can be used.</p> +<div class="listingblock"><div class="title">Using raw transport options</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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> +<pre><tt>{<font color="#FF6600">raw</font>, <font color="#993399">6</font>, <font color="#993399">9</font>, <font color="#990000"><<</font> <b><font color="#000000">30:32</font></b><font color="#990000">/</font><font color="#FF6600">native</font> <font color="#990000">>></font>}</tt></pre> +</div></div> +<p>It means go on layer 6, turn on option 9 with the given integer parameter.</p> + @@ -201,6 +142,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/ranch/1.5/guide">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> diff --git a/docs/en/ranch/1.2/guide/introduction/index.html b/docs/en/ranch/1.2/guide/introduction/index.html index e2e8b3b6..64859ee0 100644 --- a/docs/en/ranch/1.2/guide/introduction/index.html +++ b/docs/en/ranch/1.2/guide/introduction/index.html @@ -62,32 +62,17 @@ <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"> +<p>Ranch is a socket acceptor pool for TCP protocols.</p> +<p>Ranch aims to provide everything you need to accept TCP connections with a small code base and low latency while being easy to use directly as an application or to embed into your own.</p> <h2 id="_prerequisites">Prerequisites</h2> -<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"> +<p>It is assumed the developer already knows Erlang and has some experience with socket programming and TCP protocols.</p> <h2 id="_supported_platforms">Supported platforms</h2> -<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"> +<p>Ranch is tested and supported on Linux.</p> +<p>Ranch is developed for Erlang R15B01+.</p> +<p>Ranch may be compiled on earlier Erlang versions with small source code modifications but there is no guarantee that it will work as expected.</p> <h2 id="_versioning">Versioning</h2> -<div class="sectionbody"> -<div class="paragraph"><p>Ranch uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a></p></div> -</div> -</div> +<p>Ranch uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a></p> + @@ -140,6 +125,8 @@ modifications but there is no guarantee that it will work as expected.</p></div> + <li><a href="/docs/en/ranch/1.5/guide">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> diff --git a/docs/en/ranch/1.2/guide/listeners/index.html b/docs/en/ranch/1.2/guide/listeners/index.html index f8c24289..5d7bb697 100644 --- a/docs/en/ranch/1.2/guide/listeners/index.html +++ b/docs/en/ranch/1.2/guide/listeners/index.html @@ -62,287 +62,168 @@ <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"> +<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> +<p>The listener takes care of supervising all the acceptor and connection processes, allowing developers to focus on building their application.</p> <h2 id="_starting_a_listener">Starting a listener</h2> -<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> +<p>Ranch does nothing by default. It is up to the application developer to request that Ranch listens for connections.</p> +<p>A listener can be started and stopped at will.</p> +<p>When starting a listener, a number of different settings are required:</p> +<ul><li>A name to identify it locally and be able to interact with it. </li> -<li> -<p> -The number of acceptors in the pool. -</p> +<li>The number of acceptors in the pool. </li> -<li> -<p> -A transport handler and its associated options. -</p> +<li>A transport handler and its associated options. </li> -<li> -<p> -A protocol handler and its associated options. -</p> +<li>A protocol handler and its associated options. </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 +</ul> +<p>Ranch includes both TCP and SSL transport handlers, respectively <code>ranch_tcp</code> and <code>ranch_ssl</code>.</p> +<p>A listener can be started by calling the <code>ranch:start_listener/6</code> function. Before doing so however, you must ensure that the <code>ranch</code> application is started.</p> +<div class="listingblock"><div class="title">Starting the Ranch application</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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 +<pre><tt><font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">application:start</font></b>(<font color="#FF6600">ranch</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>You are then ready to start a listener. Let's call it <code>tcp_echo</code>. It will have a pool of 100 acceptors, use a TCP transport and forward connections to the <code>echo_protocol</code> handler.</p> +<div class="listingblock"><div class="title">Starting a listener for TCP connections on port 5555</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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 +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">tcp_echo</font>, <font color="#993399">100</font>, + <font color="#FF6600">ranch_tcp</font>, [{<font color="#FF6600">port</font>, <font color="#993399">5555</font>}], + <font color="#FF6600">echo_protocol</font>, [] +)<font color="#990000">.</font></tt></pre> +</div></div> +<p>You can try this out by compiling and running the <code>tcp_echo</code> example in the examples directory. To do so, open a shell in the <em>examples/tcp_echo/</em> directory and run the following command:</p> +<div class="listingblock"><div class="title">Building and starting a Ranch example</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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 +<pre><tt>$ make run</tt></pre> +</div></div> +<p>You can then connect to it using telnet and see the echo server reply everything you send to it. Then when you're done testing, you can use the <code>Ctrl+]</code> key to escape to the telnet command line and type <code>quit</code> to exit.</p> +<div class="listingblock"><div class="title">Connecting to the example listener with telnet</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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"> +<pre><tt>$ telnet localhost <font color="#993399">5555</font> +Trying <font color="#993399">127.0</font><font color="#990000">.</font><font color="#993399">0.1</font><font color="#990000">...</font> +Connected to localhost<font color="#990000">.</font> +Escape character is <font color="#FF0000">'^]'</font><font color="#990000">.</font> +Hello<font color="#990000">!</font> +Hello<font color="#990000">!</font> +It works<font color="#990000">!</font> +It works<font color="#990000">!</font> +<font color="#990000">^]</font> + +telnet<font color="#990000">></font> quit +Connection closed<font color="#990000">.</font></tt></pre> +</div></div> <h2 id="_stopping_a_listener">Stopping a listener</h2> -<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 +<p>All you need to stop a Ranch listener is to call the <code>ranch:stop_listener/1</code> function with the listener's name as argument. In the previous section we started the listener named <code>tcp_echo</code>. We can now stop it.</p> +<div class="listingblock"><div class="title">Stopping a listener</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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"> +<pre><tt><b><font color="#000000">ranch:stop_listener</font></b>(<font color="#FF6600">tcp_echo</font>)<font color="#990000">.</font></tt></pre> +</div></div> <h2 id="_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"> +<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> +<p>It will also set <code>{backlog, 1024}</code> and <code>{nodelay, true}</code>, which can be overriden at listener startup.</p> <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 +<p>You do not have to specify a specific port to listen on. If you give the port number 0, or if you omit the port number entirely, Ranch will start listening on a random port.</p> +<p>You can retrieve this port number by calling <code>ranch:get_port/1</code>. The argument is the name of the listener you gave in <code>ranch:start_listener/6</code>.</p> +<div class="listingblock"><div class="title">Starting a listener for TCP connections on a random port</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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"> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">tcp_echo</font>, <font color="#993399">100</font>, + <font color="#FF6600">ranch_tcp</font>, [{<font color="#FF6600">port</font>, <font color="#993399">0</font>}], + <font color="#FF6600">echo_protocol</font>, [] +)<font color="#990000">.</font> +<font color="#009900">Port</font> <font color="#990000">=</font> <b><font color="#000000">ranch:get_port</font></b>(<font color="#FF6600">tcp_echo</font>)<font color="#990000">.</font></tt></pre> +</div></div> <h2 id="_listening_on_privileged_ports">Listening on privileged ports</h2> -<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"> +<p>Some systems limit access to ports below 1024 for security reasons. This can easily be identified by an <code>{error, eacces}</code> error when trying to open a listening socket on such a port.</p> +<p>The methods for listening on privileged ports vary between systems, please refer to your system's documentation for more information.</p> +<p>We recommend the use of port rewriting for systems with a single server, and load balancing for systems with multiple servers. Documenting these solutions is however out of the scope of this guide.</p> <h2 id="_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"> +<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> +<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> <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 +<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 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 +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">tcp_echo</font>, <font color="#993399">100</font>, + <font color="#FF6600">ranch_tcp</font>, [{<font color="#FF6600">port</font>, <font color="#993399">5555</font>}, {<font color="#FF6600">max_connections</font>, <font color="#993399">100</font>}], + <font color="#FF6600">echo_protocol</font>, [] +)<font color="#990000">.</font></tt></pre> +</div></div> +<p>You can disable this limit by setting its value to the atom <code>infinity</code>.</p> +<div class="listingblock"><div class="title">Disabling the limit for the number of connections</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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 +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">tcp_echo</font>, <font color="#993399">100</font>, + <font color="#FF6600">ranch_tcp</font>, [{<font color="#FF6600">port</font>, <font color="#993399">5555</font>}, {<font color="#FF6600">max_connections</font>, <font color="#FF6600">infinity</font>}], + <font color="#FF6600">echo_protocol</font>, [] +)<font color="#990000">.</font></tt></pre> +</div></div> +<p>You may not always want connections to be counted when checking for <code>max_connections</code>. For example you might have a protocol where both short-lived and long-lived connections are possible. If the long-lived connections are mostly waiting for messages, then they don't consume much resources and can safely be removed from the count.</p> +<p>To remove the connection from the count, you must call the <code>ranch:remove_connection/1</code> from within the connection process, with the name of the listener as the only argument.</p> +<div class="listingblock"><div class="title">Removing a connection from the count of connections</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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 +<pre><tt><b><font color="#000000">ranch:remove_connection</font></b>(<font color="#009900">Ref</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>As seen in the chapter covering protocols, this pid is received as the first argument of the protocol's <code>start_link/4</code> callback.</p> +<p>You can modify the <code>max_connections</code> value on a running listener by using the <code>ranch:set_max_connections/2</code> function, with the name of the listener as first argument and the new value as the second.</p> +<div class="listingblock"><div class="title">Upgrading the maximum number of connections</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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"> +<pre><tt><b><font color="#000000">ranch:set_max_connections</font></b>(<font color="#FF6600">tcp_echo</font>, <font color="#009900">MaxConns</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>The change will occur immediately.</p> <h2 id="_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"> +<p>Ranch allows you to define the type of process that will be used for the connection processes. By default it expects a <code>worker</code>. When the <code>connection_type</code> configuration value is set to <code>supervisor</code>, Ranch will consider that the connection process it manages is a supervisor and will reflect that in its supervision tree.</p> +<p>Connection processes of type <code>supervisor</code> can either handle the socket directly or through one of their children. In the latter case the start function for the connection process must return two pids: the pid of the supervisor you created (that will be supervised) and the pid of the protocol handling process (that will receive the socket).</p> +<p>Instead of returning <code>{ok, ConnPid}</code>, simply return <code>{ok, SupPid, ConnPid}</code>.</p> +<p>It is very important that the connection process be created under the supervisor process so that everything works as intended. If not, you will most likely experience issues when the supervised process is stopped.</p> <h2 id="_upgrading">Upgrading</h2> -<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 +<p>Ranch allows you to upgrade the protocol options. This takes effect immediately and for all subsequent connections.</p> +<p>To upgrade the protocol options, call <code>ranch:set_protocol_options/2</code> with the name of the listener as first argument and the new options as the second.</p> +<div class="listingblock"><div class="title">Upgrading the protocol options</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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 +<pre><tt><b><font color="#000000">ranch:set_protocol_options</font></b>(<font color="#FF6600">tcp_echo</font>, <font color="#009900">NewOpts</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>All future connections will use the new options.</p> +<p>You can also retrieve the current options similarly by calling <code>ranch:get_protocol_options/1</code>.</p> +<div class="listingblock"><div class="title">Retrieving the current protocol options</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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> +<pre><tt><font color="#009900">Opts</font> <font color="#990000">=</font> <b><font color="#000000">ranch:get_protocol_options</font></b>(<font color="#FF6600">tcp_echo</font>)<font color="#990000">.</font></tt></pre> +</div></div> + @@ -399,6 +280,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/ranch/1.5/guide">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> diff --git a/docs/en/ranch/1.2/guide/parsers/index.html b/docs/en/ranch/1.2/guide/parsers/index.html index f9f1ac5e..9891fde2 100644 --- a/docs/en/ranch/1.2/guide/parsers/index.html +++ b/docs/en/ranch/1.2/guide/parsers/index.html @@ -62,109 +62,69 @@ <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> +<p>There are three kinds of protocols:</p> +<ul><li>Text protocols </li> -<li> -<p> -Schema-less binary protocols -</p> +<li>Schema-less binary protocols </li> -<li> -<p> -Schema-based binary protocols -</p> +<li>Schema-based binary protocols </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"> +</ul> +<p>This chapter introduces the first two kinds. It will not cover more advanced topics such as continuations or parser generators.</p> +<p>This chapter isn't specifically about Ranch, we assume here that you know how to read data from the socket. The data you read and the data that hasn't been parsed is saved in a buffer. Every time you read from the socket, the data read is appended to the buffer. What happens next depends on the kind of protocol. We will only cover the first two.</p> <h2 id="_parsing_text">Parsing text</h2> -<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 +<p>Text protocols are generally line based. This means that we can't do anything with them until we receive the full line.</p> +<p>A simple way to get a full line is to use <code>binary:split/{2,3}</code>.</p> +<div class="listingblock"><div class="title">Using binary:split/2 to get a line of input</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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 +<pre><tt><b><font color="#0000FF">case</font></b> <b><font color="#000000">binary:split</font></b>(<font color="#009900">Buffer</font>, <font color="#990000"><<</font><font color="#FF0000">"\n"</font><font color="#990000">>></font>) <b><font color="#0000FF">of</font></b> + [<font color="#990000">_</font>] <font color="#990000">-></font> + <b><font color="#000000">get_more_data</font></b>(<font color="#009900">Buffer</font>); + [<font color="#009900">Line</font>, <font color="#009900">Rest</font>] <font color="#990000">-></font> + <b><font color="#000000">handle_line</font></b>(<font color="#009900">Line</font>, <font color="#009900">Rest</font>) +<b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<p>In the above example, we can have two results. Either there was a line break in the buffer and we get it split into two parts, the line and the rest of the buffer; or there was no line break in the buffer and we need to get more data from the socket.</p> +<p>Next, we need to parse the line. The simplest way is to again split, here on space. The difference is that we want to split on all spaces character, as we want to tokenize the whole string.</p> +<div class="listingblock"><div class="title">Using binary:split/3 to split text</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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"> +<pre><tt><b><font color="#0000FF">case</font></b> <b><font color="#000000">binary:split</font></b>(<font color="#009900">Line</font>, <font color="#990000"><<</font><font color="#FF0000">" "</font><font color="#990000">>></font>, [<font color="#FF6600">global</font>]) <b><font color="#0000FF">of</font></b> + [<font color="#990000"><<</font><font color="#FF0000">"HELLO"</font><font color="#990000">>></font>] <font color="#990000">-></font> + <b><font color="#000000">be_polite</font></b>(); + [<font color="#990000"><<</font><font color="#FF0000">"AUTH"</font><font color="#990000">>></font>, <font color="#009900">User</font>, <font color="#009900">Password</font>] <font color="#990000">-></font> + <b><font color="#000000">authenticate_user</font></b>(<font color="#009900">User</font>, <font color="#009900">Password</font>); + [<font color="#990000"><<</font><font color="#FF0000">"QUIT"</font><font color="#990000">>></font>, <font color="#009900">Reason</font>] <font color="#990000">-></font> + <b><font color="#000000">quit</font></b>(<font color="#009900">Reason</font>) + <i><font color="#9A1900">%% ...</font></i> +<b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<p>Pretty simple, right? Match on the command name, get the rest of the tokens in variables and call the respective functions.</p> +<p>After doing this, you will want to check if there is another line in the buffer, and handle it immediately if any. Otherwise wait for more data.</p> <h2 id="_parsing_binary">Parsing binary</h2> -<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 +<p>Binary protocols can be more varied, although most of them are pretty similar. The first four bytes of a frame tend to be the size of the frame, which is followed by a certain number of bytes for the type of frame and then various parameters.</p> +<p>Sometimes the size of the frame includes the first four bytes, sometimes not. Other times this size is encoded over two bytes. And even other times little-endian is used instead of big-endian.</p> +<p>The general idea stays the same though.</p> +<div class="listingblock"><div class="title">Using binary pattern matching to split frames</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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> +<pre><tt><font color="#990000"><<</font> <font color="#009900">Size</font><font color="#990000">:</font><font color="#993399">32</font>, <font color="#990000">_/</font><font color="#FF6600">bits</font> <font color="#990000">>></font> <font color="#990000">=</font> <font color="#009900">Buffer</font>, +<b><font color="#0000FF">case</font></b> <font color="#009900">Buffer</font> <b><font color="#0000FF">of</font></b> + <font color="#990000"><<</font> <font color="#009900">Frame</font><font color="#990000">:</font><font color="#009900">Size</font><font color="#990000">/</font><b><font color="#000080">binary</font></b>, <font color="#009900">Rest</font><font color="#990000">/</font><font color="#FF6600">bits</font> <font color="#990000">>></font> <font color="#990000">-></font> + <b><font color="#000000">handle_frame</font></b>(<font color="#009900">Frame</font>, <font color="#009900">Rest</font>); + <font color="#990000">_</font> <font color="#990000">-></font> + <b><font color="#000000">get_more_data</font></b>(<font color="#009900">Buffer</font>) +<b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<p>You will then need to parse this frame using binary pattern matching, and handle it. Then you will want to check if there is another frame fully received in the buffer, and handle it immediately if any. Otherwise wait for more data.</p> + @@ -221,6 +181,8 @@ immediately if any. Otherwise wait for more data.</p></div> + <li><a href="/docs/en/ranch/1.5/guide">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> diff --git a/docs/en/ranch/1.2/guide/protocols/index.html b/docs/en/ranch/1.2/guide/protocols/index.html index 950615b5..901a0770 100644 --- a/docs/en/ranch/1.2/guide/protocols/index.html +++ b/docs/en/ranch/1.2/guide/protocols/index.html @@ -62,129 +62,98 @@ <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"> +<p>A protocol handler starts a connection process and defines the protocol logic executed in this process.</p> <h2 id="_writing_a_protocol_handler">Writing a protocol handler</h2> -<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 +<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> +<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 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 +<pre><tt><font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:accept_ack</font></b>(<font color="#009900">Ref</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>If your protocol code requires specific socket options, you should set them while initializing your connection process, after calling <code>ranch:accept_ack/1</code>. You can use <code>Transport:setopts/2</code> for that purpose.</p> +<p>Following is the complete protocol code for the example found in <code>examples/tcp_echo/</code>.</p> +<div class="listingblock"><div class="title">Protocol module that echoes everything it receives</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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"> +<pre><tt><b><font color="#000080">-module</font></b>(<font color="#FF6600">echo_protocol</font>)<font color="#990000">.</font> +<b><font color="#000080">-behaviour</font></b>(<font color="#FF6600">ranch_protocol</font>)<font color="#990000">.</font> + +<b><font color="#000080">-export</font></b>([<b><font color="#000000">start_link</font></b><font color="#990000">/</font><font color="#993399">4</font>])<font color="#990000">.</font> +<b><font color="#000080">-export</font></b>([<b><font color="#000000">init</font></b><font color="#990000">/</font><font color="#993399">4</font>])<font color="#990000">.</font> + +<b><font color="#000000">start_link</font></b>(<font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>, <font color="#009900">Opts</font>) <font color="#990000">-></font> + <font color="#009900">Pid</font> <font color="#990000">=</font> <b><font color="#000080">spawn_link</font></b>(<b><font color="#000080">?MODULE</font></b>, <font color="#FF6600">init</font>, [<font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>, <font color="#009900">Opts</font>]), + {<font color="#FF6600">ok</font>, <font color="#009900">Pid</font>}<font color="#990000">.</font> + +<b><font color="#000000">init</font></b>(<font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>, <font color="#009900">_Opts</font> <font color="#990000">=</font> []) <font color="#990000">-></font> + <font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:accept_ack</font></b>(<font color="#009900">Ref</font>), + <b><font color="#000000">loop</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Transport</font>)<font color="#990000">.</font> + +<b><font color="#000000">loop</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Transport</font>) <font color="#990000">-></font> + <b><font color="#0000FF">case</font></b> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">recv</font></b>(<font color="#009900">Socket</font>, <font color="#993399">0</font>, <font color="#993399">5000</font>) <b><font color="#0000FF">of</font></b> + {<font color="#FF6600">ok</font>, <font color="#009900">Data</font>} <font color="#990000">-></font> + <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Data</font>), + <b><font color="#000000">loop</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Transport</font>); + <font color="#990000">_</font> <font color="#990000">-></font> + <font color="#0000FF">ok</font> <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">close</font></b>(<font color="#009900">Socket</font>) + <b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> <h2 id="_using_gen_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 +<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> +<p>There are two ways of solving this problem.</p> +<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 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 +<pre><tt><b><font color="#000080">-module</font></b>(<font color="#FF6600">my_protocol</font>)<font color="#990000">.</font> +<b><font color="#000080">-behaviour</font></b>(<font color="#FF6600">gen_server</font>)<font color="#990000">.</font> +<b><font color="#000080">-behaviour</font></b>(<font color="#FF6600">ranch_protocol</font>)<font color="#990000">.</font> + +<b><font color="#000080">-export</font></b>([<b><font color="#000000">start_link</font></b><font color="#990000">/</font><font color="#993399">4</font>])<font color="#990000">.</font> +<b><font color="#000080">-export</font></b>([<b><font color="#000000">init</font></b><font color="#990000">/</font><font color="#993399">4</font>])<font color="#990000">.</font> +<i><font color="#9A1900">%% Exports of other gen_server callbacks here.</font></i> + +<b><font color="#000000">start_link</font></b>(<font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>, <font color="#009900">Opts</font>) <font color="#990000">-></font> + <b><font color="#000000">proc_lib:start_link</font></b>(<b><font color="#000080">?MODULE</font></b>, <font color="#FF6600">init</font>, [<font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>, <font color="#009900">Opts</font>])<font color="#990000">.</font> + +<b><font color="#000000">init</font></b>(<font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>, <font color="#009900">_Opts</font> <font color="#990000">=</font> []) <font color="#990000">-></font> + <font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">proc_lib:init_ack</font></b>({<font color="#FF6600">ok</font>, <b><font color="#000080">self</font></b>()}), + <i><font color="#9A1900">%% Perform any required state initialization here.</font></i> + <font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:accept_ack</font></b>(<font color="#009900">Ref</font>), + <font color="#0000FF">ok</font> <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">setopts</font></b>(<font color="#009900">Socket</font>, [{<font color="#FF6600">active</font>, <font color="#FF6600">once</font>}]), + <b><font color="#000000">gen_server:enter_loop</font></b>(<b><font color="#000080">?MODULE</font></b>, [], {<font color="#FF6600">state</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>})<font color="#990000">.</font> + +<i><font color="#9A1900">%% Other gen_server callbacks here.</font></i></tt></pre> +</div></div> +<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 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> +<pre><tt><b><font color="#000080">-module</font></b>(<font color="#FF6600">my_protocol</font>)<font color="#990000">.</font> +<b><font color="#000080">-behaviour</font></b>(<font color="#FF6600">gen_server</font>)<font color="#990000">.</font> +<b><font color="#000080">-behaviour</font></b>(<font color="#FF6600">ranch_protocol</font>)<font color="#990000">.</font> -<span style="font-style: italic"><span style="color: #9A1900">%% Exports go here.</span></span> +<i><font color="#9A1900">%% Exports go here.</font></i> -<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> +<b><font color="#000000">init</font></b>([<font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>]) <font color="#990000">-></font> + {<font color="#FF6600">ok</font>, {<font color="#FF6600">state</font>, <font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>}, <font color="#993399">0</font>}<font color="#990000">.</font> + +<b><font color="#000000">handle_info</font></b>(<font color="#FF6600">timeout</font>, <font color="#009900">State</font><font color="#990000">=</font>{<font color="#FF6600">state</font>, <font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>}) <font color="#990000">-></font> + <font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:accept_ack</font></b>(<font color="#009900">Ref</font>), + <font color="#0000FF">ok</font> <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">setopts</font></b>(<font color="#009900">Socket</font>, [{<font color="#FF6600">active</font>, <font color="#FF6600">once</font>}]), + {<font color="#FF6600">noreply</font>, <font color="#009900">State</font>}; +<i><font color="#9A1900">%% ...</font></i></tt></pre> +</div></div> -<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> @@ -241,6 +210,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/ranch/1.5/guide">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> 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 498c719a..2a0d3b35 100644 --- a/docs/en/ranch/1.2/guide/ssl_auth/index.html +++ b/docs/en/ranch/1.2/guide/ssl_auth/index.html @@ -62,158 +62,82 @@ <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"> +<p>SSL client authentication is a mechanism allowing applications to identify certificates. This allows your application to make sure that the client is an authorized certificate, but makes no claim about whether the user can be trusted. This can be combined with a password based authentication to attain greater security.</p> +<p>The server only needs to retain the certificate serial number and the certificate issuer to authenticate the certificate. Together, they can be used to uniquely identify a certicate.</p> +<p>As Ranch allows the same protocol code to be used for both SSL and non-SSL transports, you need to make sure you are in an SSL context before attempting to perform an SSL client authentication. This can be done by checking the return value of <code>Transport:name/0</code>.</p> <h2 id="_obtaining_client_certificates">Obtaining client certificates</h2> -<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> +<p>You can obtain client certificates from various sources. You can generate them yourself, or you can use a service like CAcert.org which allows you to generate client and server certificates for free.</p> +<p>Following are the steps you need to take to create a CAcert.org account, generate a certificate and install it in your favorite browser.</p> +<ul><li>Open [CAcert.org](<a href="http://cacert.org)">http://cacert.org)</a> in your favorite browser </li> -<li> -<p> -Root Certificate link: install both certificates -</p> +<li>Root Certificate link: install both certificates </li> -<li> -<p> -Join (Register an account) -</p> +<li>Join (Register an account) </li> -<li> -<p> -Verify your account (check your email inbox!) -</p> +<li>Verify your account (check your email inbox!) </li> -<li> -<p> -Log in -</p> +<li>Log in </li> -<li> -<p> -Client Certificates: New -</p> +<li>Client Certificates: New </li> -<li> -<p> -Follow instructions to create the certificate -</p> +<li>Follow instructions to create the certificate </li> -<li> -<p> -Install the certificate in your browser -</p> +<li>Install the certificate in your browser </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"> +</ul> +<p>You can optionally save the certificate for later use, for example to extract the <code>IssuerID</code> information as will be detailed later on.</p> <h2 id="_transport_configuration">Transport configuration</h2> -<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 +<p>The SSL transport does not request a client certificate by default. You need to specify the <code>{verify, verify_peer}</code> option when starting the listener to enable this behavior.</p> +<div class="listingblock"><div class="title">Configure a listener for SSL authentication</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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"> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">my_ssl</font>, <font color="#993399">100</font>, + <font color="#FF6600">ranch_ssl</font>, [ + {<font color="#FF6600">port</font>, <font color="#009900">SSLPort</font>}, + {<font color="#FF6600">certfile</font>, <font color="#009900">PathToCertfile</font>}, + {<font color="#FF6600">cacertfile</font>, <font color="#009900">PathToCACertfile</font>}, + {<font color="#FF6600">verify</font>, <font color="#FF6600">verify_peer</font>} + ], + <font color="#FF6600">my_protocol</font>, [] +)<font color="#990000">.</font></tt></pre> +</div></div> +<p>In this example we set the required <code>port</code> and <code>certfile</code>, but also the <code>cacertfile</code> containing the CACert.org root certificate, and the option to request the client certificate.</p> +<p>If you enable the <code>{verify, verify_peer}</code> option and the client does not have a client certificate configured for your domain, then no certificate will be sent. This allows you to use SSL for more than just authenticated clients.</p> <h2 id="_authentication">Authentication</h2> -<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 +<p>To authenticate users, you must first save the certificate information required. If you have your users' certificate files, you can simply load the certificate and retrieve the information directly.</p> +<div class="listingblock"><div class="title">Retrieve the issuer ID from a certificate</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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 +<pre><tt><b><font color="#000000">certfile_to_issuer_id</font></b>(<font color="#009900">Filename</font>) <font color="#990000">-></font> + {<font color="#FF6600">ok</font>, <font color="#009900">Data</font>} <font color="#990000">=</font> <b><font color="#000000">file:read_file</font></b>(<font color="#009900">Filename</font>), + [{<font color="#FF6600">'Certificate'</font>, <font color="#009900">Cert</font>, <font color="#FF6600">not_encrypted</font>}] <font color="#990000">=</font> <b><font color="#000000">public_key:pem_decode</font></b>(<font color="#009900">Data</font>), + {<font color="#FF6600">ok</font>, <font color="#009900">IssuerID</font>} <font color="#990000">=</font> <b><font color="#000000">public_key:pkix_issuer_id</font></b>(<font color="#009900">Cert</font>, <b><font color="#000080">self</font></b>), + <font color="#009900">IssuerID</font><font color="#990000">.</font></tt></pre> +</div></div> +<p>The <code>IssuerID</code> variable contains both the certificate serial number and the certificate issuer stored in a tuple, so this value alone can be used to uniquely identify the user certificate. You can save this value in a database, a configuration file or any other place where an Erlang term can be stored and retrieved.</p> +<p>To retrieve the <code>IssuerID</code> from a running connection, you need to first retrieve the client certificate and then extract this information from it. Ranch does not provide a function to retrieve the client certificate. Instead you can use the <code>ssl:peercert/1</code> function. Once you have the certificate, you can again use the <code>public_key:pkix_issuer_id/2</code> to extract the <code>IssuerID</code> value.</p> +<p>The following function returns the <code>IssuerID</code> or <code>false</code> if no client certificate was found. This snippet is intended to be used from your protocol code.</p> +<div class="listingblock"><div class="title">Retrieve the issuer ID from the certificate for the current connection</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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> +<pre><tt><b><font color="#000000">socket_to_issuer_id</font></b>(<font color="#009900">Socket</font>) <font color="#990000">-></font> + <b><font color="#0000FF">case</font></b> <b><font color="#000000">ssl:peercert</font></b>(<font color="#009900">Socket</font>) <b><font color="#0000FF">of</font></b> + {<font color="#FF6600">error</font>, <font color="#FF6600">no_peercert</font>} <font color="#990000">-></font> + <font color="#000080">false</font>; + {<font color="#FF6600">ok</font>, <font color="#009900">Cert</font>} <font color="#990000">-></font> + {<font color="#FF6600">ok</font>, <font color="#009900">IssuerID</font>} <font color="#990000">=</font> <b><font color="#000000">public_key:pkix_issuer_id</font></b>(<font color="#009900">Cert</font>, <b><font color="#000080">self</font></b>), + <font color="#009900">IssuerID</font> + <b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<p>You then only need to match the <code>IssuerID</code> value to authenticate the user.</p> + @@ -270,6 +194,8 @@ user.</p></div> + <li><a href="/docs/en/ranch/1.5/guide">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> diff --git a/docs/en/ranch/1.2/guide/transports/index.html b/docs/en/ranch/1.2/guide/transports/index.html index 91e2d4d6..3ced83c7 100644 --- a/docs/en/ranch/1.2/guide/transports/index.html +++ b/docs/en/ranch/1.2/guide/transports/index.html @@ -62,189 +62,114 @@ <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"> +<p>A transport defines the interface to interact with a socket.</p> +<p>Transports can be used for connecting, listening and accepting connections, but also for receiving and sending data. Both passive and active mode are supported, although all sockets are initialized as passive.</p> <h2 id="_tcp_transport">TCP transport</h2> -<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"> +<p>The TCP transport is a thin wrapper around <code>gen_tcp</code>.</p> <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 +<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 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"> +<pre><tt><b><font color="#000000">ssl:start</font></b>()<font color="#990000">.</font></tt></pre> +</div></div> +<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> +<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> <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 +<p>This section assumes that <code>Transport</code> is a valid transport handler (like <code>ranch_tcp</code> or <code>ranch_ssl</code>) and <code>Socket</code> is a connected socket obtained through the listener.</p> +<p>You can send data to a socket by calling the <code>Transport:send/2</code> function. The data can be given as <code>iodata()</code>, which is defined as <code>binary() | iolist()</code>. All the following calls will work:</p> +<div class="listingblock"><div class="title">Sending data to the socket</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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 +<pre><tt><font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, <font color="#990000"><<</font><font color="#FF0000">"Ranch is cool!"</font><font color="#990000">>></font>)<font color="#990000">.</font> +<font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, <font color="#FF0000">"Ranch is cool!"</font>)<font color="#990000">.</font> +<font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, [<font color="#FF0000">"Ranch"</font>, [<font color="#FF0000">"is"</font>, <font color="#FF0000">"cool!"</font>]])<font color="#990000">.</font> +<font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, [<font color="#FF0000">"Ranch"</font>, [<font color="#990000"><<</font><font color="#FF0000">"is"</font><font color="#990000">>></font>, <font color="#FF0000">"cool!"</font>]])<font color="#990000">.</font></tt></pre> +</div></div> +<p>You can receive data either in passive or in active mode. Passive mode means that you will perform a blocking <code>Transport:recv/3</code> call, while active mode means that you will receive the data as a message.</p> +<p>By default, all data will be received as binary. It is possible to receive data as strings, although this is not recommended as binaries are a more efficient construct, especially for binary protocols.</p> +<p>Receiving data using passive mode requires a single function call. The first argument is the socket, and the third argument is a timeout duration before the call returns with <code>{error, timeout}</code>.</p> +<p>The second argument is the amount of data in bytes that we want to receive. The function will wait for data until it has received exactly this amount. If you are not expecting a precise size, you can specify 0 which will make this call return as soon as data was read, regardless of its size.</p> +<div class="listingblock"><div class="title">Receiving data from the socket in passive mode</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#009900">Data</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">recv</font></b>(<font color="#009900">Socket</font>, <font color="#993399">0</font>, <font color="#993399">5000</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>Active mode requires you to inform the socket that you want to receive data as a message and to write the code to actually receive it.</p> +<p>There are 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> +<p>Three different messages can be received:</p> +<ul><li><code>{OK, Socket, Data}</code> </li> -<li> -<p> -<code>{Closed, Socket}</code> -</p> +<li><code>{Closed, Socket}</code> </li> -<li> -<p> -<code>{Error, Socket, Reason}</code> -</p> +<li><code>{Error, Socket, Reason}</code> </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 +</ul> +<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 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 +<pre><tt>{<font color="#009900">OK</font>, <font color="#009900">Closed</font>, <font color="#009900">Error</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">messages</font></b>()<font color="#990000">.</font></tt></pre> +</div></div> +<p>To start receiving messages you will need to call the <code>Transport:setopts/2</code> function, and do so every time you want to receive data.</p> +<div class="listingblock"><div class="title">Receiving messages from the socket in active mode</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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"> +<pre><tt>{<font color="#009900">OK</font>, <font color="#009900">Closed</font>, <font color="#009900">Error</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">messages</font></b>(), +<font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">setopts</font></b>(<font color="#009900">Socket</font>, [{<font color="#FF6600">active</font>, <font color="#FF6600">once</font>}]), +<b><font color="#0000FF">receive</font></b> + {<font color="#009900">OK</font>, <font color="#009900">Socket</font>, <font color="#009900">Data</font>} <font color="#990000">-></font> + <b><font color="#000000">io:format</font></b>(<font color="#FF0000">"data received: ~p~n"</font>, [<font color="#009900">Data</font>]); + {<font color="#009900">Closed</font>, <font color="#009900">Socket</font>} <font color="#990000">-></font> + <b><font color="#000000">io:format</font></b>(<font color="#FF0000">"socket got closed!~n"</font>); + {<font color="#009900">Error</font>, <font color="#009900">Socket</font>, <font color="#009900">Reason</font>} <font color="#990000">-></font> + <b><font color="#000000">io:format</font></b>(<font color="#FF0000">"error happened: ~p~n"</font>, [<font color="#009900">Reason</font>]) +<b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<p>You can easily integrate active sockets with existing Erlang code as all you really need is just a few more clauses when receiving messages.</p> <h2 id="_sending_files">Sending files</h2> -<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 +<p>As in the previous section it is assumed <code>Transport</code> is a valid transport handler and <code>Socket</code> is a connected socket obtained through the listener.</p> +<p>To send a whole file, with name <code>Filename</code>, over a socket:</p> +<div class="listingblock"><div class="title">Sending a file by filename</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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 +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#009900">SentBytes</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">sendfile</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Filename</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>Or part of a file, with <code>Offset</code> greater than or equal to 0, <code>Bytes</code> number of bytes and chunks of size <code>ChunkSize</code>:</p> +<div class="listingblock"><div class="title">Sending part of a file by filename in chunks</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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 +<pre><tt><font color="#009900">Opts</font> <font color="#990000">=</font> [{<font color="#FF6600">chunk_size</font>, <font color="#009900">ChunkSize</font>}], +{<font color="#FF6600">ok</font>, <font color="#009900">SentBytes</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">sendfile</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Filename</font>, <font color="#009900">Offset</font>, <font color="#009900">Bytes</font>, <font color="#009900">Opts</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>To improve efficiency when sending multiple parts of the same file it is also possible to use a file descriptor opened in raw mode:</p> +<div class="listingblock"><div class="title">Sending a file opened in raw mode</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.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"> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#009900">RawFile</font>} <font color="#990000">=</font> <b><font color="#000000">file:open</font></b>(<font color="#009900">Filename</font>, [<font color="#FF6600">raw</font>, <font color="#FF6600">read</font>, <b><font color="#000080">binary</font></b>]), +{<font color="#FF6600">ok</font>, <font color="#009900">SentBytes</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">sendfile</font></b>(<font color="#009900">Socket</font>, <font color="#009900">RawFile</font>, <font color="#009900">Offset</font>, <font color="#009900">Bytes</font>, <font color="#009900">Opts</font>)<font color="#990000">.</font></tt></pre> +</div></div> <h2 id="_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> +<p>A transport handler is a module implementing the <code>ranch_transport</code> behavior. It defines a certain number of callbacks that must be written in order to allow transparent usage of the transport handler.</p> +<p>The behavior doesn't define the socket options available when opening a socket. These do not need to be common to all transports as it's easy enough to write different initialization functions for the different transports that will be used. With one exception though. The <code>setopts/2</code> function <strong>must</strong> implement the <code>{active, once}</code> and the <code>{active, true}</code> options.</p> +<p>If the transport handler doesn't have a native implementation of <code>sendfile/5</code> a fallback is available, <code>ranch_transport:sendfile/6</code>. The extra first argument is the transport's module. See <code>ranch_ssl</code> for an example.</p> + @@ -301,6 +226,8 @@ is the transport’s module. See <code>ranch_ssl</code> for an example.</p>< + <li><a href="/docs/en/ranch/1.5/guide">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> diff --git a/docs/en/ranch/1.2/manual/index.html b/docs/en/ranch/1.2/manual/index.html index 4d379ce7..91c0a3c5 100644 --- a/docs/en/ranch/1.2/manual/index.html +++ b/docs/en/ranch/1.2/manual/index.html @@ -62,38 +62,20 @@ <h1 class="lined-header"><span>Ranch Function Reference</span></h1> -<div class="ulist"><ul> -<li> -<p> -<a href="ranch_app">ranch(7)</a> -</p> +<ul><li><a href="ranch_app">ranch(7)</a> </li> -<li> -<p> -<a href="ranch">ranch(3)</a> -</p> +<li><a href="ranch">ranch(3)</a> </li> -<li> -<p> -<a href="ranch_protocol">ranch_protocol(3)</a> -</p> +<li><a href="ranch_protocol">ranch_protocol(3)</a> </li> -<li> -<p> -<a href="ranch_ssl">ranch_ssl(3)</a> -</p> +<li><a href="ranch_ssl">ranch_ssl(3)</a> </li> -<li> -<p> -<a href="ranch_tcp">ranch_tcp(3)</a> -</p> +<li><a href="ranch_tcp">ranch_tcp(3)</a> </li> -<li> -<p> -<a href="ranch_transport">ranch_transport(3)</a> -</p> +<li><a href="ranch_transport">ranch_transport(3)</a> </li> -</ul></div> +</ul> + @@ -128,6 +110,8 @@ + <li><a href="/docs/en/ranch/1.5/manual">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> diff --git a/docs/en/ranch/1.2/manual/ranch/index.html b/docs/en/ranch/1.2/manual/ranch/index.html index 3c45e2f2..edbdb353 100644 --- a/docs/en/ranch/1.2/manual/ranch/index.html +++ b/docs/en/ranch/1.2/manual/ranch/index.html @@ -62,423 +62,175 @@ <h1 class="lined-header"><span>ranch(3)</span></h1> -<div class="sect1"> <h2 id="_name">Name</h2> -<div class="sectionbody"> -<div class="paragraph"><p>ranch - socket acceptor pool</p></div> -</div> -</div> -<div class="sect1"> +<p>ranch - socket acceptor pool</p> <h2 id="_description">Description</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The <code>ranch</code> module provides functions for starting and -manipulating Ranch listeners.</p></div> -</div> -</div> -<div class="sect1"> +<p>The <code>ranch</code> module provides functions for starting and manipulating Ranch listeners.</p> <h2 id="_types">Types</h2> -<div class="sectionbody"> -<div class="sect2"> -<h3 id="_max_conns_non_neg_integer_infinity">max_conns() = non_neg_integer() | infinity</h3> -<div class="paragraph"><p>Maximum number of connections allowed on this listener.</p></div> -<div class="paragraph"><p>This is a soft limit. The actual number of connections -might be slightly above the limit due to concurrency -when accepting new connections. Some connections may -also be removed from this count explicitly by the user -code.</p></div> -</div> -<div class="sect2"> +<h3 id="_max_conns_____non_neg_integer_____infinity">max_conns() = non_neg_integer() | infinity</h3> +<p>Maximum number of connections allowed on this listener.</p> +<p>This is a soft limit. The actual number of connections might be slightly above the limit due to concurrency when accepting new connections. Some connections may also be removed from this count explicitly by the user code.</p> <h3 id="_opt">opt()</h3> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">ack_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()} - | {<span style="color: #FF6600">connection_type</span>, <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>} - | {<span style="color: #FF6600">max_connections</span>, <span style="font-weight: bold"><span style="color: #000000">max_conns</span></span>()} - | {<span style="color: #000080">shutdown</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>() | <span style="color: #FF6600">brutal_kill</span>} - | {<span style="color: #FF6600">socket</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> -<div class="paragraph"><p>Ranch-specific transport options.</p></div> -<div class="paragraph"><p>These options are not passed on to the transports. -They are used by Ranch while setting up the listeners.</p></div> -</div> -<div class="sect2"> -<h3 id="_ref_any">ref() = any()</h3> -<div class="paragraph"><p>Unique name used to refer to a listener.</p></div> -</div> -</div> -</div> -<div class="sect1"> +<pre><tt><b><font color="#000000">opt</font></b>() <font color="#990000">=</font> {<font color="#FF6600">ack_timeout</font>, <b><font color="#000000">timeout</font></b>()} + | {<font color="#FF6600">connection_type</font>, <font color="#FF6600">worker</font> | <font color="#FF6600">supervisor</font>} + | {<font color="#FF6600">max_connections</font>, <b><font color="#000000">max_conns</font></b>()} + | {<font color="#000080">shutdown</font>, <b><font color="#000000">timeout</font></b>() | <font color="#FF6600">brutal_kill</font>} + | {<font color="#FF6600">socket</font>, <b><font color="#000000">any</font></b>()}</tt></pre> +</div></div> +<p>Ranch-specific transport options.</p> +<p>These options are not passed on to the transports. They are used by Ranch while setting up the listeners.</p> +<h3 id="_ref_____any">ref() = any()</h3> +<p>Unique name used to refer to a listener.</p> <h2 id="_option_descriptions">Option descriptions</h2> -<div class="sectionbody"> -<div class="paragraph"><p>None of the options are required.</p></div> -<div class="dlist"><dl> -<dt class="hdlist1"> -ack_timeout (5000) -</dt> -<dd> -<p> - Maximum allowed time for the <code>ranch:accept_ack/1</code> call to finish. -</p> -</dd> -<dt class="hdlist1"> -connection_type (worker) -</dt> -<dd> -<p> - Type of process that will handle the connection. -</p> -</dd> -<dt class="hdlist1"> -max_connections (1024) -</dt> -<dd> -<p> - Maximum number of active connections. Soft limit. Using <code>infinity</code> will disable the limit entirely. -</p> -</dd> -<dt class="hdlist1"> -shutdown (5000) -</dt> -<dd> -<p> - Maximum allowed time for children to stop on listener shutdown. -</p> -</dd> -<dt class="hdlist1"> -socket -</dt> -<dd> -<p> - Listening socket opened externally to be used instead of calling <code>Transport:listen/1</code>. -</p> -</dd> -</dl></div> -</div> -</div> -<div class="sect1"> +<p>None of the options are required.</p> +<dl><dt>ack_timeout (5000)</dt> +<dd><p>Maximum allowed time for the <code>ranch:accept_ack/1</code> call to finish.</p> +</dd> +<dt>connection_type (worker)</dt> +<dd><p>Type of process that will handle the connection.</p> +</dd> +<dt>max_connections (1024)</dt> +<dd><p>Maximum number of active connections. Soft limit. Using <code>infinity</code> will disable the limit entirely.</p> +</dd> +<dt>shutdown (5000)</dt> +<dd><p>Maximum allowed time for children to stop on listener shutdown.</p> +</dd> +<dt>socket</dt> +<dd><p>Listening socket opened externally to be used instead of calling <code>Transport:listen/1</code>.</p> +</dd> +</dl> <h2 id="_exports">Exports</h2> -<div class="sectionbody"> -<div class="sect2"> -<h3 id="_accept_ack_ref_8594_ok">accept_ack(Ref) → ok</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Ref = ref() -</dt> -<dd> -<p> -Listener name. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Acknowledge that the connection is accepted.</p></div> -<div class="paragraph"><p>This function MUST be used by a connection process to inform -Ranch that it initialized properly and let it perform any -additional operations before the socket can be safely used.</p></div> -</div> -<div class="sect2"> -<h3 id="_child_spec_ref_nbacceptors_transport_transopts_protocol_protoopts_8594_supervisor_child_spec">child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → supervisor:child_spec()</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Ref = ref() -</dt> -<dd> -<p> -Listener name. -</p> -</dd> -<dt class="hdlist1"> -NbAcceptors = non_neg_integer() -</dt> -<dd> -<p> -Number of acceptor processes. -</p> -</dd> -<dt class="hdlist1"> -Transport = module() -</dt> -<dd> -<p> -Transport module. -</p> -</dd> -<dt class="hdlist1"> -TransOpts = any() -</dt> -<dd> -<p> -Transport options. -</p> -</dd> -<dt class="hdlist1"> -Protocol = module() -</dt> -<dd> -<p> -Protocol module. -</p> -</dd> -<dt class="hdlist1"> -ProtoOpts = any() -</dt> -<dd> -<p> -Protocol options. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Return child specifications for a new listener.</p></div> -<div class="paragraph"><p>This function can be used to embed a listener directly -in an application instead of letting Ranch handle it.</p></div> -</div> -<div class="sect2"> -<h3 id="_get_addr_ref_8594_ip_port">get_addr(Ref) → {IP, Port}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Ref = ref() -</dt> -<dd> -<p> -Listener name. -</p> -</dd> -<dt class="hdlist1"> -IP = inet:ip_address() -</dt> -<dd> -<p> -IP of the interface used by this listener. -</p> -</dd> -<dt class="hdlist1"> -Port = inet:port_number() -</dt> -<dd> -<p> -Port number used by this listener. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Return the IP address and port for the given listener.</p></div> -</div> -<div class="sect2"> -<h3 id="_get_max_connections_ref_8594_maxconns">get_max_connections(Ref) → MaxConns</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Ref = ref() -</dt> -<dd> -<p> -Listener name. -</p> -</dd> -<dt class="hdlist1"> -MaxConns = max_conns() -</dt> -<dd> -<p> -Current maximum number of connections. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Return the max number of connections allowed for the given listener.</p></div> -</div> -<div class="sect2"> -<h3 id="_get_port_ref_8594_port">get_port(Ref) → Port</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Ref = ref() -</dt> -<dd> -<p> -Listener name. -</p> -</dd> -<dt class="hdlist1"> -Port = inet:port_number() -</dt> -<dd> -<p> -Port number used by this listener. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Return the port for the given listener.</p></div> -</div> -<div class="sect2"> -<h3 id="_get_protocol_options_ref_8594_protoopts">get_protocol_options(Ref) → ProtoOpts</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Ref = ref() -</dt> -<dd> -<p> -Listener name. -</p> -</dd> -<dt class="hdlist1"> -ProtoOpts = any() -</dt> -<dd> -<p> -Current protocol options. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Return the protocol options set for the given listener.</p></div> -</div> -<div class="sect2"> -<h3 id="_remove_connection_ref_8594_ok">remove_connection(Ref) → ok</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Ref = ref() -</dt> -<dd> -<p> -Listener name. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Do not count this connection when limiting the number of connections.</p></div> -<div class="paragraph"><p>You can use this function for long-running connection processes -which spend most of their time idling rather than consuming -resources. This allows Ranch to accept a lot more connections -without sacrificing the latency of the system.</p></div> -<div class="paragraph"><p>This function may only be called from a connection process.</p></div> -</div> -<div class="sect2"> -<h3 id="_set_max_connections_ref_maxconns_8594_ok">set_max_connections(Ref, MaxConns) → ok</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Ref = ref() -</dt> -<dd> -<p> -Listener name. -</p> -</dd> -<dt class="hdlist1"> -MaxConns = max_conns() -</dt> -<dd> -<p> -New maximum number of connections. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Set the max number of connections for the given listener.</p></div> -<div class="paragraph"><p>The change will be applied immediately. If the new value is -smaller than the previous one, Ranch will not kill the extra -connections, but will wait for them to terminate properly.</p></div> -</div> -<div class="sect2"> -<h3 id="_set_protocol_options_ref_protoopts_8594_ok">set_protocol_options(Ref, ProtoOpts) → ok</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Ref = ref() -</dt> -<dd> -<p> -Listener name. -</p> -</dd> -<dt class="hdlist1"> -ProtoOpts = any() -</dt> -<dd> -<p> -New protocol options. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Set the protocol options for the given listener.</p></div> -<div class="paragraph"><p>The change will be applied immediately for all new connections. -Old connections will not receive the new options.</p></div> -</div> -<div class="sect2"> -<h3 id="_start_listener_ref_nbacceptors_transport_transopts_protocol_protoopts_8594_ok_pid_error_badarg">start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → {ok, pid()} | {error, badarg}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Ref = ref() -</dt> -<dd> -<p> -Listener name. -</p> -</dd> -<dt class="hdlist1"> -NbAcceptors = non_neg_integer() -</dt> -<dd> -<p> -Number of acceptor processes. -</p> -</dd> -<dt class="hdlist1"> -Transport = module() -</dt> -<dd> -<p> -Transport module. -</p> -</dd> -<dt class="hdlist1"> -TransOpts = any() -</dt> -<dd> -<p> -Transport options. -</p> -</dd> -<dt class="hdlist1"> -Protocol = module() -</dt> -<dd> -<p> -Protocol module. -</p> -</dd> -<dt class="hdlist1"> -ProtoOpts = any() -</dt> -<dd> -<p> -Protocol options. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Start listening for connections using the given transport -and protocol. Returns the pid for this listener’s supervisor.</p></div> -<div class="paragraph"><p>There are additional transport options that apply -regardless of transport. They allow configuring how the -connections are supervised, rate limited and more. Please -consult the previous section for more details.</p></div> -</div> -<div class="sect2"> -<h3 id="_stop_listener_ref_8594_ok_error_not_found">stop_listener(Ref) → ok | {error, not_found}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Ref = ref() -</dt> -<dd> -<p> -Listener name. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Stop the given listener.</p></div> -<div class="paragraph"><p>The listener is stopped gracefully, first by closing the -listening port, then by stopping the connection processes. -These processes are stopped according to the <code>shutdown</code> -transport option, which may be set to brutally kill all -connection processes or give them some time to stop properly.</p></div> -<div class="paragraph"><p>This function does not return until the listener is -completely stopped.</p></div> -</div> -</div> -</div> +<h3 id="_accept_ack_ref_____ok">accept_ack(Ref) -> ok</h3> +<dl><dt>Ref = ref()</dt> +<dd><p>Listener name.</p> +</dd> +</dl> +<p>Acknowledge that the connection is accepted.</p> +<p>This function MUST be used by a connection process to inform Ranch that it initialized properly and let it perform any additional operations before the socket can be safely used.</p> +<h3 id="_child_spec_ref__nbacceptors__transport__transopts__protocol__protoopts_____supervisor_child_spec">child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) -> supervisor:child_spec()</h3> +<dl><dt>Ref = ref()</dt> +<dd><p>Listener name.</p> +</dd> +<dt>NbAcceptors = non_neg_integer()</dt> +<dd><p>Number of acceptor processes.</p> +</dd> +<dt>Transport = module()</dt> +<dd><p>Transport module.</p> +</dd> +<dt>TransOpts = any()</dt> +<dd><p>Transport options.</p> +</dd> +<dt>Protocol = module()</dt> +<dd><p>Protocol module.</p> +</dd> +<dt>ProtoOpts = any()</dt> +<dd><p>Protocol options.</p> +</dd> +</dl> +<p>Return child specifications for a new listener.</p> +<p>This function can be used to embed a listener directly in an application instead of letting Ranch handle it.</p> +<h3 id="_get_addr_ref______ip__port">get_addr(Ref) -> {IP, Port}</h3> +<dl><dt>Ref = ref()</dt> +<dd><p>Listener name.</p> +</dd> +<dt>IP = inet:ip_address()</dt> +<dd><p>IP of the interface used by this listener.</p> +</dd> +<dt>Port = inet:port_number()</dt> +<dd><p>Port number used by this listener.</p> +</dd> +</dl> +<p>Return the IP address and port for the given listener.</p> +<h3 id="_get_max_connections_ref_____maxconns">get_max_connections(Ref) -> MaxConns</h3> +<dl><dt>Ref = ref()</dt> +<dd><p>Listener name.</p> +</dd> +<dt>MaxConns = max_conns()</dt> +<dd><p>Current maximum number of connections.</p> +</dd> +</dl> +<p>Return the max number of connections allowed for the given listener.</p> +<h3 id="_get_port_ref_____port">get_port(Ref) -> Port</h3> +<dl><dt>Ref = ref()</dt> +<dd><p>Listener name.</p> +</dd> +<dt>Port = inet:port_number()</dt> +<dd><p>Port number used by this listener.</p> +</dd> +</dl> +<p>Return the port for the given listener.</p> +<h3 id="_get_protocol_options_ref_____protoopts">get_protocol_options(Ref) -> ProtoOpts</h3> +<dl><dt>Ref = ref()</dt> +<dd><p>Listener name.</p> +</dd> +<dt>ProtoOpts = any()</dt> +<dd><p>Current protocol options.</p> +</dd> +</dl> +<p>Return the protocol options set for the given listener.</p> +<h3 id="_remove_connection_ref_____ok">remove_connection(Ref) -> ok</h3> +<dl><dt>Ref = ref()</dt> +<dd><p>Listener name.</p> +</dd> +</dl> +<p>Do not count this connection when limiting the number of connections.</p> +<p>You can use this function for long-running connection processes which spend most of their time idling rather than consuming resources. This allows Ranch to accept a lot more connections without sacrificing the latency of the system.</p> +<p>This function may only be called from a connection process.</p> +<h3 id="_set_max_connections_ref__maxconns_____ok">set_max_connections(Ref, MaxConns) -> ok</h3> +<dl><dt>Ref = ref()</dt> +<dd><p>Listener name.</p> +</dd> +<dt>MaxConns = max_conns()</dt> +<dd><p>New maximum number of connections.</p> +</dd> +</dl> +<p>Set the max number of connections for the given listener.</p> +<p>The change will be applied immediately. If the new value is smaller than the previous one, Ranch will not kill the extra connections, but will wait for them to terminate properly.</p> +<h3 id="_set_protocol_options_ref__protoopts_____ok">set_protocol_options(Ref, ProtoOpts) -> ok</h3> +<dl><dt>Ref = ref()</dt> +<dd><p>Listener name.</p> +</dd> +<dt>ProtoOpts = any()</dt> +<dd><p>New protocol options.</p> +</dd> +</dl> +<p>Set the protocol options for the given listener.</p> +<p>The change will be applied immediately for all new connections. Old connections will not receive the new options.</p> +<h3 id="_start_listener_ref__nbacceptors__transport__transopts__protocol__protoopts______ok__pid_______error__badarg">start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) -> {ok, pid()} | {error, badarg}</h3> +<dl><dt>Ref = ref()</dt> +<dd><p>Listener name.</p> +</dd> +<dt>NbAcceptors = non_neg_integer()</dt> +<dd><p>Number of acceptor processes.</p> +</dd> +<dt>Transport = module()</dt> +<dd><p>Transport module.</p> +</dd> +<dt>TransOpts = any()</dt> +<dd><p>Transport options.</p> +</dd> +<dt>Protocol = module()</dt> +<dd><p>Protocol module.</p> +</dd> +<dt>ProtoOpts = any()</dt> +<dd><p>Protocol options.</p> +</dd> +</dl> +<p>Start listening for connections using the given transport and protocol. Returns the pid for this listener's supervisor.</p> +<p>There are additional transport options that apply regardless of transport. They allow configuring how the connections are supervised, rate limited and more. Please consult the previous section for more details.</p> +<h3 id="_stop_listener_ref_____ok____error__not_found">stop_listener(Ref) -> ok | {error, not_found}</h3> +<dl><dt>Ref = ref()</dt> +<dd><p>Listener name.</p> +</dd> +</dl> +<p>Stop the given listener.</p> +<p>The listener is stopped gracefully, first by closing the listening port, then by stopping the connection processes. These processes are stopped according to the <code>shutdown</code> transport option, which may be set to brutally kill all connection processes or give them some time to stop properly.</p> +<p>This function does not return until the listener is completely stopped.</p> + @@ -513,6 +265,8 @@ completely stopped.</p></div> + <li><a href="/docs/en/ranch/1.5/manual">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> diff --git a/docs/en/ranch/1.2/manual/ranch_app/index.html b/docs/en/ranch/1.2/manual/ranch_app/index.html index 4e5e609c..fc27d096 100644 --- a/docs/en/ranch/1.2/manual/ranch_app/index.html +++ b/docs/en/ranch/1.2/manual/ranch_app/index.html @@ -62,43 +62,19 @@ <h1 class="lined-header"><span>ranch(7)</span></h1> -<div class="sect1"> <h2 id="_name">Name</h2> -<div class="sectionbody"> -<div class="paragraph"><p>ranch - Socket acceptor pool for TCP protocols.</p></div> -</div> -</div> -<div class="sect1"> +<p>ranch - Socket acceptor pool for TCP protocols.</p> <h2 id="_dependencies">Dependencies</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The <code>ranch</code> application has no particular dependency required -to start.</p></div> -<div class="paragraph"><p>It has optional dependencies that are only required when -listening for SSL connections. The dependencies are <code>crypto</code>, -<code>asn1</code>, <code>public_key</code> and <code>ssl</code>. They are started automatically -if they weren’t before.</p></div> -</div> -</div> -<div class="sect1"> +<p>The <code>ranch</code> application has no particular dependency required to start.</p> +<p>It has optional dependencies that are only required when listening for SSL connections. The dependencies are <code>crypto</code>, <code>asn1</code>, <code>public_key</code> and <code>ssl</code>. They are started automatically if they weren't before.</p> <h2 id="_environment">Environment</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The <code>ranch</code> application defines one application environment -configuration parameter.</p></div> -<div class="dlist"><dl> -<dt class="hdlist1"> -profile (false) -</dt> -<dd> -<p> - When enabled, Ranch will start <code>eprof</code> profiling automatically. -</p> +<p>The <code>ranch</code> application defines one application environment configuration parameter.</p> +<dl><dt>profile (false)</dt> +<dd><p>When enabled, Ranch will start <code>eprof</code> profiling automatically.</p> </dd> -</dl></div> -<div class="paragraph"><p>You can use the <code>ranch_app:profile_output/0</code> function to stop -profiling and output the results to the files <em>procs.profile</em> -and <em>total.profile</em>. Do not use in production.</p></div> -</div> -</div> +</dl> +<p>You can use the <code>ranch_app:profile_output/0</code> function to stop profiling and output the results to the files <em>procs.profile</em> and <em>total.profile</em>. Do not use in production.</p> + @@ -133,6 +109,8 @@ and <em>total.profile</em>. Do not use in production.</p></div> + <li><a href="/docs/en/ranch/1.5/manual">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> diff --git a/docs/en/ranch/1.2/manual/ranch_protocol/index.html b/docs/en/ranch/1.2/manual/ranch_protocol/index.html index 1b145f30..d548e5ca 100644 --- a/docs/en/ranch/1.2/manual/ranch_protocol/index.html +++ b/docs/en/ranch/1.2/manual/ranch_protocol/index.html @@ -62,83 +62,33 @@ <h1 class="lined-header"><span>ranch_protocol(3)</span></h1> -<div class="sect1"> <h2 id="_name">Name</h2> -<div class="sectionbody"> -<div class="paragraph"><p>ranch_protocol - behaviour for protocol modules</p></div> -</div> -</div> -<div class="sect1"> +<p>ranch_protocol - behaviour for protocol modules</p> <h2 id="_description">Description</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The <code>ranch_protocol</code> behaviour defines the interface used -by Ranch protocols.</p></div> -</div> -</div> -<div class="sect1"> +<p>The <code>ranch_protocol</code> behaviour defines the interface used by Ranch protocols.</p> <h2 id="_types">Types</h2> -<div class="sectionbody"> -<div class="paragraph"><p>None.</p></div> -</div> -</div> -<div class="sect1"> +<p>None.</p> <h2 id="_callbacks">Callbacks</h2> -<div class="sectionbody"> -<div class="sect2"> -<h3 id="_start_link_ref_socket_transport_protoopts_8594_ok_pid_ok_pid_pid">start_link(Ref, Socket, Transport, ProtoOpts) → {ok, pid()} | {ok, pid(), pid()}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Ref = ranch:ref() -</dt> -<dd> -<p> -Listener name. -</p> +<h3 id="_start_link_ref__socket__transport__protoopts______ok__pid_______ok__pid____pid">start_link(Ref, Socket, Transport, ProtoOpts) -> {ok, pid()} | {ok, pid(), pid()}</h3> +<dl><dt>Ref = ranch:ref()</dt> +<dd><p>Listener name.</p> </dd> -<dt class="hdlist1"> -Socket = any() -</dt> -<dd> -<p> -Socket for this connection. -</p> +<dt>Socket = any()</dt> +<dd><p>Socket for this connection.</p> </dd> -<dt class="hdlist1"> -Transport = module() -</dt> -<dd> -<p> -Transport module for this socket. -</p> +<dt>Transport = module()</dt> +<dd><p>Transport module for this socket.</p> </dd> -<dt class="hdlist1"> -ProtoOpts = any() -</dt> -<dd> -<p> -Protocol options. -</p> +<dt>ProtoOpts = any()</dt> +<dd><p>Protocol options.</p> </dd> -</dl></div> -<div class="paragraph"><p>Start a new connection process for the given socket.</p></div> -<div class="paragraph"><p>The only purpose of this callback is to start a process that -will handle the socket. It must spawn the process, link and -then return the new pid. This function will always be called -from inside a supervisor.</p></div> -<div class="paragraph"><p>This callback can also return two pids. The first pid is the -pid of the process that will be supervised. The second pid is -the pid of the process that will receive ownership of the -socket. This second process must be a child of the first. This -form is only available when <code>connection_type</code> is set to -<code>supervisor</code>.</p></div> -<div class="paragraph"><p>If any other value is returned, the supervisor will close the -socket and assume no process has been started.</p></div> -<div class="paragraph"><p>Do not perform any operations in this callback, as this would -block the supervisor responsible for starting connection -processes and degrade performance severely.</p></div> -</div> -</div> -</div> +</dl> +<p>Start a new connection process for the given socket.</p> +<p>The only purpose of this callback is to start a process that will handle the socket. It must spawn the process, link and then return the new pid. This function will always be called from inside a supervisor.</p> +<p>This callback can also return two pids. The first pid is the pid of the process that will be supervised. The second pid is the pid of the process that will receive ownership of the socket. This second process must be a child of the first. This form is only available when <code>connection_type</code> is set to <code>supervisor</code>.</p> +<p>If any other value is returned, the supervisor will close the socket and assume no process has been started.</p> +<p>Do not perform any operations in this callback, as this would block the supervisor responsible for starting connection processes and degrade performance severely.</p> + @@ -173,6 +123,8 @@ processes and degrade performance severely.</p></div> + <li><a href="/docs/en/ranch/1.5/manual">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> diff --git a/docs/en/ranch/1.2/manual/ranch_ssl/index.html b/docs/en/ranch/1.2/manual/ranch_ssl/index.html index f310db81..7ea56fa3 100644 --- a/docs/en/ranch/1.2/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.2/manual/ranch_ssl/index.html @@ -62,349 +62,158 @@ <h1 class="lined-header"><span>ranch_ssl(3)</span></h1> -<div class="sect1"> <h2 id="_name">Name</h2> -<div class="sectionbody"> -<div class="paragraph"><p>ranch_ssl - SSL transport module</p></div> -</div> -</div> -<div class="sect1"> +<p>ranch_ssl - SSL transport module</p> <h2 id="_description">Description</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The <code>ranch_ssl</code> module implements an SSL Ranch transport.</p></div> -</div> -</div> -<div class="sect1"> +<p>The <code>ranch_ssl</code> module implements an SSL Ranch transport.</p> <h2 id="_types">Types</h2> -<div class="sectionbody"> -<div class="sect2"> <h3 id="_ssl_opt">ssl_opt()</h3> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">alpn_preferred_protocols</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]} - | {<span style="color: #FF6600">cacertfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} - | {<span style="color: #FF6600">cacerts</span>, [<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]} - | {<span style="color: #FF6600">cert</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} - | {<span style="color: #FF6600">certfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} - | {<span style="color: #FF6600">ciphers</span>, [<span style="font-weight: bold"><span style="color: #000000">ssl:erl_cipher_suite</span></span>()] | <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} - | {<span style="color: #FF6600">client_renegotiation</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">crl_cache</span>, {<span style="font-weight: bold"><span style="color: #000000">module</span></span>(), {<span style="color: #FF6600">internal</span> | <span style="font-weight: bold"><span style="color: #000000">any</span></span>(), <span style="font-weight: bold"><span style="color: #000080">list</span></span>()}}} - | {<span style="color: #FF6600">crl_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() | <span style="color: #FF6600">peer</span> | <span style="color: #FF6600">best_effort</span>} - | {<span style="color: #FF6600">depth</span>, <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">255</span>} - | {<span style="color: #FF6600">dh</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} - | {<span style="color: #FF6600">dhfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} - | {<span style="color: #FF6600">fail_if_no_peer_cert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">hibernate_after</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>() | <span style="color: #000080">undefined</span>} - | {<span style="color: #FF6600">honor_cipher_order</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">key</span>, {<span style="color: #FF6600">'RSAPrivateKey'</span> | <span style="color: #FF6600">'DSAPrivateKey'</span> | <span style="color: #FF6600">'PrivateKeyInfo'</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}} - | {<span style="color: #FF6600">keyfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} - | {<span style="color: #FF6600">log_alert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">next_protocols_advertised</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]} - | {<span style="color: #FF6600">partial_chain</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(([<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]) <span style="color: #990000">-></span> {<span style="color: #FF6600">trusted_ca</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} | <span style="color: #FF6600">unknown_ca</span>)} - | {<span style="color: #FF6600">password</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} - | {<span style="color: #FF6600">psk_identity</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} - | {<span style="color: #FF6600">reuse_session</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()} - | {<span style="color: #FF6600">reuse_sessions</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">secure_renegotiate</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">sni_fun</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()} - | {<span style="color: #FF6600">sni_hosts</span>, [{<span style="font-weight: bold"><span style="color: #000000">string</span></span>(), <span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>()}]} - | {<span style="color: #FF6600">user_lookup_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}} - | {<span style="color: #FF6600">verify</span>, <span style="font-weight: bold"><span style="color: #000000">ssl:verify_type</span></span>()} - | {<span style="color: #FF6600">verify_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}} - | {<span style="color: #FF6600">versions</span>, [<span style="font-weight: bold"><span style="color: #000080">atom</span></span>()]}<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>SSL-specific listen options.</p></div> -</div> -<div class="sect2"> -<h3 id="_opt_ranch_tcp_opt_ssl_opt">opt() = ranch_tcp:opt() | ssl_opt()</h3> -<div class="paragraph"><p>Listen options.</p></div> -</div> -<div class="sect2"> -<h3 id="_opts_opt">opts() = [opt()]</h3> -<div class="paragraph"><p>List of listen options.</p></div> -</div> -</div> -</div> -<div class="sect1"> +<pre><tt><b><font color="#000000">ssl_opt</font></b>() <font color="#990000">=</font> {<font color="#FF6600">alpn_preferred_protocols</font>, [<b><font color="#000080">binary</font></b>()]} + | {<font color="#FF6600">cacertfile</font>, <b><font color="#000000">string</font></b>()} + | {<font color="#FF6600">cacerts</font>, [<b><font color="#000000">public_key:der_encoded</font></b>()]} + | {<font color="#FF6600">cert</font>, <b><font color="#000000">public_key:der_encoded</font></b>()} + | {<font color="#FF6600">certfile</font>, <b><font color="#000000">string</font></b>()} + | {<font color="#FF6600">ciphers</font>, [<b><font color="#000000">ssl:erl_cipher_suite</font></b>()] | <b><font color="#000000">string</font></b>()} + | {<font color="#FF6600">client_renegotiation</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">crl_cache</font>, {<b><font color="#000000">module</font></b>(), {<font color="#FF6600">internal</font> | <b><font color="#000000">any</font></b>(), <b><font color="#000080">list</font></b>()}}} + | {<font color="#FF6600">crl_check</font>, <b><font color="#000000">boolean</font></b>() | <font color="#FF6600">peer</font> | <font color="#FF6600">best_effort</font>} + | {<font color="#FF6600">depth</font>, <font color="#993399">0</font><font color="#990000">..</font><font color="#993399">255</font>} + | {<font color="#FF6600">dh</font>, <b><font color="#000000">public_key:der_encoded</font></b>()} + | {<font color="#FF6600">dhfile</font>, <b><font color="#000000">string</font></b>()} + | {<font color="#FF6600">fail_if_no_peer_cert</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">hibernate_after</font>, <b><font color="#000080">integer</font></b>() | <font color="#000080">undefined</font>} + | {<font color="#FF6600">honor_cipher_order</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">key</font>, {<font color="#FF6600">'RSAPrivateKey'</font> | <font color="#FF6600">'DSAPrivateKey'</font> | <font color="#FF6600">'PrivateKeyInfo'</font>, <b><font color="#000000">public_key:der_encoded</font></b>()}} + | {<font color="#FF6600">keyfile</font>, <b><font color="#000000">string</font></b>()} + | {<font color="#FF6600">log_alert</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">next_protocols_advertised</font>, [<b><font color="#000080">binary</font></b>()]} + | {<font color="#FF6600">partial_chain</font>, <b><font color="#0000FF">fun</font></b>(([<b><font color="#000000">public_key:der_encoded</font></b>()]) <font color="#990000">-></font> {<font color="#FF6600">trusted_ca</font>, <b><font color="#000000">public_key:der_encoded</font></b>()} | <font color="#FF6600">unknown_ca</font>)} + | {<font color="#FF6600">password</font>, <b><font color="#000000">string</font></b>()} + | {<font color="#FF6600">psk_identity</font>, <b><font color="#000000">string</font></b>()} + | {<font color="#FF6600">reuse_session</font>, <b><font color="#0000FF">fun</font></b>()} + | {<font color="#FF6600">reuse_sessions</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">secure_renegotiate</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">sni_fun</font>, <b><font color="#0000FF">fun</font></b>()} + | {<font color="#FF6600">sni_hosts</font>, [{<b><font color="#000000">string</font></b>(), <b><font color="#000000">ssl_opt</font></b>()}]} + | {<font color="#FF6600">user_lookup_fun</font>, {<b><font color="#0000FF">fun</font></b>(), <b><font color="#000000">any</font></b>()}} + | {<font color="#FF6600">verify</font>, <b><font color="#000000">ssl:verify_type</font></b>()} + | {<font color="#FF6600">verify_fun</font>, {<b><font color="#0000FF">fun</font></b>(), <b><font color="#000000">any</font></b>()}} + | {<font color="#FF6600">versions</font>, [<b><font color="#000080">atom</font></b>()]}<font color="#990000">.</font></tt></pre> +</div></div> +<p>SSL-specific listen options.</p> +<h3 id="_opt_____ranch_tcp_opt_____ssl_opt">opt() = ranch_tcp:opt() | ssl_opt()</h3> +<p>Listen options.</p> +<h3 id="_opts______opt">opts() = [opt()]</h3> +<p>List of listen options.</p> <h2 id="_option_descriptions">Option descriptions</h2> -<div class="sectionbody"> -<div class="paragraph"><p>Specifying a certificate is mandatory, either through the <code>cert</code> -or the <code>certfile</code> option. None of the other options are required.</p></div> -<div class="paragraph"><p>The default value is given next to the option name.</p></div> -<div class="dlist"><dl> -<dt class="hdlist1"> -alpn_preferred_protocols -</dt> -<dd> -<p> - Perform Application-Layer Protocol Negotiation with the given list of preferred protocols. -</p> -</dd> -<dt class="hdlist1"> -cacertfile -</dt> -<dd> -<p> - Path to PEM encoded trusted certificates file used to verify peer certificates. -</p> -</dd> -<dt class="hdlist1"> -cacerts -</dt> -<dd> -<p> - List of DER encoded trusted certificates. -</p> -</dd> -<dt class="hdlist1"> -cert -</dt> -<dd> -<p> - DER encoded user certificate. -</p> -</dd> -<dt class="hdlist1"> -certfile -</dt> -<dd> -<p> - Path to the PEM encoded user certificate file. May also contain the private key. -</p> -</dd> -<dt class="hdlist1"> -ciphers -</dt> -<dd> -<p> - List of ciphers that clients are allowed to use. -</p> -</dd> -<dt class="hdlist1"> -client_renegotiation (true) -</dt> -<dd> -<p> - Whether to allow client-initiated renegotiation. -</p> -</dd> -<dt class="hdlist1"> -crl_cache ({ssl_crl_cache, {internal, []}}) -</dt> -<dd> -<p> - Customize the module used to cache Certificate Revocation Lists. -</p> -</dd> -<dt class="hdlist1"> -crl_check (false) -</dt> -<dd> -<p> - Whether to perform CRL check on all certificates in the chain during validation. -</p> -</dd> -<dt class="hdlist1"> -depth (1) -</dt> -<dd> -<p> - Maximum of intermediate certificates allowed in the certification path. -</p> -</dd> -<dt class="hdlist1"> -dh -</dt> -<dd> -<p> - DER encoded Diffie-Hellman parameters. -</p> -</dd> -<dt class="hdlist1"> -dhfile -</dt> -<dd> -<p> - Path to the PEM encoded Diffie-Hellman parameters file. -</p> -</dd> -<dt class="hdlist1"> -fail_if_no_peer_cert (false) -</dt> -<dd> -<p> - Whether to refuse the connection if the client sends an empty certificate. -</p> -</dd> -<dt class="hdlist1"> -hibernate_after (undefined) -</dt> -<dd> -<p> - Time in ms after which SSL socket processes go into hibernation to reduce memory usage. -</p> -</dd> -<dt class="hdlist1"> -honor_cipher_order (false) -</dt> -<dd> -<p> - If true, use the server’s preference for cipher selection. If false, use the client’s preference. -</p> -</dd> -<dt class="hdlist1"> -key -</dt> -<dd> -<p> - DER encoded user private key. -</p> -</dd> -<dt class="hdlist1"> -keyfile -</dt> -<dd> -<p> - Path to the PEM encoded private key file, if different than the certfile. -</p> -</dd> -<dt class="hdlist1"> -log_alert (true) -</dt> -<dd> -<p> - If false, error reports will not be displayed. -</p> -</dd> -<dt class="hdlist1"> -next_protocols_advertised -</dt> -<dd> -<p> - List of protocols to send to the client if it supports the Next Protocol extension. -</p> -</dd> -<dt class="hdlist1"> -nodelay (true) -</dt> -<dd> -<p> - Whether to enable TCP_NODELAY. -</p> -</dd> -<dt class="hdlist1"> -partial_chain -</dt> -<dd> -<p> - Claim an intermediate CA in the chain as trusted. -</p> -</dd> -<dt class="hdlist1"> -password -</dt> -<dd> -<p> - Password to the private key file, if password protected. -</p> -</dd> -<dt class="hdlist1"> -psk_identity -</dt> -<dd> -<p> - Provide the given PSK identity hint to the client during the handshake. -</p> -</dd> -<dt class="hdlist1"> -reuse_session -</dt> -<dd> -<p> - Custom policy to decide whether a session should be reused. -</p> -</dd> -<dt class="hdlist1"> -reuse_sessions (false) -</dt> -<dd> -<p> - Whether to allow session reuse. -</p> -</dd> -<dt class="hdlist1"> -secure_renegotiate (false) -</dt> -<dd> -<p> - Whether to reject renegotiation attempts that do not conform to RFC5746. -</p> -</dd> -<dt class="hdlist1"> -sni_fun -</dt> -<dd> -<p> - Function called when the client requests a host using Server Name Indication. Returns options to apply. -</p> -</dd> -<dt class="hdlist1"> -sni_hosts -</dt> -<dd> -<p> - Options to apply for the host that matches what the client requested with Server Name Indication. -</p> -</dd> -<dt class="hdlist1"> -user_lookup_fun -</dt> -<dd> -<p> - Function called to determine the shared secret when using PSK, or provide parameters when using SRP. -</p> -</dd> -<dt class="hdlist1"> -verify (verify_none) -</dt> -<dd> -<p> - Use <code>verify_peer</code> to request a certificate from the client. -</p> -</dd> -<dt class="hdlist1"> -verify_fun -</dt> -<dd> -<p> - Custom policy to decide whether a client certificate is valid. -</p> -</dd> -<dt class="hdlist1"> -versions -</dt> -<dd> -<p> - TLS protocol versions that will be supported. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Note that the client will not send a certificate unless the -value for the <code>verify</code> option is set to <code>verify_peer</code>. This -means that the <code>fail_if_no_peer_cert</code> only apply when combined -with the <code>verify</code> option. The <code>verify_fun</code> option allows -greater control over the client certificate validation.</p></div> -<div class="paragraph"><p>The options <code>sni_fun</code> and <code>sni_hosts</code> are mutually exclusive.</p></div> -</div> -</div> -<div class="sect1"> +<p>Specifying a certificate is mandatory, either through the <code>cert</code> or the <code>certfile</code> option. None of the other options are required.</p> +<p>The default value is given next to the option name.</p> +<dl><dt>alpn_preferred_protocols</dt> +<dd><p>Perform Application-Layer Protocol Negotiation with the given list of preferred protocols.</p> +</dd> +<dt>cacertfile</dt> +<dd><p>Path to PEM encoded trusted certificates file used to verify peer certificates.</p> +</dd> +<dt>cacerts</dt> +<dd><p>List of DER encoded trusted certificates.</p> +</dd> +<dt>cert</dt> +<dd><p>DER encoded user certificate.</p> +</dd> +<dt>certfile</dt> +<dd><p>Path to the PEM encoded user certificate file. May also contain the private key.</p> +</dd> +<dt>ciphers</dt> +<dd><p>List of ciphers that clients are allowed to use.</p> +</dd> +<dt>client_renegotiation (true)</dt> +<dd><p>Whether to allow client-initiated renegotiation.</p> +</dd> +<dt>crl_cache ({ssl_crl_cache, {internal, []}})</dt> +<dd><p>Customize the module used to cache Certificate Revocation Lists.</p> +</dd> +<dt>crl_check (false)</dt> +<dd><p>Whether to perform CRL check on all certificates in the chain during validation.</p> +</dd> +<dt>depth (1)</dt> +<dd><p>Maximum of intermediate certificates allowed in the certification path.</p> +</dd> +<dt>dh</dt> +<dd><p>DER encoded Diffie-Hellman parameters.</p> +</dd> +<dt>dhfile</dt> +<dd><p>Path to the PEM encoded Diffie-Hellman parameters file.</p> +</dd> +<dt>fail_if_no_peer_cert (false)</dt> +<dd><p>Whether to refuse the connection if the client sends an empty certificate.</p> +</dd> +<dt>hibernate_after (undefined)</dt> +<dd><p>Time in ms after which SSL socket processes go into hibernation to reduce memory usage.</p> +</dd> +<dt>honor_cipher_order (false)</dt> +<dd><p>If true, use the server's preference for cipher selection. If false, use the client's preference.</p> +</dd> +<dt>key</dt> +<dd><p>DER encoded user private key.</p> +</dd> +<dt>keyfile</dt> +<dd><p>Path to the PEM encoded private key file, if different than the certfile.</p> +</dd> +<dt>log_alert (true)</dt> +<dd><p>If false, error reports will not be displayed.</p> +</dd> +<dt>next_protocols_advertised</dt> +<dd><p>List of protocols to send to the client if it supports the Next Protocol extension.</p> +</dd> +<dt>nodelay (true)</dt> +<dd><p>Whether to enable TCP_NODELAY.</p> +</dd> +<dt>partial_chain</dt> +<dd><p>Claim an intermediate CA in the chain as trusted.</p> +</dd> +<dt>password</dt> +<dd><p>Password to the private key file, if password protected.</p> +</dd> +<dt>psk_identity</dt> +<dd><p>Provide the given PSK identity hint to the client during the handshake.</p> +</dd> +<dt>reuse_session</dt> +<dd><p>Custom policy to decide whether a session should be reused.</p> +</dd> +<dt>reuse_sessions (false)</dt> +<dd><p>Whether to allow session reuse.</p> +</dd> +<dt>secure_renegotiate (false)</dt> +<dd><p>Whether to reject renegotiation attempts that do not conform to RFC5746.</p> +</dd> +<dt>sni_fun</dt> +<dd><p>Function called when the client requests a host using Server Name Indication. Returns options to apply.</p> +</dd> +<dt>sni_hosts</dt> +<dd><p>Options to apply for the host that matches what the client requested with Server Name Indication.</p> +</dd> +<dt>user_lookup_fun</dt> +<dd><p>Function called to determine the shared secret when using PSK, or provide parameters when using SRP.</p> +</dd> +<dt>verify (verify_none)</dt> +<dd><p>Use <code>verify_peer</code> to request a certificate from the client.</p> +</dd> +<dt>verify_fun</dt> +<dd><p>Custom policy to decide whether a client certificate is valid.</p> +</dd> +<dt>versions</dt> +<dd><p>TLS protocol versions that will be supported.</p> +</dd> +</dl> +<p>Note that the client will not send a certificate unless the value for the <code>verify</code> option is set to <code>verify_peer</code>. This means that the <code>fail_if_no_peer_cert</code> only apply when combined with the <code>verify</code> option. The <code>verify_fun</code> option allows greater control over the client certificate validation.</p> +<p>The options <code>sni_fun</code> and <code>sni_hosts</code> are mutually exclusive.</p> <h2 id="_exports">Exports</h2> -<div class="sectionbody"> -<div class="paragraph"><p>None.</p></div> -</div> -</div> +<p>None.</p> + @@ -439,6 +248,8 @@ greater control over the client certificate validation.</p></div> + <li><a href="/docs/en/ranch/1.5/manual">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> diff --git a/docs/en/ranch/1.2/manual/ranch_tcp/index.html b/docs/en/ranch/1.2/manual/ranch_tcp/index.html index 6e3f7c64..2218c203 100644 --- a/docs/en/ranch/1.2/manual/ranch_tcp/index.html +++ b/docs/en/ranch/1.2/manual/ranch_tcp/index.html @@ -62,274 +62,123 @@ <h1 class="lined-header"><span>ranch_tcp(3)</span></h1> -<div class="sect1"> <h2 id="_name">Name</h2> -<div class="sectionbody"> -<div class="paragraph"><p>ranch_tcp - TCP transport module</p></div> -</div> -</div> -<div class="sect1"> +<p>ranch_tcp - TCP transport module</p> <h2 id="_description">Description</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The <code>ranch_tcp</code> module implements a TCP Ranch transport.</p></div> -<div class="paragraph"><p>Note that due to bugs in OTP up to at least R16B02, it is -recommended to disable async threads when using the -<code>sendfile</code> function of this transport, as it can make -the threads stuck indefinitely.</p></div> -</div> -</div> -<div class="sect1"> +<p>The <code>ranch_tcp</code> module implements a TCP Ranch transport.</p> +<p>Note that due to bugs in OTP up to at least R16B02, it is recommended to disable async threads when using the <code>sendfile</code> function of this transport, as it can make the threads stuck indefinitely.</p> <h2 id="_types">Types</h2> -<div class="sectionbody"> -<div class="sect2"> <h3 id="_opt">opt()</h3> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">backlog</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} - | {<span style="color: #FF6600">buffer</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} - | {<span style="color: #FF6600">delay_send</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">dontroute</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">exit_on_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">fd</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} - | {<span style="color: #FF6600">high_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} - | {<span style="color: #FF6600">high_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} - | <span style="color: #FF6600">inet</span> - | <span style="color: #FF6600">inet6</span> - | {<span style="color: #FF6600">ip</span>, <span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>()} - | {<span style="color: #FF6600">keepalive</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">linger</span>, {<span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}} - | {<span style="color: #FF6600">low_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} - | {<span style="color: #FF6600">low_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} - | {<span style="color: #FF6600">nodelay</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">port</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()} - | {<span style="font-weight: bold"><span style="color: #000080">priority</span></span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()} - | {<span style="color: #FF6600">raw</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} - | {<span style="color: #FF6600">recbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} - | {<span style="color: #FF6600">send_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()} - | {<span style="color: #FF6600">send_timeout_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">sndbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} - | {<span style="color: #FF6600">tos</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}</tt></pre></div></div> -<div class="paragraph"><p>Listen options.</p></div> -<div class="paragraph"><p>This does not represent the entirety of the options that can -be set on the socket, but only the options that may be -set independently of protocol implementation.</p></div> -</div> -<div class="sect2"> -<h3 id="_opts_opt">opts() = [opt()]</h3> -<div class="paragraph"><p>List of listen options.</p></div> -</div> -</div> -</div> -<div class="sect1"> +<pre><tt><b><font color="#000000">opt</font></b>() <font color="#990000">=</font> {<font color="#FF6600">backlog</font>, <b><font color="#000000">non_neg_integer</font></b>()} + | {<font color="#FF6600">buffer</font>, <b><font color="#000000">non_neg_integer</font></b>()} + | {<font color="#FF6600">delay_send</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">dontroute</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">exit_on_close</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">fd</font>, <b><font color="#000000">non_neg_integer</font></b>()} + | {<font color="#FF6600">high_msgq_watermark</font>, <b><font color="#000000">non_neg_integer</font></b>()} + | {<font color="#FF6600">high_watermark</font>, <b><font color="#000000">non_neg_integer</font></b>()} + | <font color="#FF6600">inet</font> + | <font color="#FF6600">inet6</font> + | {<font color="#FF6600">ip</font>, <b><font color="#000000">inet:ip_address</font></b>()} + | {<font color="#FF6600">keepalive</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">linger</font>, {<b><font color="#000000">boolean</font></b>(), <b><font color="#000000">non_neg_integer</font></b>()}} + | {<font color="#FF6600">low_msgq_watermark</font>, <b><font color="#000000">non_neg_integer</font></b>()} + | {<font color="#FF6600">low_watermark</font>, <b><font color="#000000">non_neg_integer</font></b>()} + | {<font color="#FF6600">nodelay</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">port</font>, <b><font color="#000000">inet:port_number</font></b>()} + | {<b><font color="#000080">priority</font></b>, <b><font color="#000080">integer</font></b>()} + | {<font color="#FF6600">raw</font>, <b><font color="#000000">non_neg_integer</font></b>(), <b><font color="#000000">non_neg_integer</font></b>(), <b><font color="#000080">binary</font></b>()} + | {<font color="#FF6600">recbuf</font>, <b><font color="#000000">non_neg_integer</font></b>()} + | {<font color="#FF6600">send_timeout</font>, <b><font color="#000000">timeout</font></b>()} + | {<font color="#FF6600">send_timeout_close</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">sndbuf</font>, <b><font color="#000000">non_neg_integer</font></b>()} + | {<font color="#FF6600">tos</font>, <b><font color="#000080">integer</font></b>()}</tt></pre> +</div></div> +<p>Listen options.</p> +<p>This does not represent the entirety of the options that can be set on the socket, but only the options that may be set independently of protocol implementation.</p> +<h3 id="_opts______opt">opts() = [opt()]</h3> +<p>List of listen options.</p> <h2 id="_option_descriptions">Option descriptions</h2> -<div class="sectionbody"> -<div class="paragraph"><p>None of the options are required.</p></div> -<div class="paragraph"><p>Please consult the <code>gen_tcp</code> and <code>inet</code> manuals for a more -thorough description of these options. This manual only aims -to provide a short description along with what the defaults -are. Defaults may be different in Ranch compared to <code>gen_tcp</code>. -Defaults are given next to the option name.</p></div> -<div class="dlist"><dl> -<dt class="hdlist1"> -backlog (1024) -</dt> -<dd> -<p> - Max length of the queue of pending connections. -</p> +<p>None of the options are required.</p> +<p>Please consult the <code>gen_tcp</code> and <code>inet</code> manuals for a more thorough description of these options. This manual only aims to provide a short description along with what the defaults are. Defaults may be different in Ranch compared to <code>gen_tcp</code>. Defaults are given next to the option name.</p> +<dl><dt>backlog (1024)</dt> +<dd><p>Max length of the queue of pending connections.</p> </dd> -<dt class="hdlist1"> -buffer -</dt> -<dd> -<p> - Size of the buffer used by the Erlang driver. Default is system-dependent. -</p> +<dt>buffer</dt> +<dd><p>Size of the buffer used by the Erlang driver. Default is system-dependent.</p> </dd> -<dt class="hdlist1"> -delay_send (false) -</dt> -<dd> -<p> - Always queue packets before sending, to send fewer, larger packets over the network. -</p> +<dt>delay_send (false)</dt> +<dd><p>Always queue packets before sending, to send fewer, larger packets over the network.</p> </dd> -<dt class="hdlist1"> -dontroute (false) -</dt> -<dd> -<p> - Don’t send via a gateway, only send to directly connected hosts. -</p> +<dt>dontroute (false)</dt> +<dd><p>Don't send via a gateway, only send to directly connected hosts.</p> </dd> -<dt class="hdlist1"> -exit_on_close (true) -</dt> -<dd> -<p> - Disable to allow sending data after a close has been detected. -</p> +<dt>exit_on_close (true)</dt> +<dd><p>Disable to allow sending data after a close has been detected.</p> </dd> -<dt class="hdlist1"> -fd -</dt> -<dd> -<p> - File descriptor of the socket, if it was opened externally. -</p> +<dt>fd</dt> +<dd><p>File descriptor of the socket, if it was opened externally.</p> </dd> -<dt class="hdlist1"> -high_msgq_watermark (8192) -</dt> -<dd> -<p> - Limit in the amount of data in the socket message queue before the socket queue becomes busy. -</p> +<dt>high_msgq_watermark (8192)</dt> +<dd><p>Limit in the amount of data in the socket message queue before the socket queue becomes busy.</p> </dd> -<dt class="hdlist1"> -high_watermark (8192) -</dt> -<dd> -<p> - Limit in the amount of data in the ERTS socket implementation’s queue before the socket becomes busy. -</p> +<dt>high_watermark (8192)</dt> +<dd><p>Limit in the amount of data in the ERTS socket implementation's queue before the socket becomes busy.</p> </dd> -<dt class="hdlist1"> -inet -</dt> -<dd> -<p> - Set up the socket for IPv4. -</p> +<dt>inet</dt> +<dd><p>Set up the socket for IPv4.</p> </dd> -<dt class="hdlist1"> -inet6 -</dt> -<dd> -<p> - Set up the socket for IPv6. -</p> +<dt>inet6</dt> +<dd><p>Set up the socket for IPv6.</p> </dd> -<dt class="hdlist1"> -ip -</dt> -<dd> -<p> - Interface to listen on. Listen on all interfaces by default. -</p> +<dt>ip</dt> +<dd><p>Interface to listen on. Listen on all interfaces by default.</p> </dd> -<dt class="hdlist1"> -keepalive (false) -</dt> -<dd> -<p> - Enable sending of keep-alive messages. -</p> +<dt>keepalive (false)</dt> +<dd><p>Enable sending of keep-alive messages.</p> </dd> -<dt class="hdlist1"> -linger ({false, 0}) -</dt> -<dd> -<p> - Whether to wait and how long to flush data sent before closing the socket. -</p> +<dt>linger ({false, 0})</dt> +<dd><p>Whether to wait and how long to flush data sent before closing the socket.</p> </dd> -<dt class="hdlist1"> -low_msgq_watermark (4096) -</dt> -<dd> -<p> - Amount of data in the socket message queue before the socket queue leaves busy state. -</p> +<dt>low_msgq_watermark (4096)</dt> +<dd><p>Amount of data in the socket message queue before the socket queue leaves busy state.</p> </dd> -<dt class="hdlist1"> -low_watermark (4096) -</dt> -<dd> -<p> - Amount of data in the ERTS socket implementation’s queue before the socket leaves busy state. -</p> +<dt>low_watermark (4096)</dt> +<dd><p>Amount of data in the ERTS socket implementation's queue before the socket leaves busy state.</p> </dd> -<dt class="hdlist1"> -nodelay (true) -</dt> -<dd> -<p> - Whether to enable TCP_NODELAY. -</p> +<dt>nodelay (true)</dt> +<dd><p>Whether to enable TCP_NODELAY.</p> </dd> -<dt class="hdlist1"> -port (0) -</dt> -<dd> -<p> - TCP port number to listen on. 0 means a random port will be used. -</p> +<dt>port (0)</dt> +<dd><p>TCP port number to listen on. 0 means a random port will be used.</p> </dd> -<dt class="hdlist1"> -priority (0) -</dt> -<dd> -<p> - Priority value for all packets to be sent by this socket. -</p> +<dt>priority (0)</dt> +<dd><p>Priority value for all packets to be sent by this socket.</p> </dd> -<dt class="hdlist1"> -recbuf -</dt> -<dd> -<p> - Minimum size of the socket’s receive buffer. Default is system-dependent. -</p> +<dt>recbuf</dt> +<dd><p>Minimum size of the socket's receive buffer. Default is system-dependent.</p> </dd> -<dt class="hdlist1"> -send_timeout (30000) -</dt> -<dd> -<p> - How long the send call may wait for confirmation before returning. -</p> +<dt>send_timeout (30000)</dt> +<dd><p>How long the send call may wait for confirmation before returning.</p> </dd> -<dt class="hdlist1"> -send_timeout_close (true) -</dt> -<dd> -<p> - Whether to close the socket when the confirmation wasn’t received. -</p> +<dt>send_timeout_close (true)</dt> +<dd><p>Whether to close the socket when the confirmation wasn't received.</p> </dd> -<dt class="hdlist1"> -sndbuf -</dt> -<dd> -<p> - Minimum size of the socket’s send buffer. Default is system-dependent. -</p> +<dt>sndbuf</dt> +<dd><p>Minimum size of the socket's send buffer. Default is system-dependent.</p> </dd> -<dt class="hdlist1"> -tos -</dt> -<dd> -<p> - Value for the IP_TOS IP level option. Use with caution. -</p> +<dt>tos</dt> +<dd><p>Value for the IP_TOS IP level option. Use with caution.</p> </dd> -</dl></div> -<div class="paragraph"><p>In addition, the <code>raw</code> option can be used to set system-specific -options by specifying the protocol level, the option number and -the actual option value specified as a binary. This option is not -portable. Use with caution.</p></div> -</div> -</div> -<div class="sect1"> +</dl> +<p>In addition, the <code>raw</code> option can be used to set system-specific options by specifying the protocol level, the option number and the actual option value specified as a binary. This option is not portable. Use with caution.</p> <h2 id="_exports">Exports</h2> -<div class="sectionbody"> -<div class="paragraph"><p>None.</p></div> -</div> -</div> +<p>None.</p> + @@ -364,6 +213,8 @@ portable. Use with caution.</p></div> + <li><a href="/docs/en/ranch/1.5/manual">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> diff --git a/docs/en/ranch/1.2/manual/ranch_transport/index.html b/docs/en/ranch/1.2/manual/ranch_transport/index.html index c0c08417..f276197e 100644 --- a/docs/en/ranch/1.2/manual/ranch_transport/index.html +++ b/docs/en/ranch/1.2/manual/ranch_transport/index.html @@ -62,494 +62,198 @@ <h1 class="lined-header"><span>ranch_transport(3)</span></h1> -<div class="sect1"> <h2 id="_name">Name</h2> -<div class="sectionbody"> -<div class="paragraph"><p>ranch_transport - behaviour for transport modules</p></div> -</div> -</div> -<div class="sect1"> +<p>ranch_transport - behaviour for transport modules</p> <h2 id="_description">Description</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The <code>ranch_transport</code> behaviour defines the interface used -by Ranch transports.</p></div> -</div> -</div> -<div class="sect1"> +<p>The <code>ranch_transport</code> behaviour defines the interface used by Ranch transports.</p> <h2 id="_types">Types</h2> -<div class="sectionbody"> -<div class="sect2"> -<h3 id="_sendfile_opts_chunk_size_non_neg_integer">sendfile_opts() = [{chunk_size, non_neg_integer()}]</h3> -<div class="paragraph"><p>Options used by the sendfile function and callbacks.</p></div> -<div class="paragraph"><p>Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.</p></div> -</div> -</div> -</div> -<div class="sect1"> +<h3 id="_sendfile_opts_______chunk_size__non_neg_integer">sendfile_opts() = [{chunk_size, non_neg_integer()}]</h3> +<p>Options used by the sendfile function and callbacks.</p> +<p>Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.</p> <h2 id="_callbacks">Callbacks</h2> -<div class="sectionbody"> -<div class="sect2"> -<h3 id="_accept_lsocket_timeout_8594_ok_csocket_error_closed_timeout_atom">accept(LSocket, Timeout) → {ok, CSocket} | {error, closed | timeout | atom()}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -LSocket = CSocket = any() -</dt> -<dd> -<p> -Listening socket. -</p> -</dd> -<dt class="hdlist1"> -Timeout = timeout() -</dt> -<dd> -<p> -Accept timeout. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Accept a connection on the given listening socket.</p></div> -<div class="paragraph"><p>The <code>accept_ack</code> callback will be used to initialize the socket -after accepting the connection. This is most useful when the -transport is not raw TCP, like with SSL for example.</p></div> -</div> -<div class="sect2"> -<h3 id="_accept_ack_csocket_timeout_8594_ok">accept_ack(CSocket, Timeout) → ok</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -CSocket = any() -</dt> -<dd> -<p> -Socket for this connection. -</p> -</dd> -<dt class="hdlist1"> -Timeout = timeout() -</dt> -<dd> -<p> -Ack timeout. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Perform post-accept initialization of the connection.</p></div> -<div class="paragraph"><p>This function will be called by connection processes -before performing any socket operation. It allows -transports that require extra initialization to perform -their task and make the socket ready to use.</p></div> -</div> -<div class="sect2"> -<h3 id="_close_socket_8594_ok">close(Socket) → ok</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Socket = any() -</dt> -<dd> -<p> -Socket opened with listen/1 or accept/2. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Close the given socket.</p></div> -</div> -<div class="sect2"> -<h3 id="_controlling_process_socket_pid_8594_ok_error_closed_not_owner_atom">controlling_process(Socket, Pid) → ok | {error, closed | not_owner | atom()}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Socket = any() -</dt> -<dd> -<p> -Socket opened with listen/1 or accept/2. -</p> -</dd> -<dt class="hdlist1"> -Pid = pid() -</dt> -<dd> -<p> -Pid of the new owner of the socket. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Change the controlling process for the given socket.</p></div> -<div class="paragraph"><p>The controlling process is the process that is allowed to -perform operations on the socket, and that will receive -messages from the socket when active mode is used. When -the controlling process dies, the socket is closed.</p></div> -</div> -<div class="sect2"> -<h3 id="_listen_transopts_8594_ok_lsocket_error_atom">listen(TransOpts) → {ok, LSocket} | {error, atom()}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -TransOpts = any() -</dt> -<dd> -<p> -Transport options. -</p> -</dd> -<dt class="hdlist1"> -LSocket = any() -</dt> -<dd> -<p> -Listening socket. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Listen for connections on the given port.</p></div> -<div class="paragraph"><p>The port is given as part of the transport options under -the key <code>port</code>. Any other option is transport dependent.</p></div> -<div class="paragraph"><p>The socket returned by this call can then be used to -accept connections. It is not possible to send or receive -data from the listening socket.</p></div> -</div> -<div class="sect2"> -<h3 id="_messages_8594_ok_closed_error">messages() → {OK, Closed, Error}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -OK = Closed = Error = atom() -</dt> -<dd> -<p> -Tuple names. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Return the atoms used to identify messages sent in active mode.</p></div> -</div> -<div class="sect2"> -<h3 id="_name_8594_name">name() → Name</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Name = atom() -</dt> -<dd> -<p> -Transport module name. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Return the name of the transport.</p></div> -</div> -<div class="sect2"> -<h3 id="_peername_csocket_8594_ok_ip_port_error_atom">peername(CSocket) → {ok, {IP, Port}} | {error, atom()}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -CSocket = any() -</dt> -<dd> -<p> -Socket for this connection. -</p> -</dd> -<dt class="hdlist1"> -IP = inet:ip_address() -</dt> -<dd> -<p> -IP of the remote endpoint. -</p> -</dd> -<dt class="hdlist1"> -Port = inet:port_number() -</dt> -<dd> -<p> -Port of the remote endpoint. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Return the IP and port of the remote endpoint.</p></div> -</div> -<div class="sect2"> -<h3 id="_recv_csocket_length_timeout_8594_ok_packet_error_closed_timeout_atom">recv(CSocket, Length, Timeout) → {ok, Packet} | {error, closed | timeout | atom()}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -CSocket = any() -</dt> -<dd> -<p> -Socket for this connection. -</p> -</dd> -<dt class="hdlist1"> -Length = non_neg_integer() -</dt> -<dd> -<p> -Requested length. -</p> -</dd> -<dt class="hdlist1"> -Timeout = timeout() -</dt> -<dd> -<p> -Receive timeout. -</p> -</dd> -<dt class="hdlist1"> -Packet = iodata() | any() -</dt> -<dd> -<p> -Data received. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Receive data from the given socket when in passive mode.</p></div> -<div class="paragraph"><p>Trying to receive data from a socket that is in active mode -will return an error.</p></div> -<div class="paragraph"><p>A length of 0 will return any data available on the socket.</p></div> -<div class="paragraph"><p>While it is possible to use the timeout value <code>infinity</code>, -this is highly discouraged as this could cause your process -to get stuck waiting for data that will never come. This may -happen when a socket becomes half-open due to a crash of the -remote endpoint. Wi-Fi going down is another common culprit -of this issue.</p></div> -</div> -<div class="sect2"> -<h3 id="_send_csocket_packet_8594_ok_error_atom">send(CSocket, Packet) → ok | {error, atom()}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -CSocket = any() -</dt> -<dd> -<p> -Socket for this connection. -</p> -</dd> -<dt class="hdlist1"> -Packet = iodata() -</dt> -<dd> -<p> -Data to be sent. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Send data to the given socket.</p></div> -</div> -<div class="sect2"> -<h3 id="_sendfile_csocket_file_8594_sendfile_csocket_file_0_0">sendfile(CSocket, File) → sendfile(CSocket, File, 0, 0, [])</h3> -<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div> -</div> -<div class="sect2"> -<h3 id="_sendfile_csocket_file_offset_bytes_8594_sendfile_csocket_file_offset_bytes">sendfile(CSocket, File, Offset, Bytes) → sendfile(CSocket, File, Offset, Bytes, [])</h3> -<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div> -</div> -<div class="sect2"> -<h3 id="_sendfile_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -CSocket = any() -</dt> -<dd> -<p> -Socket for this connection. -</p> -</dd> -<dt class="hdlist1"> -File = file:filename_all() | file:fd() -</dt> -<dd> -<p> -Filename or file descriptor for the file to be sent. -</p> -</dd> -<dt class="hdlist1"> -Offset = non_neg_integer() -</dt> -<dd> -<p> -Begin sending at this position in the file. -</p> -</dd> -<dt class="hdlist1"> -Bytes = non_neg_integer() -</dt> -<dd> -<p> -Send this many bytes. -</p> -</dd> -<dt class="hdlist1"> -SentBytes = non_neg_integer() -</dt> -<dd> -<p> -This many bytes were sent. -</p> -</dd> -<dt class="hdlist1"> -SfOpts = sendfile_opts() -</dt> -<dd> -<p> -Sendfile options. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Send data from a file to the given socket.</p></div> -<div class="paragraph"><p>The file may be sent full or in parts, and may be specified -by its filename or by an already open file descriptor.</p></div> -<div class="paragraph"><p>Transports that manipulate TCP directly may use the -<code>file:sendfile/{2,4,5}</code> function, which calls the sendfile -syscall where applicable (on Linux, for example). Other -transports can use the <code>sendfile/6</code> function exported from -this module.</p></div> -</div> -<div class="sect2"> -<h3 id="_setopts_csocket_sockopts_8594_ok_error_atom">setopts(CSocket, SockOpts) → ok | {error, atom()}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -CSocket = any() -</dt> -<dd> -<p> -Socket for this connection. -</p> -</dd> -<dt class="hdlist1"> -SockOpts = any() -</dt> -<dd> -<p> -Socket options. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Change options for the given socket.</p></div> -<div class="paragraph"><p>This is mainly useful for switching to active or passive mode -or to set protocol-specific options.</p></div> -</div> -<div class="sect2"> -<h3 id="_shutdown_csocket_how_8594_ok_error_atom">shutdown(CSocket, How) → ok | {error, atom()}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -CSocket = any() -</dt> -<dd> -<p> -Socket for this connection. -</p> -</dd> -<dt class="hdlist1"> -How = read | write | read_write -</dt> -<dd> -<p> -Which side(s) of the socket to close. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Immediately close the socket in one or two directions.</p></div> -</div> -<div class="sect2"> -<h3 id="_sockname_socket_8594_ok_ip_port_error_atom">sockname(Socket) → {ok, {IP, Port}} | {error, atom()}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Socket = any() -</dt> -<dd> -<p> -Socket opened with listen/1 or accept/2. -</p> -</dd> -<dt class="hdlist1"> -IP = inet:ip_address() -</dt> -<dd> -<p> -IP of the local endpoint. -</p> -</dd> -<dt class="hdlist1"> -Port = inet:port_number() -</dt> -<dd> -<p> -Port of the local endpoint. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Return the IP and port of the local endpoint.</p></div> -</div> -</div> -</div> -<div class="sect1"> +<h3 id="_accept_lsocket__timeout______ok__csocket_____error__closed___timeout___atom">accept(LSocket, Timeout) -> {ok, CSocket} | {error, closed | timeout | atom()}</h3> +<dl><dt>LSocket = CSocket = any()</dt> +<dd><p>Listening socket.</p> +</dd> +<dt>Timeout = timeout()</dt> +<dd><p>Accept timeout.</p> +</dd> +</dl> +<p>Accept a connection on the given listening socket.</p> +<p>The <code>accept_ack</code> callback will be used to initialize the socket after accepting the connection. This is most useful when the transport is not raw TCP, like with SSL for example.</p> +<h3 id="_accept_ack_csocket__timeout_____ok">accept_ack(CSocket, Timeout) -> ok</h3> +<dl><dt>CSocket = any()</dt> +<dd><p>Socket for this connection.</p> +</dd> +<dt>Timeout = timeout()</dt> +<dd><p>Ack timeout.</p> +</dd> +</dl> +<p>Perform post-accept initialization of the connection.</p> +<p>This function will be called by connection processes before performing any socket operation. It allows transports that require extra initialization to perform their task and make the socket ready to use.</p> +<h3 id="_close_socket_____ok">close(Socket) -> ok</h3> +<dl><dt>Socket = any()</dt> +<dd><p>Socket opened with listen/1 or accept/2.</p> +</dd> +</dl> +<p>Close the given socket.</p> +<h3 id="_controlling_process_socket__pid_____ok____error__closed___not_owner___atom">controlling_process(Socket, Pid) -> ok | {error, closed | not_owner | atom()}</h3> +<dl><dt>Socket = any()</dt> +<dd><p>Socket opened with listen/1 or accept/2.</p> +</dd> +<dt>Pid = pid()</dt> +<dd><p>Pid of the new owner of the socket.</p> +</dd> +</dl> +<p>Change the controlling process for the given socket.</p> +<p>The controlling process is the process that is allowed to perform operations on the socket, and that will receive messages from the socket when active mode is used. When the controlling process dies, the socket is closed.</p> +<h3 id="_listen_transopts______ok__lsocket_____error__atom">listen(TransOpts) -> {ok, LSocket} | {error, atom()}</h3> +<dl><dt>TransOpts = any()</dt> +<dd><p>Transport options.</p> +</dd> +<dt>LSocket = any()</dt> +<dd><p>Listening socket.</p> +</dd> +</dl> +<p>Listen for connections on the given port.</p> +<p>The port is given as part of the transport options under the key <code>port</code>. Any other option is transport dependent.</p> +<p>The socket returned by this call can then be used to accept connections. It is not possible to send or receive data from the listening socket.</p> +<h3 id="_messages_______ok__closed__error">messages() -> {OK, Closed, Error}</h3> +<dl><dt>OK = Closed = Error = atom()</dt> +<dd><p>Tuple names.</p> +</dd> +</dl> +<p>Return the atoms used to identify messages sent in active mode.</p> +<h3 id="_name______name">name() -> Name</h3> +<dl><dt>Name = atom()</dt> +<dd><p>Transport module name.</p> +</dd> +</dl> +<p>Return the name of the transport.</p> +<h3 id="_peername_csocket______ok___ip__port______error__atom">peername(CSocket) -> {ok, {IP, Port}} | {error, atom()}</h3> +<dl><dt>CSocket = any()</dt> +<dd><p>Socket for this connection.</p> +</dd> +<dt>IP = inet:ip_address()</dt> +<dd><p>IP of the remote endpoint.</p> +</dd> +<dt>Port = inet:port_number()</dt> +<dd><p>Port of the remote endpoint.</p> +</dd> +</dl> +<p>Return the IP and port of the remote endpoint.</p> +<h3 id="_recv_csocket__length__timeout______ok__packet_____error__closed___timeout___atom">recv(CSocket, Length, Timeout) -> {ok, Packet} | {error, closed | timeout | atom()}</h3> +<dl><dt>CSocket = any()</dt> +<dd><p>Socket for this connection.</p> +</dd> +<dt>Length = non_neg_integer()</dt> +<dd><p>Requested length.</p> +</dd> +<dt>Timeout = timeout()</dt> +<dd><p>Receive timeout.</p> +</dd> +<dt>Packet = iodata() | any()</dt> +<dd><p>Data received.</p> +</dd> +</dl> +<p>Receive data from the given socket when in passive mode.</p> +<p>Trying to receive data from a socket that is in active mode will return an error.</p> +<p>A length of 0 will return any data available on the socket.</p> +<p>While it is possible to use the timeout value <code>infinity</code>, this is highly discouraged as this could cause your process to get stuck waiting for data that will never come. This may happen when a socket becomes half-open due to a crash of the remote endpoint. Wi-Fi going down is another common culprit of this issue.</p> +<h3 id="_send_csocket__packet_____ok____error__atom">send(CSocket, Packet) -> ok | {error, atom()}</h3> +<dl><dt>CSocket = any()</dt> +<dd><p>Socket for this connection.</p> +</dd> +<dt>Packet = iodata()</dt> +<dd><p>Data to be sent.</p> +</dd> +</dl> +<p>Send data to the given socket.</p> +<h3 id="_sendfile_csocket__file_____sendfile_csocket__file__0__0">sendfile(CSocket, File) -> sendfile(CSocket, File, 0, 0, [])</h3> +<p>Alias of <code>ranch_transport:sendfile/5</code>.</p> +<h3 id="_sendfile_csocket__file__offset__bytes_____sendfile_csocket__file__offset__bytes">sendfile(CSocket, File, Offset, Bytes) -> sendfile(CSocket, File, Offset, Bytes, [])</h3> +<p>Alias of <code>ranch_transport:sendfile/5</code>.</p> +<h3 id="_sendfile_csocket__file__offset__bytes__sfopts______ok__sentbytes_____error__atom">sendfile(CSocket, File, Offset, Bytes, SfOpts) -> {ok, SentBytes} | {error, atom()}</h3> +<dl><dt>CSocket = any()</dt> +<dd><p>Socket for this connection.</p> +</dd> +<dt>File = file:filename_all() | file:fd()</dt> +<dd><p>Filename or file descriptor for the file to be sent.</p> +</dd> +<dt>Offset = non_neg_integer()</dt> +<dd><p>Begin sending at this position in the file.</p> +</dd> +<dt>Bytes = non_neg_integer()</dt> +<dd><p>Send this many bytes.</p> +</dd> +<dt>SentBytes = non_neg_integer()</dt> +<dd><p>This many bytes were sent.</p> +</dd> +<dt>SfOpts = sendfile_opts()</dt> +<dd><p>Sendfile options.</p> +</dd> +</dl> +<p>Send data from a file to the given socket.</p> +<p>The file may be sent full or in parts, and may be specified by its filename or by an already open file descriptor.</p> +<p>Transports that manipulate TCP directly may use the <code>file:sendfile/{2,4,5}</code> function, which calls the sendfile syscall where applicable (on Linux, for example). Other transports can use the <code>sendfile/6</code> function exported from this module.</p> +<h3 id="_setopts_csocket__sockopts_____ok____error__atom">setopts(CSocket, SockOpts) -> ok | {error, atom()}</h3> +<dl><dt>CSocket = any()</dt> +<dd><p>Socket for this connection.</p> +</dd> +<dt>SockOpts = any()</dt> +<dd><p>Socket options.</p> +</dd> +</dl> +<p>Change options for the given socket.</p> +<p>This is mainly useful for switching to active or passive mode or to set protocol-specific options.</p> +<h3 id="_shutdown_csocket__how_____ok____error__atom">shutdown(CSocket, How) -> ok | {error, atom()}</h3> +<dl><dt>CSocket = any()</dt> +<dd><p>Socket for this connection.</p> +</dd> +<dt>How = read | write | read_write</dt> +<dd><p>Which side(s) of the socket to close.</p> +</dd> +</dl> +<p>Immediately close the socket in one or two directions.</p> +<h3 id="_sockname_socket______ok___ip__port______error__atom">sockname(Socket) -> {ok, {IP, Port}} | {error, atom()}</h3> +<dl><dt>Socket = any()</dt> +<dd><p>Socket opened with listen/1 or accept/2.</p> +</dd> +<dt>IP = inet:ip_address()</dt> +<dd><p>IP of the local endpoint.</p> +</dd> +<dt>Port = inet:port_number()</dt> +<dd><p>Port of the local endpoint.</p> +</dd> +</dl> +<p>Return the IP and port of the local endpoint.</p> <h2 id="_exports">Exports</h2> -<div class="sectionbody"> -<div class="sect2"> -<h3 id="_sendfile_transport_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3> -<div class="dlist"><dl> -<dt class="hdlist1"> -Transport = module() -</dt> -<dd> -<p> -Transport module for this socket. -</p> -</dd> -<dt class="hdlist1"> -CSocket = any() -</dt> -<dd> -<p> -Socket for this connection. -</p> -</dd> -<dt class="hdlist1"> -File = file:filename_all() | file:fd() -</dt> -<dd> -<p> -Filename or file descriptor for the file to be sent. -</p> -</dd> -<dt class="hdlist1"> -Offset = non_neg_integer() -</dt> -<dd> -<p> -Begin sending at this position in the file. -</p> -</dd> -<dt class="hdlist1"> -Bytes = non_neg_integer() -</dt> -<dd> -<p> -Send this many bytes. -</p> -</dd> -<dt class="hdlist1"> -SentBytes = non_neg_integer() -</dt> -<dd> -<p> -This many bytes were sent. -</p> -</dd> -<dt class="hdlist1"> -SfOpts = sendfile_opts() -</dt> -<dd> -<p> -Sendfile options. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Send data from a file to the given socket.</p></div> -<div class="paragraph"><p>This function emulates the function <code>file:sendfile/{2,4,5}</code> -and may be used when transports are not manipulating TCP -directly.</p></div> -</div> -</div> -</div> +<h3 id="_sendfile_transport__csocket__file__offset__bytes__sfopts______ok__sentbytes_____error__atom">sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) -> {ok, SentBytes} | {error, atom()}</h3> +<dl><dt>Transport = module()</dt> +<dd><p>Transport module for this socket.</p> +</dd> +<dt>CSocket = any()</dt> +<dd><p>Socket for this connection.</p> +</dd> +<dt>File = file:filename_all() | file:fd()</dt> +<dd><p>Filename or file descriptor for the file to be sent.</p> +</dd> +<dt>Offset = non_neg_integer()</dt> +<dd><p>Begin sending at this position in the file.</p> +</dd> +<dt>Bytes = non_neg_integer()</dt> +<dd><p>Send this many bytes.</p> +</dd> +<dt>SentBytes = non_neg_integer()</dt> +<dd><p>This many bytes were sent.</p> +</dd> +<dt>SfOpts = sendfile_opts()</dt> +<dd><p>Sendfile options.</p> +</dd> +</dl> +<p>Send data from a file to the given socket.</p> +<p>This function emulates the function <code>file:sendfile/{2,4,5}</code> and may be used when transports are not manipulating TCP directly.</p> + @@ -584,6 +288,8 @@ directly.</p></div> + <li><a href="/docs/en/ranch/1.5/manual">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> |