gun:ws_upgrade(3)

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   :: [{binary(), iodata()}]
WsOpts    :: gun:ws_opts
StreamRef :: reference()

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.

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
}).

See also

gun(3), gun:ws_send(3), gun_upgrade(3), gun_ws(3)

Gun 1.2 Function Reference

Navigation

Version select

Like my work? Donate!

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.