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/gun/1.0/guide/websocket/index.html | |
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/gun/1.0/guide/websocket/index.html')
-rw-r--r-- | docs/en/gun/1.0/guide/websocket/index.html | 142 |
1 files changed, 64 insertions, 78 deletions
diff --git a/docs/en/gun/1.0/guide/websocket/index.html b/docs/en/gun/1.0/guide/websocket/index.html index a77f1319..67becc45 100644 --- a/docs/en/gun/1.0/guide/websocket/index.html +++ b/docs/en/gun/1.0/guide/websocket/index.html @@ -62,102 +62,88 @@ <h1 class="lined-header"><span>Websocket</span></h1> -<div class="paragraph"><p>This chapter describes how to use the Gun client for -communicating with a Websocket server.</p></div> -<div class="sect1"> +<p>This chapter describes how to use the Gun client for communicating with a Websocket server.</p> +<!-- @todo recovering from connection failure, reconnecting to Websocket etc.--> <h2 id="_http_upgrade">HTTP upgrade</h2> -<div class="sectionbody"> -<div class="paragraph"><p>Websocket is a protocol built on top of HTTP. To use Websocket, -you must first request for the connection to be upgraded. Only -HTTP/1.1 connections can be upgraded to Websocket, so you might -need to restrict the protocol to HTTP/1.1 if you are planning -to use Websocket over TLS.</p></div> -<div class="paragraph"><p>You must use the <code>gun:ws_upgrade/2,3,4</code> function to upgrade -to Websocket. This function can be called anytime after connection, -so you can send HTTP requests before upgrading to Websocket.</p></div> -<div class="listingblock"> -<div class="title">Upgrade to Websocket</div> -<div class="content"><!-- Generator: GNU source-highlight +<p>Websocket is a protocol built on top of HTTP. To use Websocket, you must first request for the connection to be upgraded. Only HTTP/1.1 connections can be upgraded to Websocket, so you might need to restrict the protocol to HTTP/1.1 if you are planning to use Websocket over TLS.</p> +<p>You must use the <code>gun:ws_upgrade/2,3,4</code> function to upgrade to Websocket. This function can be called anytime after connection, so you can send HTTP requests before upgrading to Websocket.</p> +<div class="listingblock"><div class="title">Upgrade to Websocket</div> +<div class="content"><!-- Generator: 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">gun:ws_upgrade</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/websocket"</span>)<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>Gun will set all the necessary headers for performing the -Websocket upgrade, but you can specify additional headers -if needed. For example you can request a custom sub-protocol.</p></div> -<div class="listingblock"> -<div class="title">Upgrade to Websocket and request a protocol</div> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt><b><font color="#000000">gun:ws_upgrade</font></b>(<font color="#009900">ConnPid</font>, <font color="#FF0000">"/websocket"</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>Gun will set all the necessary headers for performing the Websocket upgrade, but you can specify additional headers if needed. For example you can request a custom sub-protocol.</p> +<div class="listingblock"><div class="title">Upgrade to Websocket and request a protocol</div> +<div class="content"><!-- Generator: 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">gun:ws_upgrade</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/websocket"</span>, [ - {<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"mychat"</span>} -])<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>You can pass the Websocket options as part of the <code>gun:open/2,3</code> -call when opening the connection, or using the <code>gun:ws_upgrade/4</code>. -The fourth argument is those same options.</p></div> -<div class="paragraph"><p>When the upgrade succeeds, a <code>gun_upgrade</code> message is sent. -If the server does not understand Websocket or refused the -upgrade, a <code>gun_response</code> message is sent. If Gun couldn’t -perform the upgrade due to an error (for example attempting -to upgrade to Websocket on an HTTP/1.0 connection) then a -<code>gun_error</code> message is sent.</p></div> -<div class="paragraph"><p>When the server does not understand Websocket, it may send -a meaningful response which should be processed. In the -following example we however ignore it:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt><b><font color="#000000">gun:ws_upgrade</font></b>(<font color="#009900">ConnPid</font>, <font color="#FF0000">"/websocket"</font>, [ + {<font color="#990000"><<</font><font color="#FF0000">"sec-websocket-protocol"</font><font color="#990000">>></font>, <font color="#FF0000">"mychat"</font>} +])<font color="#990000">.</font></tt></pre> +</div></div> +<p>You can pass the Websocket options as part of the <code>gun:open/2,3</code> call when opening the connection, or using the <code>gun:ws_upgrade/4</code>. The fourth argument is those same options.</p> +<p>When the upgrade succeeds, a <code>gun_upgrade</code> message is sent. If the server does not understand Websocket or refused the upgrade, a <code>gun_response</code> message is sent. If Gun couldn't perform the upgrade due to an error (for example attempting to upgrade to Websocket on an HTTP/1.0 connection) then a <code>gun_error</code> message is sent.</p> +<p>When the server does not understand Websocket, it may send a meaningful response which should be processed. In the following example we however ignore it:</p> +<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: #0000FF">receive</span></span> - {<span style="color: #FF6600">gun_upgrade</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"websocket"</span><span style="color: #990000">>></span>], <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">upgrade_success</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>); - {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000080">exit</span></span>({<span style="color: #FF6600">ws_upgrade_failed</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>}); - {<span style="color: #FF6600">gun_error</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000080">exit</span></span>({<span style="color: #FF6600">ws_upgrade_failed</span>, <span style="color: #009900">Reason</span>}) - <span style="font-style: italic"><span style="color: #9A1900">%% More clauses here as needed.</span></span> -<span style="font-weight: bold"><span style="color: #0000FF">after</span></span> <span style="color: #993399">1000</span> <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</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="#0000FF">receive</font></b> + {<font color="#FF6600">gun_upgrade</font>, <font color="#009900">ConnPid</font>, <font color="#009900">StreamRef</font>, [<font color="#990000"><<</font><font color="#FF0000">"websocket"</font><font color="#990000">>></font>], <font color="#009900">Headers</font>} <font color="#990000">-></font> + <b><font color="#000000">upgrade_success</font></b>(<font color="#009900">ConnPid</font>, <font color="#009900">StreamRef</font>); + {<font color="#FF6600">gun_response</font>, <font color="#009900">ConnPid</font>, <font color="#990000">_</font>, <font color="#990000">_</font>, <font color="#009900">Status</font>, <font color="#009900">Headers</font>} <font color="#990000">-></font> + <b><font color="#000080">exit</font></b>({<font color="#FF6600">ws_upgrade_failed</font>, <font color="#009900">Status</font>, <font color="#009900">Headers</font>}); + {<font color="#FF6600">gun_error</font>, <font color="#009900">ConnPid</font>, <font color="#009900">StreamRef</font>, <font color="#009900">Reason</font>} <font color="#990000">-></font> + <b><font color="#000080">exit</font></b>({<font color="#FF6600">ws_upgrade_failed</font>, <font color="#009900">Reason</font>}) + <i><font color="#9A1900">%% More clauses here as needed.</font></i> +<b><font color="#0000FF">after</font></b> <font color="#993399">1000</font> <font color="#990000">-></font> + <b><font color="#000080">exit</font></b>(<font color="#FF6600">timeout</font>) +<b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> <h2 id="_sending_data">Sending data</h2> -<div class="sectionbody"> -<div class="paragraph"><p>Once the Websocket upgrade has completed successfully, you no -longer have access to functions for performing requests. You -can only send and receive Websocket messages.</p></div> -<div class="paragraph"><p>Use <code>gun:ws_send/2</code> to send messages to the server.</p></div> -<div class="listingblock"> -<div class="title">Send a text frame</div> -<div class="content"><!-- Generator: GNU source-highlight +<p>Once the Websocket upgrade has completed successfully, you no longer have access to functions for performing requests. You can only send and receive Websocket messages.</p> +<p>Use <code>gun:ws_send/2</code> to send messages to the server.</p> +<div class="listingblock"><div class="title">Send a text frame</div> +<div class="content"><!-- Generator: 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">gun:ws_send</span></span>(<span style="color: #009900">ConnPid</span>, {<span style="color: #FF6600">text</span>, <span style="color: #FF0000">"Hello!"</span>})<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>Note that if you send a close frame, Gun will close the connection -cleanly and will not attempt to reconnect afterwards.</p></div> -</div> -</div> -<div class="sect1"> +<pre><tt><b><font color="#000000">gun:ws_send</font></b>(<font color="#009900">ConnPid</font>, {<font color="#FF6600">text</font>, <font color="#FF0000">"Hello!"</font>})<font color="#990000">.</font></tt></pre> +</div></div> +<!-- @todo Implement sending of N frames--> +<!-- --> +<!-- .Send a text frame, a binary frame and then close the connection--> +<!-- [source,erlang]--> +<!-- ------> +<!-- gun:ws_send(ConnPid, [--> +<!-- {text, "Hello!"},--> +<!-- {binary, BinaryValue},--> +<!-- close--> +<!-- ]).--> +<!-- ------> +<p>Note that if you send a close frame, Gun will close the connection cleanly and will not attempt to reconnect afterwards.</p> <h2 id="_receiving_data">Receiving data</h2> -<div class="sectionbody"> -<div class="paragraph"><p>Gun sends an Erlang message to the owner process for every -Websocket message it receives.</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<p>Gun sends an Erlang message to the owner process for every Websocket message it receives.</p> +<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: #0000FF">receive</span></span> - {<span style="color: #FF6600">gun_ws</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Frame</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Frame</span>) -<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> -</div> -</div> +<pre><tt><b><font color="#0000FF">receive</font></b> + {<font color="#FF6600">gun_ws</font>, <font color="#009900">ConnPid</font>, <font color="#009900">StreamRef</font>, <font color="#009900">Frame</font>} <font color="#990000">-></font> + <b><font color="#000000">handle_frame</font></b>(<font color="#009900">ConnPid</font>, <font color="#009900">StreamRef</font>, <font color="#009900">Frame</font>) +<b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<!-- @todo auto ping has not been implemented yet--> +<!-- --> +<!-- Gun will automatically send ping messages to the server to keep--> +<!-- the connection alive, however if the connection dies and Gun has--> +<!-- to reconnect it will not upgrade to Websocket automatically, you--> +<!-- need to perform the operation when you receive the `gun_error`--> +<!-- message.--> + |