From 87e279322ba8dd86d6d8ab43f90a1b591ef090d1 Mon Sep 17 00:00:00 2001
From: Michal Piotrowski <michal.piotrowski@erlang-solutions.com>
Date: Fri, 28 Sep 2018 13:43:48 +0200
Subject: Document the protocols option for Websocket

---
 doc/src/guide/websocket.asciidoc | 22 +++++++++++++++++++---
 doc/src/manual/gun.asciidoc      | 14 +++++++++++---
 src/gun.erl                      |  3 ++-
 3 files changed, 32 insertions(+), 7 deletions(-)

diff --git a/doc/src/guide/websocket.asciidoc b/doc/src/guide/websocket.asciidoc
index 418b456..8503670 100644
--- a/doc/src/guide/websocket.asciidoc
+++ b/doc/src/guide/websocket.asciidoc
@@ -26,13 +26,13 @@ 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.
+if needed. For example you can authenticate.
 
-.Upgrade to Websocket and request a protocol
+.Upgrade to Websocket using HTTP authentication
 [source,erlang]
 ----
 gun:ws_upgrade(ConnPid, "/websocket", [
-    {<<"sec-websocket-protocol">>, "mychat"}
+    {<<"authorization">>, "Basic dXNlcm5hbWU6cGFzc3dvcmQ="}
 ]).
 ----
 
@@ -40,6 +40,22 @@ 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.
 
+Gun can negotiate the protocol to be used for the Websocket
+connection. The `protocols` option can be given with a list
+of protocols accepted and the corresponding handler module.
+Note that the interface for handler modules is currently
+undocumented and must be set to `gun_ws_h`.
+
+.Upgrade to Websocket with protocol negotiation
+[source,erlang]
+----
+gun:ws_upgrade(ConnPid, "/websocket", []
+    #{protocols => [{<<"xmpp">>, gun_ws_h}]}).
+----
+
+The upgrade will fail if the server cannot satisfy the
+protocol negotiation.
+
 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
diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index 9f753b4..020c8b3 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -287,7 +287,8 @@ The pid of the process that will receive the response messages.
 [source,erlang]
 ----
 ws_opts() :: #{
-    compress => boolean()
+    compress  => boolean(),
+    protocols => [{binary(), module()}]
 }
 ----
 
@@ -295,13 +296,20 @@ Configuration for the Websocket protocol.
 
 The default value is given next to the option name:
 
-compress => boolean()::
+compress (false)::
 
 Whether to enable permessage-deflate compression. This does
 not guarantee that compression will be used as it is the
 server that ultimately decides. Defaults to false.
 
-// @todo Document default_protocol, protocols and user_opts.
+protocols ([])::
+
+A non-empty list enables Websocket protocol negotiation. The
+list of protocols will be sent in the sec-websocket-protocol
+request header. The handler module interface is currently
+undocumented and must be set to `gun_ws_h`.
+
+// @todo Document default_protocol and user_opts.
 
 == Changelog
 
diff --git a/src/gun.erl b/src/gun.erl
index 0095169..1659ee3 100644
--- a/src/gun.erl
+++ b/src/gun.erl
@@ -156,7 +156,8 @@
 
 %% @todo keepalive
 -type ws_opts() :: #{
-	compress => boolean()
+	compress => boolean(),
+	protocols => [{binary(), module()}]
 }.
 -export_type([ws_opts/0]).
 
-- 
cgit v1.2.3