umgeher/cowboy
0
Fork 0
mirror of https://github.com/ninenines/cowboy.git synced 2025-07-14 20:30:23 +00:00
Code Issues Wiki Activity

Update cowboy_websocket_manual

Browse source
This commit is contained in:
Loïc Hoguin 2016-12-22 18:13:25 +01:00
parent e584412de7
commit cbc7056395
No known key found for this signature in database
GPG key ID: 71366FF21851DF03
3 changed files with 136 additions and 120 deletions
Download patch file Download diff file Expand all files Collapse all files

8
doc/src/manual/cowboy_http.asciidoc
View file

@ -9,9 +9,7 @@ cowboy_http - HTTP/1.1
The module `cowboy_http` implements HTTP/1.1 and HTTP/1.0 The module `cowboy_http` implements HTTP/1.1 and HTTP/1.0
as a Ranch protocol. as a Ranch protocol.
== Types == Options
=== opts()
[source,erlang] [source,erlang]
---- ----
@ -40,9 +38,7 @@ It can be updated without restarting listeners using the
Ranch functions `ranch:get_protocol_options/1` and Ranch functions `ranch:get_protocol_options/1` and
`ranch:set_protocol_options/2`. `ranch:set_protocol_options/2`.
=== Option descriptions The default value is given next to the option name:
The default value is given next to the option name.
env (#{}):: env (#{})::
Middleware environment. Middleware environment.

8
doc/src/manual/cowboy_http2.asciidoc
View file

@ -9,9 +9,7 @@ cowboy_http2 - HTTP/2
The module `cowboy_http2` implements HTTP/2 The module `cowboy_http2` implements HTTP/2
as a Ranch protocol. as a Ranch protocol.
== Types == Options
=== opts()
[source,erlang] [source,erlang]
---- ----
@ -31,9 +29,7 @@ It can be updated without restarting listeners using the
Ranch functions `ranch:get_protocol_options/1` and Ranch functions `ranch:get_protocol_options/1` and
`ranch:set_protocol_options/2`. `ranch:set_protocol_options/2`.
=== Option descriptions The default value is given next to the option name:
The default value is given next to the option name.
env (#{}):: env (#{})::
Middleware environment. Middleware environment.

240
doc/src/manual/cowboy_websocket.asciidoc
View file

@ -2,140 +2,164 @@
== Name == Name
cowboy_websocket - Websocket protocol cowboy_websocket - Websocket
== Description == Description
The `cowboy_websocket` module implements the Websocket protocol. The module `cowboy_websocket` implements Websocket
as a Ranch protocol. It also defines a callback interface
for handling Websocket connections.
This module is a sub protocol that defines four callbacks to == Options
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 [source,erlang]
specific to Websocket handlers and will be called as many times ----
as necessary until the Websocket connection is closed. opts() :: #{
websocket_compress := boolean()
}
----
The `init/2` callback can be used to negotiate Websocket protocol Configuration for the 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 This configuration is passed to Cowboy when starting listeners
Websocket connection. This means that there is no real need to using `cowboy:start_clear/4` or `cowboy:start_tls/4` functions.
perform any cleanup in the optional `terminate/3` callback.
== Meta values It can be updated without restarting listeners using the
Ranch functions `ranch:get_protocol_options/1` and
`ranch:set_protocol_options/2`.
websocket_compress = boolean():: The default value is given next to the option name:
Whether a websocket compression extension in in use.
websocket_version = 7 | 8 | 13:: websocket_compress (false)::
The version of the Websocket protocol being used. Whether to enable the Websocket frame compression
extension. Frames will only be compressed for the
== Terminate reasons clients that support this extension.
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 == Callbacks
=== websocket_handle(InFrame, State) -> Ret Websocket handlers must implement the following callback
interface:
[source,erlang] [source,erlang]
---- ----
Ret = {ok, State} init(Req, State)
| {ok, State, hibernate} -> {cowboy_websocket, Req, State}
| {reply, OutFrame | [OutFrame], State} | {cowboy_websocket, Req, State, hibernate}
| {reply, OutFrame | [OutFrame], State, hibernate} | {cowboy_websocket, Req, State, timeout()}
| {stop, State} | {cowboy_websocket, Req, State, timeout(), hibernate}
InFrame = {text | binary | ping | pong, binary()} websocket_init(State) -> CallResult %% optional
State = any() websocket_handle(InFrame, State) -> CallResult
OutFrame = cow_ws:frame() websocket_info(Info, State) -> CallResult
terminate(Reason, undefined, State) -> any() %% optional
Req :: cowboy_req:req()
State :: any()
InFrame :: {text | binary | ping | pong, binary()}
OutFrame :: cow_ws:frame()
Info :: any()
CallResult :: {ok, State}
| {ok, State, hibernate}
| {reply, OutFrame | [OutFrame], State}
| {reply, OutFrame | [OutFrame], State, hibernate}
| {stop, State}
Reason :: normal | stop | timeout
| remote | {remote, cow_ws:close_code(), binary()}
| {error, badencoding | badframe | closed | atom()}
| {crash, error | exit | throw, any()}
---- ----
Handle the data received from the Websocket connection. The `init/2` callback is common to all handlers. To upgrade
the connection to Websocket, it must return `cowboy_websocket`
as the first element of the tuple.
This function will be called every time data is received Any operation requiring the HTTP request must be done in the
from the Websocket connection. `init/2` function, as the Req object will not be available
after it returns. Websocket sub-protocol selection should
therefore be done in this function.
The `stop` return value can be used to close the The optional `websocket_init/1` callback will be called once
connection. A close reply will also result in the connection the connection has been upgraded to Websocket. It can be used
being closed. to perform any required initialization of the handler.
The `hibernate` option will hibernate the process until Note that the `init/2` function does not run in the same
it receives new data from the Websocket connection or an process as the Websocket callbacks. Any Websocket-specific
Erlang message. initialization must be done in `websocket_init/1`.
=== websocket_info(Info, State) -> Ret The `websocket_handle/2` callback will be called for every
frame received. The `websocket_info/2` callback will be
called for every Erlang message received.
[source,erlang] All three Websocket callbacks may send one or more frames
---- back to the client (by returning a `reply` tuple) or terminate
Ret = {ok, State} the connection (by sending a `close` frame or returning a `stop`
| {ok, State, hibernate} tuple).
| {reply, OutFrame | [OutFrame], State}
| {reply, OutFrame | [OutFrame], State, hibernate}
| {stop, State}
Info = any() The optional `terminate/3` callback will ultimately be called
State = any() with the reason for the termination of the connection. This
OutFrame = cow_ws:frame() callback is common to all handlers. Note that Websocket has
---- no concept of requests so it sets the second argument to
undefined.
Handle the Erlang message received. Cowboy will terminate the process right after closing the
Websocket connection. This means that there is no need to
perform any cleanup in the `terminate/3` callback.
This function will be called every time an Erlang message The following terminate reasons are defined for Websocket
has been received. The message can be any Erlang term. connections:
The `stop` return value can be used to close the normal::
connection. A close reply will also result in the connection The connection was closed normally before establishing a Websocket
being closed. connection. This typically happens if an `ok` tuple is returned
from the `init/2` callback.
The `hibernate` option will hibernate the process until remote::
it receives another message or new data from the Websocket The remote endpoint closed the connection without giving any
connection. 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.
== Changelog
* *2.0*: The Req object is no longer passed to Websocket callbacks.
* *2.0*: The callback `websocket_terminate/3` was removed in favor of `terminate/3`.
* *1.0*: Protocol introduced.
== See also
link:man:cowboy(7)[cowboy(7)],
link:man:cowboy_http(3)[cowboy_http(3)],
link:man:cowboy_http2(3)[cowboy_http2(3)]