cowboy_websocket

The cowboy_websocket module implements the Websocket protocol.

This module is a sub protocol that defines four callbacks to be implemented by handlers. The init/2 and terminate/3 callbacks are common to all handler types and are documented in the manual for the cowboy_handler module.

The websocket_handle/3 and websocket_info/3 callbacks are specific to Websocket handlers and will be called as many times as necessary until the Websocket connection is closed.

The init/2 callback can be used to negotiate Websocket protocol extensions with the client. It is highly recommended to return a timeout value from this callback to ensure that the process is terminated when no data has been received during that timespan. The default timeout is infinity, which should only be used if you have alternate means of ending inactive connections.

Cowboy will terminate the process right after closing the Websocket connection. This means that there is no real need to perform any cleanup in the optional terminate/3 callback.

Types

close_code() = 1000..4999

Reason for closing the connection.

frame() = close | ping | pong | {text | binary | close | ping | pong, iodata()} | {close, close_code(), iodata()}

Frames that can be sent to the client.

Meta values

websocket_compress

Type: true | false

Whether a websocket compression extension in in use.

websocket_version

Type: 7 | 8 | 13

The version of the Websocket protocol being used.

Terminate reasons

The following values may be received as the terminate reason in the optional terminate/3 callback.

normal

The connection was closed normally before establishing a Websocket connection. This typically happens if an ok tuple is returned from the init/2 callback.

remote

The remote endpoint closed the connection without giving any further details.

{remote, Code, Payload}

The remote endpoint closed the connection with the given Code and Payload as the reason.

shutdown

The handler requested to close the connection, either by returning a shutdown tuple or by sending a close frame.

timeout

The connection has been closed due to inactivity. The timeout value can be configured from init/2.

{crash, Class, Reason}

A crash occurred in the handler. Class and Reason can be used to obtain more information about the crash. The function erlang:get_stacktrace/0 can also be called to obtain the stacktrace of the process when the crash occurred.

{error, badencoding}

A text frame was sent by the client with invalid encoding. All text frames must be valid UTF-8.

{error, badframe}

A protocol error has been detected.

{error, closed}

The socket has been closed brutally without a close frame being received first.

{error, Reason}

A socket error ocurred.

Callbacks

websocket_handle(InFrame, Req, State) -> {ok, Req, State} | {ok, Req, State, hibernate} | {reply, OutFrame | [OutFrame], Req, State} | {reply, OutFrame | [OutFrame], Req, State, hibernate} | {shutdown, Req, State}

Types:

  • InFrame = {text | binary | ping | pong, binary()}
  • Req = cowboy_req:req()
  • State = any()
  • OutFrame = frame()

Handle the data received from the Websocket connection.

This function will be called every time data is received from the Websocket connection.

The shutdown return value can be used to close the connection. A close reply will also result in the connection being closed.

The hibernate option will hibernate the process until it receives new data from the Websocket connection or an Erlang message.

websocket_info(Info, Req, State) -> {ok, Req, State} | {ok, Req, State, hibernate} | {reply, OutFrame | [OutFrame], Req, State} | {reply, OutFrame | [OutFrame], Req, State, hibernate} | {shutdown, Req, State}

Types:

  • Info = any()
  • Req = cowboy_req:req()
  • State = any()
  • OutFrame = frame()

Handle the Erlang message received.

This function will be called every time an Erlang message has been received. The message can be any Erlang term.

The shutdown return value can be used to close the connection. A close reply will also result in the connection being closed.

The hibernate option will hibernate the process until it receives another message or new data from the Websocket connection.

Navigation

See also

Version select