<!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">
<meta name="generator" content="Hugo 0.17" />
<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/bootstrap.min.css" rel="stylesheet">
<link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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>
<div class="paragraph"><p>This chapter describes how to use the Gun client for
communicating with a Websocket server.</p></div>
<div class="paragraph"><p>@todo recovering from connection failure
reconnecting to Websocket etc.</p></div>
<div class="sect1">
<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 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 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. This function call
will crash if the options are incorrect, unlike when passing
them through <code>gun:open/{2,3}</code>.</p></div>
<div class="paragraph"><p>When the upgrade succeeds, a <code>gun_ws_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 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_upgrade</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #FF6600">ok</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: #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">
<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 one or more messages to the server.</p></div>
<div class="paragraph"><p>@todo Implement sending of N frames</p></div>
<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="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.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="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">BinaryValue</span>},
<span style="color: #FF6600">close</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, similar to
calling <code>gun:shutdown/1</code>.</p></div>
</div>
</div>
<div class="sect1">
<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 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">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">Frame</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>@todo auto ping has not been implemented yet</p></div>
<div class="paragraph"><p>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 <code>gun_error</code>
message.</p></div>
</div>
</div>
<nav style="margin:1em 0">
<a style="float:left" href="https://ninenines.eu/docs/en/gun/1.0/guide/http/">
HTTP
</a>
</nav>
</div>
<div class="span3 sidecol">
<h3>
Gun
1.0
User Guide
</h3>
<ul>
<li><a href="/docs/en/gun/1.0/guide">User Guide</a></li>
<li><a href="/docs/en/gun/1.0/manual">Function Reference</a></li>
</ul>
<h4 id="docs-nav">Navigation</h4>
<h4>Version select</h4>
<ul>
<li><a href="/docs/en/gun/1.0/guide">1.0</a></li>
</ul>
</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-2016</p>
</div>
</div>
</div>
</footer>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
<script src="/js/bootstrap-carousel.js"></script>
<script src="/js/bootstrap-dropdown.js"></script>
<script src="/js/custom.js"></script>
</body>
</html>
