99s

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.

HTTP upgrade

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.

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
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
gun:ws_upgrade(ConnPid, "/websocket", [
        {<<"sec-websocket-protocol">>, "mychat"}
]).

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}.

When the upgrade succeeds, a gun_ws_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 to upgrade to Websocket on an HTTP/1.0 connection) then a gun_error message is sent.

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:

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.
after 1000 ->
        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

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

Send a text frame
gun:ws_send(ConnPid, {text, "Hello!"}).
Send a text frame, a binary frame and then close the connection
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.

Receiving data

Gun sends an Erlang message to the owner process for every Websocket message it receives.

receive
        {gun_ws, ConnPid, Frame} ->
                handle_frame(ConnPid, 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.

Gun 1.0 User Guide

Navigation

Version select