aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/src/guide/websocket.asciidoc22
-rw-r--r--doc/src/manual/gun.asciidoc14
2 files changed, 30 insertions, 6 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