aboutsummaryrefslogtreecommitdiffstats
path: root/guide/http_handlers.md
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2014-07-06 13:10:35 +0200
committerLoïc Hoguin <[email protected]>2014-07-06 13:10:35 +0200
commit078d686a0ac0aed212db97d73bd1e4a9387a4956 (patch)
tree6bbc6111fdbdfedd3bb351bf3b01c63fac0d7143 /guide/http_handlers.md
parent1a71a733c37df70c15ebfd28157b10915cd738d1 (diff)
downloadcowboy-078d686a0ac0aed212db97d73bd1e4a9387a4956.tar.gz
cowboy-078d686a0ac0aed212db97d73bd1e4a9387a4956.tar.bz2
cowboy-078d686a0ac0aed212db97d73bd1e4a9387a4956.zip
Provide installable man pages
make docs: generate Markdown and man pages in doc/ make install-docs: install man pages to be usable directly Docs are generated from the ezdoc files in doc/src/.
Diffstat (limited to 'guide/http_handlers.md')
-rw-r--r--guide/http_handlers.md149
1 files changed, 0 insertions, 149 deletions
diff --git a/guide/http_handlers.md b/guide/http_handlers.md
deleted file mode 100644
index b1e2d5c..0000000
--- a/guide/http_handlers.md
+++ /dev/null
@@ -1,149 +0,0 @@
-Handling plain HTTP requests
-============================
-
-The simplest way to handle a request is by writing a
-plain HTTP handler. It is modeled after Erlang/OTP's
-gen_server behaviour, although simplified, as Cowboy
-will simply call the three callbacks sequentially.
-
-Initialization
---------------
-
-The first callback, `init/3`, is common to all handlers,
-as it is used to identify the type of handler. Plain
-HTTP handlers just return `ok`.
-
-``` erlang
-init(_Type, Req, _Opts) ->
- {ok, Req, no_state}.
-```
-
-This function receives the name of the transport and
-protocol modules used for processing the request.
-They can be used to quickly dismiss requests. For
-example the following handler will crash when accessed
-using TCP instead of SSL.
-
-``` erlang
-init({ssl, _}, Req, _Opts) ->
- {ok, Req, no_state}.
-```
-
-This function also receives the options associated with
-this route that you configured previously. If your
-handler does not use options, then it is recommended
-you match the value `[]` directly to quickly detect
-configuration errors.
-
-``` erlang
-init(_Type, Req, []) ->
- {ok, Req, no_state}.
-```
-
-You do not need to validate the options unless they
-are user configured. If they are, and there's a
-configuration error, you may choose to crash. For
-example, this will crash if the required `lang`
-option is not found.
-
-``` erlang
-init(_Type, Req, Opts) ->
- {_, _Lang} = lists:keyfind(lang, 1, Opts),
- {ok, Req, no_state}.
-```
-
-If your users are unlikely to figure out the issue
-without explanations, then you should send a more
-meaningful error back to the user. Since we already
-replied to the user, there's no need for us to
-continue with the handler code, so we use the
-`shutdown` return value to stop early.
-
-``` erlang
-init(_Type, Req, Opts) ->
- case lists:keyfind(lang, 1, Opts) of
- false ->
- {ok, Req2} = cowboy_req:reply(500, [
- {<<"content-type">>, <<"text/plain">>}
- ], "Missing option 'lang'.", Req),
- {shutdown, Req2, no_state};
- _ ->
- {ok, Req, no_state}
- end.
-```
-
-Once the options have been validated, we can use them
-safely. So we need to pass them onward to the rest of
-the handler. That's what the third element of the return
-tuple, the state, is for.
-
-We recommend that you create a state record for this.
-The record will make your handler code clearer and
-will allow you to better use Dialyzer for type checking.
-
-``` erlang
--record(state, {
- lang :: en | fr
- %% More fields here.
-}).
-
-init(_Type, Req, Opts) ->
- {_, Lang} = lists:keyfind(lang, 1, Opts),
- {ok, Req, #state{lang=Lang}}.
-```
-
-Handling the request
---------------------
-
-The second callback, `handle/2`, is specific to plain HTTP
-handlers. It's where you, wait for it, handle the request.
-
-A handle function that does nothing would look like this:
-
-``` erlang
-handle(Req, State) ->
- {ok, Req, State}.
-```
-
-There's no other return value. To obtain information about
-the request, or send a response, you would use the Req object
-here. The Req object is documented in its own chapter.
-
-The following handle function will send a fairly original response.
-
-``` erlang
-handle(Req, State) ->
- {ok, Req2} = cowboy_req:reply(200, [
- {<<"content-type">>, <<"text/plain">>}
- ], <<"Hello World!">>, Req),
- {ok, Req2, State}.
-```
-
-Cleaning up
------------
-
-The third and last callback, `terminate/3`, will most likely
-be empty in your handler.
-
-``` 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.
-
-The chances of any of this happening in your handler are pretty
-thin however. The use of the process dictionary is discouraged
-in Erlang code in general. And if you need to use timers, monitors
-or to receive messages, you are better off with a loop handler,
-a different kind of handler meant specifically for this use.
-
-This function is still available should you need it. It will
-always be called.