mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-15 20:50:24 +00:00
55 lines
1.6 KiB
Markdown
55 lines
1.6 KiB
Markdown
Handlers
|
|
========
|
|
|
|
Purpose
|
|
-------
|
|
|
|
Handlers are Erlang modules that represent a resource.
|
|
|
|
Handlers must process the request and send a reply. The nature of the
|
|
reply will vary between handlers.
|
|
|
|
Different kinds of handlers can be combined in a single module. This
|
|
allows a module to handle both websocket and long-polling code in a
|
|
single place, for example.
|
|
|
|
Protocol upgrades
|
|
-----------------
|
|
|
|
Cowboy features many different handlers: HTTP handlers, loop handlers,
|
|
websocket handlers, REST handlers and static handlers. All of them
|
|
have a common entry point: the `init/3` function.
|
|
|
|
By default, Cowboy considers your handler to be an HTTP handler.
|
|
|
|
To switch to a different protocol, like, for example, Websocket,
|
|
you must perform a protocol upgrade. This is done by returning
|
|
a protocol upgrade tuple at the end of `init/3`.
|
|
|
|
The following snippet upgrades the handler to `my_protocol`.
|
|
|
|
``` erlang
|
|
init(_Any, _Req, _Opts) ->
|
|
{upgrade, protocol, my_protocol}.
|
|
```
|
|
|
|
Cowboy comes with two protocol upgrades: `cowboy_rest` and
|
|
`cowboy_websocket`. Use these values in place of `my_protocol`
|
|
to use them.
|
|
|
|
Custom protocol upgrades
|
|
------------------------
|
|
|
|
The `my_protocol` module above will be used for further processing
|
|
of the request. It requires only one callback, `upgrade/4`.
|
|
|
|
It receives the request object, the middleware environment, and
|
|
the handler this request has been routed to along with its options.
|
|
|
|
``` erlang
|
|
upgrade(Req, Env, Handler, HandlerOpts) ->
|
|
%% ...
|
|
```
|
|
|
|
This callback is expected to behave like any middleware. Please
|
|
see the corresponding chapter for more information.
|