diff options
Diffstat (limited to 'doc/src/manual/cowboy_websocket.ezdoc')
-rw-r--r-- | doc/src/manual/cowboy_websocket.ezdoc | 133 |
1 files changed, 131 insertions, 2 deletions
diff --git a/doc/src/manual/cowboy_websocket.ezdoc b/doc/src/manual/cowboy_websocket.ezdoc index 59a6248..889ddd7 100644 --- a/doc/src/manual/cowboy_websocket.ezdoc +++ b/doc/src/manual/cowboy_websocket.ezdoc @@ -2,8 +2,25 @@ The `cowboy_websocket` module implements the Websocket protocol. -The callbacks for websocket handlers are defined in the manual -for the `cowboy_websocket_handler` behaviour. +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 @@ -31,6 +48,118 @@ 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. + :: Exports None. |