aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/guide/handlers.asciidoc
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2016-01-14 13:35:25 +0100
committerLoïc Hoguin <[email protected]>2016-01-14 13:37:20 +0100
commit4023e7f4e429179fd9c2cce4487c33646c6bd327 (patch)
tree3c4e26d1b5592958e35297c82ad3069bdb642594 /doc/src/guide/handlers.asciidoc
parentb7d666cfc746f55b0a72ef8d37f703885099daf7 (diff)
downloadcowboy-4023e7f4e429179fd9c2cce4487c33646c6bd327.tar.gz
cowboy-4023e7f4e429179fd9c2cce4487c33646c6bd327.tar.bz2
cowboy-4023e7f4e429179fd9c2cce4487c33646c6bd327.zip
Convert the documentation to Asciidoc
A few small revisions were made, and Erlang.mk has been updated.
Diffstat (limited to 'doc/src/guide/handlers.asciidoc')
-rw-r--r--doc/src/guide/handlers.asciidoc105
1 files changed, 105 insertions, 0 deletions
diff --git a/doc/src/guide/handlers.asciidoc b/doc/src/guide/handlers.asciidoc
new file mode 100644
index 0000000..b6cefdd
--- /dev/null
+++ b/doc/src/guide/handlers.asciidoc
@@ -0,0 +1,105 @@
+[[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.