init(Req, State) -> {cowboy_websocket, Req, State}.
Sub protocols are used for creating new types of handlers that provide extra functionality in a reusable way. Cowboy uses this mechanism to provide its loop, REST and Websocket handlers.
This chapter will explain how to create your own sub protocols and handler types.
To switch to a sub protocol, the init/2 callback must return
the name of the sub protocol module. Everything past this point
is handled by the sub protocol.
init(Req, State) -> {cowboy_websocket, Req, State}.
The returned tuple may also have a fourth element containing
options for the sub protocol. No option is universal. While
it will usually be a map of options, it doesn’t have to be.
For example loop handlers accept the atom hibernate.
The following snippet switches to the my_protocol sub
protocol, sets the timeout value to 5 seconds and enables
hibernation:
init(Req, State) -> {my_protocol, Req, State, #{ timeout => 5000, compress => true}}.
Sub protocols should ignore unknown options so as to not waste resources doing unnecessary validation.
After the init/2 function returns, Cowboy will call either
the upgrade/4 or the upgrade/5 function. The former is called
when no options were given; the latter when they were given.
The function is named upgrade because it mimics the mechanism
of HTTP protocol upgrades. For some sub protocols, like Websocket,
an actual upgrade is performed. For others, like REST, this is
only an upgrade at Cowboy’s level and the client has nothing to
do about it.
The upgrade callback receives the Req object, the middleware
environment, the handler and its state, and for upgrade/5
also the aformentioned options.
upgrade(Req, Env, Handler, State) -> %% Sub protocol code here. upgrade(Req, Env, Handler, State, Opts) -> %% Sub protocol code here.
These callbacks are expected to behave like middlewares and to return an updated environment and Req object.
Sub protocols are expected to call the cowboy_handler:terminate/4
function when they terminate. This function will make sure that
the optional terminate/3 callback is called, if present.