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

=== 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
[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"}
]).
----

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.

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
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:

[source,erlang]
----
receive
    {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)
end.
----

=== 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 messages to the server.

.Send a text frame
[source,erlang]
----
gun:ws_send(ConnPid, {text, "Hello!"}).
----

// @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 but will attempt to reconnect afterwards.

=== Receiving data

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

[source,erlang]
----
receive
    {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.