Name

gun:ws_upgrade - Upgrade to Websocket

Description

ws_upgrade(ConnPid, Path)
    -> ws_upgrade(ConnPid, Path, [])

ws_upgrade(ConnPid, Path, Headers)
    -> StreamRef

ws_upgrade(ConnPid, Path, Headers, WsOpts)
    -> StreamRef

ConnPid   :: pid()
Path      :: iodata()
Headers   :: gun:req_headers()
WsOpts    :: gun:ws_opts()
StreamRef :: gun:stream_ref()

Upgrade to Websocket.

The behavior of this function depends on the protocol selected.

HTTP/1.1 cannot handle Websocket and HTTP requests concurrently. The upgrade, if successful, will result in the complete takeover of the connection. Any subsequent HTTP requests will be rejected.

Gun does not currently support Websocket over HTTP/2.

By default Gun will take the Websocket options from the connection’s ws_opts.

Websocket subprotocol negotiation is enabled when the protocols option is given. It takes a subprotocol name and a module implementing the gun_ws_protocol(3) behavior.

Arguments

ConnPid: The pid of the Gun connection process.
Path: Path to the resource.
Headers: Additional request headers.
WsOpts: Configuration for the Websocket protocol.

Return value

A reference that identifies the newly created stream is returned. It is this reference that must be passed in subsequent calls and will be received in messages related to this new stream.

Changelog

1.0: Function introduced.

Examples

Upgrade to Websocket

StreamRef = gun:ws_upgrade(ConnPid, "/ws", [
    {<<"sec-websocket-protocol">>, <<"chat">>}
]).
receive
    {gun_upgrade, ConnPid, StreamRef, [<<"websocket">>], _} ->
        ok
after 5000 ->
    error(timeout)
end.

Upgrade to Websocket with different options

StreamRef = gun:ws_upgrade(ConnPid, "/ws", [], #{
    compress => false
}).

Upgrade to Websocket with protocol negotiation

StreamRef = gun:ws_upgrade(ConnPid, "/ws", [], #{
    protocols => [
        {<<"mqtt">>, gun_ws_mqtt_h},
        {<<"v12.stomp">>, gun_ws_stomp_h}
    ]
}).