diff options
Diffstat (limited to 'doc/src/guide/websocket.asciidoc')
| -rw-r--r-- | doc/src/guide/websocket.asciidoc | 97 |
1 files changed, 49 insertions, 48 deletions
diff --git a/doc/src/guide/websocket.asciidoc b/doc/src/guide/websocket.asciidoc index f99dea7..cf32291 100644 --- a/doc/src/guide/websocket.asciidoc +++ b/doc/src/guide/websocket.asciidoc @@ -1,10 +1,10 @@ +[[websocket]] == Websocket This chapter describes how to use the Gun client for communicating with a Websocket server. -@todo recovering from connection failure -reconnecting to Websocket etc. +// @todo recovering from connection failure, reconnecting to Websocket etc. === HTTP upgrade @@ -14,33 +14,33 @@ 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. -You must use the `gun_ws:upgrade/{2,3,4}` function to upgrade +You must use the `gun:ws_upgrade/2,3,4` function to upgrade to Websocket. This function can be called anytime after connection, so you can send HTTP requests before upgrading to Websocket. .Upgrade to Websocket - [source,erlang] +---- gun:ws_upgrade(ConnPid, "/websocket"). +---- 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. .Upgrade to Websocket and request a protocol - [source,erlang] +---- gun:ws_upgrade(ConnPid, "/websocket", [ - {<<"sec-websocket-protocol">>, "mychat"} + {<<"sec-websocket-protocol">>, "mychat"} ]). +---- -You can pass the Websocket options as part of the `gun:open/{2,3}` +You can pass the Websocket options as part of the `gun:open/2,3` call when opening the connection, or using the `gun:ws_upgrade/4`. -The fourth argument is those same options. This function call -will crash if the options are incorrect, unlike when passing -them through `gun:open/{2,3}`. +The fourth argument is those same options. -When the upgrade succeeds, a `gun_ws_upgrade` message is sent. +When the upgrade succeeds, a `gun_upgrade` message is sent. If the server does not understand Websocket or refused the upgrade, a `gun_response` message is sent. If Gun couldn't perform the upgrade due to an error (for example attempting @@ -52,21 +52,19 @@ a meaningful response which should be processed. In the following example we however ignore it: [source,erlang] +---- receive - {gun_ws_upgrade, ConnPid, ok, Headers} -> - upgrade_success(ConnPid); - {gun_response, ConnPid, _, _, Status, Headers} -> - exit({ws_upgrade_failed, Status, Headers}); - {gun_error, ConnPid, StreamRef, Reason} -> - exit({ws_upgrade_failed, Reason}) - %% More clauses here as needed. + {gun_upgrade, ConnPid, StreamRef, [<<"websocket">>], Headers} -> + upgrade_success(ConnPid, StreamRef); + {gun_response, ConnPid, _, _, Status, Headers} -> + exit({ws_upgrade_failed, Status, Headers}); + {gun_error, ConnPid, StreamRef, Reason} -> + exit({ws_upgrade_failed, Reason}) + %% More clauses here as needed. after 1000 -> - exit(timeout) + exit(timeout) end. - -Note that you shouldn't use the `reply_to` request option -for connections you plan to upgrade, because only the -owner of the connection will receive messages about it. +---- === Sending data @@ -74,27 +72,28 @@ 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. -Use `gun:ws_send/2` to send one or more messages to the server. - -@todo Implement sending of N frames +Use `gun:ws_send/2` to send messages to the server. .Send a text frame - [source,erlang] +---- gun:ws_send(ConnPid, {text, "Hello!"}). - -.Send a text frame, a binary frame and then close the connection - -[source,erlang] -gun:ws_send(ConnPid, [ - {text, "Hello!"}, - {binary, BinaryValue}, - close -]). +---- + +// @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 +//]). +//---- Note that if you send a close frame, Gun will close the connection -cleanly and will not attempt to reconnect afterwards, similar to -calling `gun:shutdown/1`. +cleanly and will not attempt to reconnect afterwards. === Receiving data @@ -102,15 +101,17 @@ Gun sends an Erlang message to the owner process for every Websocket message it receives. [source,erlang] +---- receive - {gun_ws, ConnPid, Frame} -> - handle_frame(ConnPid, Frame) + {gun_ws, ConnPid, StreamRef, Frame} -> + handle_frame(ConnPid, StreamRef, Frame) end. - -@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. +---- + +// @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. |