1 files changed, 100 insertions, 0 deletions
diff --git a/doc/src/guide/websocket.asciidoc b/doc/src/guide/websocket.asciidoc
new file mode 100644
index 0000000..011e457
--- /dev/null
+++ b/doc/src/guide/websocket.asciidoc
@@ -0,0 +1,100 @@
+== 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.
+
+@todo add option to disable specific protocols
+
+You must use the `gun_ws:upgrade/{2,3}` 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"}
+]).
+
+The success or failure of this operation will be sent as a
+message.
+
+@todo hmm we want the headers to be sent in the gun_ws_upgrade ok message too
+
+[source,erlang]
+receive
+	{gun_ws_upgrade, ConnPid, ok} ->
+		upgrade_success(ConnPid);
+	{gun_ws_upgrade, ConnPid, error, IsFin, Status, Headers} ->
+		exit({ws_upgrade_failed, Status, Headers});
+	%% 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 one or more messages to the server.
+
+@todo Implement sending of N frames
+
+.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
+]).
+
+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.
+
+[source,erlang]
+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.