mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-15 12:40:25 +00:00
141 lines
4 KiB
Text
141 lines
4 KiB
Text
= cowboy_websocket(3)
|
|
|
|
== Name
|
|
|
|
cowboy_websocket - Websocket protocol
|
|
|
|
== Description
|
|
|
|
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 link:cowboy_handler.asciidoc[cowboy_handler] module.
|
|
|
|
The `websocket_handle/2` and `websocket_info/2` 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.
|
|
|
|
== Meta values
|
|
|
|
websocket_compress = boolean()::
|
|
Whether a websocket compression extension in in use.
|
|
|
|
websocket_version = 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.
|
|
|
|
stop::
|
|
The handler requested to close the connection, either by returning
|
|
a `stop` 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, State) -> Ret
|
|
|
|
[source,erlang]
|
|
----
|
|
Ret = {ok, State}
|
|
| {ok, State, hibernate}
|
|
| {reply, OutFrame | [OutFrame], State}
|
|
| {reply, OutFrame | [OutFrame], State, hibernate}
|
|
| {stop, State}
|
|
|
|
InFrame = {text | binary | ping | pong, binary()}
|
|
State = any()
|
|
OutFrame = cow_ws:frame()
|
|
----
|
|
|
|
Handle the data received from the Websocket connection.
|
|
|
|
This function will be called every time data is received
|
|
from the Websocket connection.
|
|
|
|
The `stop` 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, State) -> Ret
|
|
|
|
[source,erlang]
|
|
----
|
|
Ret = {ok, State}
|
|
| {ok, State, hibernate}
|
|
| {reply, OutFrame | [OutFrame], State}
|
|
| {reply, OutFrame | [OutFrame], State, hibernate}
|
|
| {stop, State}
|
|
|
|
Info = any()
|
|
State = any()
|
|
OutFrame = cow_ws: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 `stop` 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.
|