Improve handler interface and documentation

This change simplifies a little more the sub protocols mechanism.
Aliases have been removed. The renaming of loop handlers as long
polling handlers has been reverted.

Plain HTTP handlers now simply do their work in the init/2
callback. There is no specific code for them.

Loop handlers now follow the same return value as Websocket,
they use ok to continue and shutdown to stop.

Terminate reasons for all handler types have been documented.
The terminate callback is now appropriately called in all cases
(or should be).

Behaviors for all handler types have been moved in the module
that implement them. This means that cowboy_handler replaces
the cowboy_http_handler behavior, and similarly cowboy_loop
replaces cowboy_loop_handler, cowboy_websocket replaces
cowboy_websocket_handler. Finally cowboy_rest now has the
start of a behavior in it and will have the full list of
optional callbacks defined once Erlang 18.0 gets released.

The guide has been reorganized and should be easier to follow.

1 files changed, 0 insertions, 132 deletions

diff --git a/doc/src/guide/http_handlers.ezdoc b/doc/src/guide/http_handlers.ezdoc
deleted file mode 100644
index d846ffe..0000000
--- a/doc/src/guide/http_handlers.ezdoc
+++ /dev/null
@@ -1,132 +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/2`, is common to all handlers,
-as it is used to identify the type of handler. Plain
-HTTP handlers just return `http`.
-
-``` erlang
-init(Req, Opts) ->
-    {http, Req, Opts}.
-```
-
-This function receives the options associated with
-this route that you configured previously.
-
-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(Req, Opts) ->
-    {_, Lang} = lists:keyfind(lang, 1, Opts),
-    {http, Req, Lang}.
-```
-
-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(Req, Opts) ->
-    case lists:keyfind(lang, 1, Opts) of
-        false ->
-            Req2 = cowboy_req:reply(500, [
-                {<<"content-type">>, <<"text/plain">>}
-            ], "Missing option 'lang'.", Req),
-            {shutdown, Req2, undefined};
-        {_, Lang} ->
-            {http, Req, Lang}
-    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.
-
-You may use a state record for this. The record will make
-your handler code clearer and will allow Dialyzer to better
-type check your code.
-
-``` erlang
--record(state, {
-    lang :: en | fr
-    %% More fields here.
-}).
-
-init(Req, Opts) ->
-    {_, Lang} = lists:keyfind(lang, 1, Opts),
-    {http, Req, #state{lang=Lang}}.
-```
-
-You may also use a map. A map is interesting in that you
-do not need to define it beforehand, but is a little less
-efficient and not as well supported by Dialyzer.
-
-``` erlang
-init(Req, Opts) ->
-    {_, Lang} = lists:keyfind(lang, 1, Opts),
-    {http, Req, #{lang => Lang}.
-```
-
-:: Handling the request
-
-The second callback, `handle/2`, is specific to plain HTTP
-handlers. It's where you 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) ->
-    Req2 = cowboy_req:reply(200, [
-        {<<"content-type">>, <<"text/plain">>}
-    ], <<"Hello World!">>, Req),
-    {ok, Req2, State}.
-```
-
-:: Cleaning up
-
-The third and last callback, `terminate/3`, is optional.
-
-``` 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.