diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/src/guide/websocket.asciidoc | 22 | ||||
| -rw-r--r-- | doc/src/manual/gun.asciidoc | 14 |
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 |