diff options
| author | Loïc Hoguin <[email protected]> | 2025-04-11 14:34:51 +0200 |
|---|---|---|
| committer | Loïc Hoguin <[email protected]> | 2025-04-11 14:34:51 +0200 |
| commit | eb808a3f8bbd97d2a2ea0114b43b708a17b44066 (patch) | |
| tree | fc142e5b11792af4f84d8634d9a8809f32344634 /docs/en/gun/2.2/guide/websocket/index.html | |
| parent | 25e93c91878b7f8536764b06d2cb72020031acd1 (diff) | |
| download | ninenines.eu-master.tar.gz ninenines.eu-master.tar.bz2 ninenines.eu-master.zip | |
Diffstat (limited to 'docs/en/gun/2.2/guide/websocket/index.html')
| -rw-r--r-- | docs/en/gun/2.2/guide/websocket/index.html | 277 |
1 files changed, 277 insertions, 0 deletions
diff --git a/docs/en/gun/2.2/guide/websocket/index.html b/docs/en/gun/2.2/guide/websocket/index.html new file mode 100644 index 00000000..291ebce3 --- /dev/null +++ b/docs/en/gun/2.2/guide/websocket/index.html @@ -0,0 +1,277 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Websocket</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + </head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Websocket</span></h1> + +<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> +<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.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<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 authenticate.</p> +<div class="listingblock"><div class="title">Upgrade to Websocket using HTTP authentication</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<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">"authorization"</font><font color="#990000">>></font>, <font color="#FF0000">"Basic dXNlcm5hbWU6cGFzc3dvcmQ="</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>Gun can negotiate the protocol to be used for the Websocket connection. The <code>protocols</code> option can be given with a list of protocols accepted and the corresponding handler module. Note that the interface for handler modules is currently undocumented and must be set to <code>gun_ws_h</code>.</p> +<div class="listingblock"><div class="title">Upgrade to Websocket with protocol negotiation</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><font color="#009900">StreamRef</font> <font color="#990000">=</font> <b><font color="#000000">gun:ws_upgrade</font></b>(<font color="#009900">ConnPid</font>, <font color="#FF0000">"/websocket"</font>, [] + #{<font color="#0000FF">protocols</font> <font color="#990000">=></font> [{<font color="#990000"><<</font><font color="#FF0000">"xmpp"</font><font color="#990000">>></font>, <font color="#FF6600">gun_ws_h</font>}]})<font color="#990000">.</font></tt></pre> +</div></div> +<p>The upgrade will fail if the server cannot satisfy the protocol negotiation.</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.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<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> +<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/3</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.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">gun:ws_send</font></b>(<font color="#009900">ConnPid</font>, <font color="#009900">StreamRef</font>, {<font color="#FF6600">text</font>, <font color="#FF0000">"Hello!"</font>})<font color="#990000">.</font></tt></pre> +</div></div> +<div class="listingblock"><div class="title">Send a text frame, a binary frame and then close the connection</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">gun:ws_send</font></b>(<font color="#009900">ConnPid</font>, <font color="#009900">StreamRef</font>, [ + {<font color="#FF6600">text</font>, <font color="#FF0000">"Hello!"</font>}, + {<b><font color="#000080">binary</font></b>, <font color="#009900">BinaryValue</font>}, + <font color="#FF6600">close</font> +])<font color="#990000">.</font></tt></pre> +</div></div> +<p>Note that if you send a close frame, Gun will close the connection cleanly but may attempt to reconnect afterwards depending on the <code>retry</code> configuration.</p> +<h2 id="_receiving_data">Receiving data</h2> +<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.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<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> +<h2 id="_automatic_reconnect_gotchas">Automatic reconnect gotchas</h2> +<p>It is recommended to disable automatic reconnect when Websocket is used because Gun cannot automatically upgrade to Websocket on reconnect, and so an undetected disconnect may lead to many error messages from Gun.</p> +<p>This can be done by setting the <code>retry</code> option to <code>0</code> when opening a connection:</p> +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#009900">ConnPid</font>} <font color="#990000">=</font> <b><font color="#000000">gun:open</font></b>(<font color="#FF0000">"localhost"</font>, <font color="#993399">12345</font>, #{ + <font color="#FF6600">retry</font> ⇒ <font color="#993399">0</font> +})<font color="#990000">.</font></tt></pre> +</div></div> + + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/gun/2.2/guide/http/"> + HTTP + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/gun/2.2/guide/internals_tls_over_tls/"> + Internals: TLS over TLS + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Gun + 2.2 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/gun/2.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/gun/2.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/gun/2.2/guide">2.2</a></li> + + <li><a href="/docs/en/gun/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/gun/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/gun/1.3/guide">1.3</a></li> + + <li><a href="/docs/en/gun/1.2/guide">1.2</a></li> + + <li><a href="/docs/en/gun/1.1/guide">1.1</a></li> + + <li><a href="/docs/en/gun/1.0/guide">1.0</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + |