diff options
Diffstat (limited to 'docs/en/cowboy/1.0/guide/ws_handlers')
| -rw-r--r-- | docs/en/cowboy/1.0/guide/ws_handlers/index.html | 327 |
1 files changed, 0 insertions, 327 deletions
diff --git a/docs/en/cowboy/1.0/guide/ws_handlers/index.html b/docs/en/cowboy/1.0/guide/ws_handlers/index.html deleted file mode 100644 index fe712da7..00000000 --- a/docs/en/cowboy/1.0/guide/ws_handlers/index.html +++ /dev/null @@ -1,327 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta charset="utf-8"> - <title>Nine Nines Support: Cowboy User Guide</title> - <meta name="viewport" content="width=device-width, initial-scale=1.0"> - <!-- Change them or set them up as you like --> - <meta name="description" content=""> - <meta name="author" content="(Soft10) Pol Cámara"> - - <!-- Stylesheets --> - <link href='http://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 href="js/google-code-prettify/prettify.css" rel="stylesheet"> --> - <link href="/css/sh99s.css" rel="stylesheet"/> - - <!-- Enables html5 support on older browsers, other js is placed at the end of the page to speed up loading --> - <!--[if lt IE 9]> - <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script> - <![endif]--> - - <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"> - <link rel="alternate" href="/feeds/atom.xml" type="application/atom+xml" title="Nine Nines Atom Feed"> - </head> - - <body class="big_text docs"> - <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"> - <!-- Top navigation and social icons--> - <div id="side-header"> - <nav> - <ul> - <li><a title="Erlang training" href="/training">Training</a></li> - <li><a title="Technical publications" href="/articles">Articles</a></li> - <li><a title="Our talks" href="/talks">Talks</a></li> - <li class="active"><a title="Our services" href="/support">Pricing & Sponsoring</a></li> - <li><a title="Community support" href="https://ninenines.eu/archives/extend/">Mailing Lists</a></li> - <li><a title="Contact us" href="mailto:[email protected]">Contact</a></li> - </ul> - </nav> - <ul id="social"> - <li> - <a href="https://github.com/ninenines" title="Check our Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> - </li> - <li class="dropdown" id="twitter-links"> - <a href="#twitter-links" class="dropdown-toggle" data-toggle="dropdown" title="Follow us on Twitter"> - <img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png" alt="Twitter"> - </a> - <ul class="dropdown-menu"> - <li><a title="Visit Loïc Hoguin's Twitter Account" href="http://twitter.com/lhoguin">@lhoguin</a></li> - <!-- <li class="divider"></li> - <li><a title="Visit our official Twitter account" href="#">@99s</a></li> --> - </ul> - </li> - <!-- <li> - <a href="/css/" title="Add us on Linkedin"><img src="/img/ico_linkedin.png" data-hover="img/ico_linkedin_alt.png" alt="Linkedin"></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>Handling Websocket connections</span></h1> - -<p>A special handler is required for handling Websocket connections. Websocket handlers allow you to initialize the connection, handle incoming frames from the socket, handle incoming Erlang messages and then clean up on termination.</p> - -<p>Websocket handlers essentially act as a bridge between the client and the Erlang system. They will typically do little more than socket communication and decoding/encoding of frames.</p> - -<h2 id="initialization">Initialization</h2> - -<p>First, the <code>init/3</code> callback is called. This callback is common to all handlers. To establish a Websocket connection, this function must return an <code>upgrade</code> tuple.</p> - -<script type="syntaxhighlighter" class="brush: erlang"><![CDATA[ -init(_, Req, Opts) -> - {upgrade, protocol, cowboy_websocket}. -]]></script> - -<p>It is also possible to return an update Req object and options using the longer form of this tuple.</p> - -<script type="syntaxhighlighter" class="brush: erlang"><![CDATA[ -init(_Type, Req, Opts) -> - {upgrade, protocol, cowboy_websocket, Req, Opts}. -]]></script> - -<p>Upon receiving this tuple, Cowboy will switch to the code that handles Websocket connections. It does not immediately perform the handshake however. First, it calls the <code>websocket_init/3</code> callback.</p> - -<p>This function must be used to initialize the state, and can also be used to register the process, start a timer, etc. As long as the function returns an <code>ok</code> tuple, then Cowboy performs the Websocket handshake.</p> - -<script type="syntaxhighlighter" class="brush: erlang"><![CDATA[ -websocket_init(_Type, Req, _Opts) -> - {ok, Req, #state{}}. -]]></script> - -<p>A <code>shutdown</code> tuple can be returned to refuse to perform the handshake. When doing so, Cowboy will send a <code>400 Bad Request</code> response to the client and close the connection.</p> - -<script type="syntaxhighlighter" class="brush: erlang"><![CDATA[ -websocket_init(_Type, Req, _Opts) -> - {shutdown, Req}. -]]></script> - -<p>It is also possible to perform a <code>cowboy_req:reply/{2,3,4}</code> before returning a <code>shutdown</code> tuple, allowing you to override the response sent back to the client.</p> - -<p>Note that browser support for handling Websocket connection failures may vary.</p> - -<p>If the sec-websocket-protocol header was sent with the request for establishing a Websocket connection, then the Websocket handler <em>must</em> select one of these subprotocol and send it back to the client, otherwise the client might decide to close the connection, assuming no correct subprotocol was found.</p> - -<script type="syntaxhighlighter" class="brush: erlang"><![CDATA[ -websocket_init(_Type, Req, _Opts) -> - case cowboy_req:parse_header(<<"sec-websocket-protocol">>, Req) of - {ok, undefined, Req2} -> - {ok, Req, #state{}}; - {ok, Subprotocols, Req2} -> - case lists:keymember(<<"mychat2">>, 1, Subprotocols) of - true -> - Req3 = cowboy_req:set_resp_header(<<"sec-websocket-protocol">>, - <<"mychat2">>, Req2), - {ok, Req3, #state{}}; - false -> - {shutdown, Req2} - end - end. -]]></script> - -<p>It is not recommended to wait too long inside the <code>websocket_init/3</code> function. Any extra initialization may be done after returning by sending yourself a message before doing anything. Any message sent to <code>self()</code> from <code>websocket_init/3</code> is guaranteed to arrive before any frames from the client.</p> - -<p>It is also very easy to ensure that this message arrives before any message from other processes by sending it before registering or enabling timers.</p> - -<script type="syntaxhighlighter" class="brush: erlang"><![CDATA[ -websocket_init(_Type, Req, _Opts) -> - self() ! post_init, - %% Register process here... - {ok, Req, #state{}}. - -websocket_info(post_init, Req, State) -> - %% Perform post_init initialization here... - {ok, Req, State}. -]]></script> - -<h2 id="handling_frames_from_the_client">Handling frames from the client</h2> - -<p>Cowboy will call <code>websocket_handle/3</code> whenever a text, binary, ping or pong frame arrives from the client. Note that in the case of ping and pong frames, no action is expected as Cowboy automatically replies to ping frames.</p> - -<p>The handler can decide to send frames to the socket, shutdown or just continue without sending anything.</p> - -<p>The following snippet echoes back any text frame received and ignores all others.</p> - -<script type="syntaxhighlighter" class="brush: erlang"><![CDATA[ -websocket_handle(Frame = {text, _}, Req, State) -> - {reply, Frame, Req, State}; -websocket_handle(_Frame, Req, State) -> - {ok, Req, State}. -]]></script> - -<h2 id="handling_erlang_messages">Handling Erlang messages</h2> - -<p>Cowboy will call <code>websocket_info/3</code> whenever an Erlang message arrives.</p> - -<p>The handler can decide to send frames to the socket, shutdown or just continue without sending anything.</p> - -<p>The following snippet forwards any <code>log</code> message to the socket and ignores all others.</p> - -<script type="syntaxhighlighter" class="brush: erlang"><![CDATA[ -websocket_info({log, Text}, Req, State) -> - {reply, {text, Text}, Req, State}; -websocket_info(_Info, Req, State) -> - {ok, Req, State}. -]]></script> - -<h2 id="sending_frames_to_the_socket">Sending frames to the socket</h2> - -<p>Cowboy allows sending either a single frame or a list of frames to the socket. Any frame can be sent: text, binary, ping, pong or close frames.</p> - -<p>The following example sends three frames using a single <code>reply</code> tuple.</p> - -<script type="syntaxhighlighter" class="brush: erlang"><![CDATA[ -websocket_info(hello_world, Req, State) -> - {reply, [ - {text, "Hello"}, - {text, <<"world!">>}, - {binary, <<0:8000>>} - ], Req, State}; -%% More websocket_info/3 clauses here... -]]></script> - -<p>Note that the payload for text and binary frames is of type <code>iodata()</code>, meaning it can be either a <code>binary()</code> or an <code>iolist()</code>.</p> - -<p>Sending a <code>close</code> frame will immediately initiate the closing of the Websocket connection. Be aware that any additional frames sent by the client or any Erlang messages waiting to be received will not be processed. Also note that when replying a list of frames that includes close, any frame found after the close frame will not be sent.</p> - -<h2 id="ping_and_timeout">Ping and timeout</h2> - -<p>The biggest performance improvement you can do when dealing with a huge number of Websocket connections is to reduce the number of timers that are started on the server. A common use of timers when dealing with connections is for sending a ping every once in a while. This should be done exclusively on the client side. Indeed, a server handling one million Websocket connections will perform a lot better when it doesn't have to handle one million extra timers too!</p> - -<p>Cowboy will automatically respond to ping frames sent by the client. It will still forward the frame to the handler for informative purpose, but no further action is required.</p> - -<p>Cowboy can be configured to automatically close the Websocket connection when no data arrives on the socket. It is highly recommended to configure a timeout for it, as otherwise you may end up with zombie "half-connected" sockets that may leave the process alive forever.</p> - -<p>A good timeout value is 60 seconds.</p> - -<script type="syntaxhighlighter" class="brush: erlang"><![CDATA[ -websocket_init(_Type, Req, _Opts) -> - {ok, Req, #state{}, 60000}. -]]></script> - -<p>This value cannot be changed once it is set. It defaults to <code>infinity</code>.</p> - -<h2 id="hibernate">Hibernate</h2> - -<p>Most tuples returned from handler callbacks can include an extra value <code>hibernate</code>. After doing any necessary operations following the return of the callback, Cowboy will hibernate the process.</p> - -<p>It is highly recommended to hibernate processes that do not handle much traffic. It is a good idea to hibernate all connections by default and investigate only when you start noticing increased CPU usage.</p> - -<h2 id="supporting_older_browsers">Supporting older browsers</h2> - -<p>Unfortunately Websocket is a relatively recent technology, which means that not all browsers support it. A library like <a href="https://github.com/extend/bullet">Bullet</a> can be used to emulate Websocket connections on older browsers.</p> - - -<!-- a.code --> -</div> - -<div class="span3 sidecol"> -<div class="input-append"> -<form id="form-search" class="form-search" action="#"> - <input id="input-search" type="text" placeholder="Function search" autocomplete="off" autofocus class="input-medium search-query span2"> - <button type="submit" class="btn btn-success">Go</button> -</form> -</div> - -<h3 id="docs-nav">Navigation</h3> - -<h3>See also</h3><ul><li><a href="/docs/en/cowboy/1.0/manual/">Function Reference</a></li><li><a href="/docs/en/cowboy/1.0/index.html">README</a></li></ul> - -<h3>Version select</h3> -<ul> - - <li><a href="/docs/en/cowboy/1.0/guide/"><strong>1.0</strong></a></li> - - <li><a href="/docs/en/cowboy/HEAD/guide/"><strong>HEAD</strong></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 © Nine Nines 2012-2014</p> - </div> - </div> - </div> - </footer> - - <!-- Javascript --> - <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> - - -<script type="text/javascript" src="/js/shCore.js"></script> -<script type="text/javascript" src="/js/shlang/shBrushBash.js"></script> -<script type="text/javascript" src="/js/shlang/shBrushErlang.js"></script> -<script type="text/javascript" src="/js/shlang/shBrushJScript.js"></script> -<script type="text/javascript" src="/js/shlang/shBrushPlain.js"></script> -<script type="text/javascript">SyntaxHighlighter.all();</script> - -<script type="text/javascript" src="/js/fuse.min.js"></script> -<script type="text/javascript"> -$(document).ready(function(){ - var f; - - $.getJSON("/docs/db.json", function(data){ - f = new Fuse(data, {keys: ["n"], threshold: 0.3}); - $("<ul id=\"search-results\">").insertAfter("#form-search"); - }); - - $("#input-search").keyup(function(e){if(f){if (e.which != 13 ){ - var results = f.search($(this).val()); - if (results.length == 0){ - $("#form-search").attr("action", "#"); - }else{ - $("#form-search").attr("action", results[0].l); - } - - $("#search-results").empty(); - for (var i = 0; i < 10 && i < results.length; i++){ - $("<li><a href=\"" + results[i].l + "\">" + results[i].n + "</a></li>") - .appendTo("#search-results"); - } - }}}); -}); -</script> - - </body> -</html> |