cowboy/doc/src/guide/sub_protocols.ezdoc

::: Sub protocols

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.

:: Usage

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.

``` erlang
init(Req, _Opts) ->
	{cowboy_websocket, Req, #state{}}.
```

The return value may also have a `Timeout` value and/or the
atom `hibernate`. These options are useful for long living
connections. When they are not provided, the timeout value
defaults to `infinity` and the hibernate value to `run`.

The following snippet switches to the `my_protocol` sub
protocol, sets the timeout value to 5 seconds and enables
hibernation:

``` erlang
init(Req, _Opts) ->
	{my_protocol, Req, #state{}, 5000, hibernate}.
```

If a sub protocol does not make use of these options, it should
crash if it receives anything other than the default values.

:: Upgrade

After the `init/2` function returns, Cowboy will then call the
`upgrade/6` function. This is the only callback defined by the
`cowboy_sub_protocol` behavior.

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 options, and the aforementioned
timeout and hibernate values.

``` erlang
upgrade(Req, Env, Handler, HandlerOpts, Timeout, Hibernate) ->
	%% Sub protocol code here.
```

This callback is expected to behave like a middleware 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.