aboutsummaryrefslogtreecommitdiffstats
path: root/guide/handlers.md
blob: e2c1264775757909caafb042926545717b7471ac (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
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.