cowboy/doc/src/guide/handlers.asciidoc

[[handlers]]
== Handlers

Handlers are Erlang modules that handle HTTP requests.

=== Plain HTTP handlers

The most basic handler in Cowboy implements the mandatory
`init/2` callback, manipulates the request, optionally
sends a response and then returns.

This callback receives the xref:req[Req object] and the options
defined during the xref:routing[router configuration].

A handler that does nothing would look like this:

[source,erlang]
----
init(Req, _Opts) ->
    {ok, Req, #state{}}.
----

Despite sending no reply, a `204 No Content` reply will be
sent to the client, as Cowboy makes sure that a reply is
sent for every request.

We need to use the Req object for sending a reply.

[source,erlang]
----
init(Req, _Opts) ->
    Req2 = cowboy_req:reply(200, [
        {<<"content-type">>, <<"text/plain">>}
    ], <<"Hello World!">>, Req),
    {ok, Req2, #state{}}.
----

As you can see we return a 3-tuple. `ok` means that the
handler ran successfully. The Req object is returned as
it may have been modified as is the case here: replying
returns a modified Req object that you need to return
back to Cowboy for proper operations.

The last value of the tuple is a state that will be used
in every subsequent callbacks to this handler. Plain HTTP
handlers only have one additional callback, the optional
`terminate/3`.

=== Other handlers

The `init/2` callback can also be used to inform Cowboy
that this is a different kind of handler and that Cowboy
should switch to it. To do this you simply need to return
the module name of the handler type you want to switch to.

Cowboy comes with three handler types you can switch to:
xref:rest_handlers[cowboy_rest], xref:ws_handlers[cowboy_websocket]
and xref:loop_handlers[cowboy_loop]. In addition to those you
can define your own handler types.

Switching is simple. Instead of returning `ok`, you simply
return the name of the handler type you want to use. The
following snippet switches to a Websocket handler:

[source,erlang]
----
init(Req, _Opts) ->
	{cowboy_websocket, Req, #state{}}.
----

You can also switch to your own custom handler type:

[source,erlang]
----
init(Req, _Opts) ->
	{my_handler_type, Req, #state{}}.
----

How to implement a custom handler type is described in the
xref:sub_protocols[Sub protocols] chapter.

=== Cleaning up

All handlers coming with Cowboy allow the use of the optional
`terminate/3` callback.

[source,erlang]
----
terminate(_Reason, Req, State) ->
    ok.
----

This callback is strictly reserved for any required cleanup.
You cannot send a response from this function. There is no
other return value.

If you used the process dictionary, timers, monitors or may
be receiving messages, then you can use this function to clean
them up, as Cowboy might reuse the process for the next
keep-alive request.

Note that while this function may be called in a Websocket
handler, it is generally not useful to do any clean up as
the process terminates immediately after calling this callback
when using Websocket.