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.

test/handlers/long_polling_h.erl

@@ -11,15 +11,15 @@
 
 init(Req, _) ->
 	erlang:send_after(200, self(), timeout),
-	{long_polling, Req, 2, 5000, hibernate}.
+	{cowboy_loop, Req, 2, 5000, hibernate}.
 
 info(timeout, Req, 0) ->
-	{ok, cowboy_req:reply(102, Req), 0};
+	{shutdown, cowboy_req:reply(102, Req), 0};
 info(timeout, Req, Count) ->
 	erlang:send_after(200, self(), timeout),
-	{loop, Req, Count - 1, hibernate}.
+	{ok, Req, Count - 1, hibernate}.
 
-terminate({normal, shutdown}, _, 0) ->
+terminate(shutdown, _, 0) ->
 	ok;
 terminate({error, overflow}, _, _) ->
 	ok.

test/handlers/loop_handler_body_h.erl

@@ -11,12 +11,12 @@
 
 init(Req, _) ->
 	self() ! timeout,
-	{long_polling, Req, undefined, 5000, hibernate}.
+	{cowboy_loop, Req, undefined, 5000, hibernate}.
 
 info(timeout, Req, State) ->
 	{ok, Body, Req2} = cowboy_req:body(Req),
 	100000 = byte_size(Body),
-	{ok, cowboy_req:reply(200, Req2), State}.
+	{shutdown, cowboy_req:reply(200, Req2), State}.
 
-terminate({normal, shutdown}, _, _) ->
+terminate(shutdown, _, _) ->
 	ok.

test/handlers/loop_handler_timeout_h.erl

@@ -1,7 +1,7 @@
 %% This module implements a loop handler that sends
 %% itself a timeout that will intentionally arrive
 %% too late, as it configures itself to only wait
-%% 200ms before closing the connection in init/3.
+%% 200ms before closing the connection in init/2.
 %% This results in a 204 reply being sent back by Cowboy.
 
 -module(loop_handler_timeout_h).
@@ -12,10 +12,10 @@
 
 init(Req, _) ->
 	erlang:send_after(1000, self(), timeout),
-	{long_polling, Req, undefined, 200, hibernate}.
+	{cowboy_loop, Req, undefined, 200, hibernate}.
 
 info(timeout, Req, State) ->
-	{ok, cowboy_req:reply(500, Req), State}.
+	{shutdown, cowboy_req:reply(500, Req), State}.
 
-terminate({normal, timeout}, _, _) ->
+terminate(timeout, _, _) ->
 	ok.

test/http_SUITE.erl

@@ -142,7 +142,6 @@ init_dispatch(Config) ->
 		{"localhost", [
 			{"/chunked_response", http_chunked, []},
 			{"/streamed_response", http_streamed, []},
-			{"/init_shutdown", http_init_shutdown, []},
 			{"/headers/dupe", http_handler,
 				[{headers, [{<<"connection">>, <<"close">>}]}]},
 			{"/set_resp/header", http_set_resp,
@@ -292,9 +291,7 @@ check_status(Config) ->
 		{403, "/static/unreadable"},
 		{404, "/not/found"},
 		{404, "/static/not_found"},
-		{500, "/handler_errors?case=handle_before_reply"},
-		{500, "/handler_errors?case=init_before_reply"},
-		{666, "/init_shutdown"}
+		{500, "/handler_errors?case=init_before_reply"}
 	],
 	_ = [{Status, URL} = begin
 		Ret = do_get(URL, Config),
@@ -342,40 +339,12 @@ echo_body_qs_max_length(Config) ->
 	{response, nofin, 413, _} = gun:await(ConnPid, Ref),
 	ok.
 
-error_chain_handle_after_reply(Config) ->
-	{ConnPid, MRef} = gun_monitor_open(Config),
-	Ref1 = gun:get(ConnPid, "/"),
-	Ref2 = gun:get(ConnPid, "/handler_errors?case=handle_after_reply"),
-	{response, nofin, 200, _} = gun:await(ConnPid, Ref1, MRef),
-	{response, nofin, 200, _} = gun:await(ConnPid, Ref2, MRef),
-	gun_is_gone(ConnPid, MRef).
-
-error_chain_handle_before_reply(Config) ->
-	{ConnPid, MRef} = gun_monitor_open(Config),
-	Ref1 = gun:get(ConnPid, "/"),
-	Ref2 = gun:get(ConnPid, "/handler_errors?case=handle_before_reply"),
-	{response, nofin, 200, _} = gun:await(ConnPid, Ref1, MRef),
-	{response, fin, 500, _} = gun:await(ConnPid, Ref2, MRef),
-	gun_is_gone(ConnPid, MRef).
-
-error_handle_after_reply(Config) ->
-	{ConnPid, MRef} = gun_monitor_open(Config),
-	Ref = gun:get(ConnPid, "/handler_errors?case=handle_after_reply"),
-	{response, nofin, 200, _} = gun:await(ConnPid, Ref, MRef),
-	gun_is_gone(ConnPid, MRef).
-
 error_init_after_reply(Config) ->
 	{ConnPid, MRef} = gun_monitor_open(Config),
 	Ref = gun:get(ConnPid, "/handler_errors?case=init_after_reply"),
 	{response, nofin, 200, _} = gun:await(ConnPid, Ref, MRef),
 	gun_is_gone(ConnPid, MRef).
 
-error_init_reply_handle_error(Config) ->
-	{ConnPid, MRef} = gun_monitor_open(Config),
-	Ref = gun:get(ConnPid, "/handler_errors?case=init_reply_handle_error"),
-	{response, nofin, 200, _} = gun:await(ConnPid, Ref, MRef),
-	gun_is_gone(ConnPid, MRef).
-
 headers_dupe(Config) ->
 	{ConnPid, MRef} = gun_monitor_open(Config),
 	Ref = gun:get(ConnPid, "/headers/dupe"),

test/http_SUITE_data/http_body_qs.erl

@@ -3,15 +3,11 @@
 -module(http_body_qs).
 
 -export([init/2]).
--export([handle/2]).
 
 init(Req, Opts) ->
-	{http, Req, Opts}.
-
-handle(Req, State) ->
 	Method = cowboy_req:method(Req),
 	HasBody = cowboy_req:has_body(Req),
-	{ok, maybe_echo(Method, HasBody, Req), State}.
+	{ok, maybe_echo(Method, HasBody, Req), Opts}.
 
 maybe_echo(<<"POST">>, true, Req) ->
 	case cowboy_req:body_qs(Req) of

test/http_SUITE_data/http_chunked.erl

@@ -3,15 +3,11 @@
 -module(http_chunked).
 
 -export([init/2]).
--export([handle/2]).
 
 init(Req, Opts) ->
-	{http, Req, Opts}.
-
-handle(Req, State) ->
 	Req2 = cowboy_req:chunked_reply(200, Req),
 	timer:sleep(100),
 	cowboy_req:chunk("chunked_handler\r\n", Req2),
 	timer:sleep(100),
 	cowboy_req:chunk("works fine!", Req2),
-	{ok, Req2, State}.
+	{ok, Req2, Opts}.

test/http_SUITE_data/http_echo_body.erl

@@ -3,18 +3,14 @@
 -module(http_echo_body).
 
 -export([init/2]).
--export([handle/2]).
 
 init(Req, Opts) ->
-	{http, Req, Opts}.
-
-handle(Req, State) ->
 	true = cowboy_req:has_body(Req),
 	Req3 = case cowboy_req:body(Req, [{length, 1000000}]) of
 		{ok, Body, Req2} -> handle_body(Req2, Body);
 		{more, _, Req2} -> handle_badlength(Req2)
 	end,
-	{ok, Req3, State}.
+	{ok, Req3, Opts}.
 
 handle_badlength(Req) ->
 	cowboy_req:reply(413, [], <<"Request entity too large">>, Req).

test/http_SUITE_data/http_errors.erl

@@ -3,7 +3,6 @@
 -module(http_errors).
 
 -export([init/2]).
--export([handle/2]).
 
 init(Req, _Opts) ->
 	#{'case' := Case} = cowboy_req:match_qs(Req, ['case']),
@@ -15,22 +14,4 @@ case_init(<<"init_before_reply">> = Case, _Req) ->
 case_init(<<"init_after_reply">> = Case, Req) ->
 	cowboy_error_h:ignore(?MODULE, case_init, 2),
     _ = cowboy_req:reply(200, [], "http_handler_crashes", Req),
-    error(Case);
-case_init(<<"init_reply_handle_error">> = Case, Req) ->
-    Req1 = cowboy_req:reply(200, [], "http_handler_crashes", Req),
-    {http, Req1, Case};
-case_init(<<"handle_before_reply">> = Case, Req) ->
-    {http, Req, Case};
-case_init(<<"handle_after_reply">> = Case, Req) ->
-    {http, Req, Case}.
-
-handle(_Req, <<"init_reply_handle_error">> = Case) ->
-	cowboy_error_h:ignore(?MODULE, handle, 2),
-    error(Case);
-handle(_Req, <<"handle_before_reply">> = Case) ->
-	cowboy_error_h:ignore(?MODULE, handle, 2),
-    error(Case);
-handle(Req, <<"handle_after_reply">> = Case) ->
-	cowboy_error_h:ignore(?MODULE, handle, 2),
-    _ = cowboy_req:reply(200, [], "http_handler_crashes", Req),
     error(Case).

test/http_SUITE_data/http_handler.erl

@@ -3,12 +3,8 @@
 -module(http_handler).
 
 -export([init/2]).
--export([handle/2]).
 
 init(Req, Opts) ->
-	{http, Req, Opts}.
-
-handle(Req, State) ->
-	Headers = proplists:get_value(headers, State, []),
-	Body = proplists:get_value(body, State, "http_handler"),
-	{ok, cowboy_req:reply(200, Headers, Body, Req), State}.
+	Headers = proplists:get_value(headers, Opts, []),
+	Body = proplists:get_value(body, Opts, "http_handler"),
+	{ok, cowboy_req:reply(200, Headers, Body, Req), Opts}.

test/http_SUITE_data/http_init_shutdown.erl

@@ -1,10 +0,0 @@
-%% Feel free to use, reuse and abuse the code in this file.
-
--module(http_init_shutdown).
-
--export([init/2]).
-
-init(Req, _) ->
-	Req2 = cowboy_req:reply(<<"666 Init Shutdown Testing">>,
-		[{<<"connection">>, <<"close">>}], Req),
-	{shutdown, Req2, undefined}.

test/http_SUITE_data/http_loop_stream_recv.erl

@@ -9,7 +9,7 @@
 init(Req, _) ->
 	receive after 100 -> ok end,
 	self() ! stream,
-	{long_polling, Req, undefined, 100}.
+	{cowboy_loop, Req, undefined, 100}.
 
 info(stream, Req, undefined) ->
 	stream(Req, 1, <<>>).
@@ -17,7 +17,7 @@ info(stream, Req, undefined) ->
 stream(Req, ID, Acc) ->
 	case cowboy_req:body(Req) of
 		{ok, <<>>, Req2} ->
-			{ok, cowboy_req:reply(200, Req2), undefined};
+			{shutdown, cowboy_req:reply(200, Req2), undefined};
 		{_, Data, Req2} ->
 			parse_id(Req2, ID, << Acc/binary, Data/binary >>)
 	end.
@@ -30,5 +30,5 @@ parse_id(Req, ID, Data) ->
 			stream(Req, ID, Data)
 	end.
 
-terminate({normal, shutdown}, _, _) ->
+terminate(shutdown, _, _) ->
 	ok.

test/http_SUITE_data/http_multipart.erl

@@ -3,14 +3,10 @@
 -module(http_multipart).
 
 -export([init/2]).
--export([handle/2]).
 
 init(Req, Opts) ->
-	{http, Req, Opts}.
-
-handle(Req, State) ->
 	{Result, Req2} = acc_multipart(Req, []),
-	{ok, cowboy_req:reply(200, [], term_to_binary(Result), Req2), State}.
+	{ok, cowboy_req:reply(200, [], term_to_binary(Result), Req2), Opts}.
 
 acc_multipart(Req, Acc) ->
 	case cowboy_req:part(Req) of

test/http_SUITE_data/http_multipart_stream.erl

@@ -3,14 +3,10 @@
 -module(http_multipart_stream).
 
 -export([init/2]).
--export([handle/2]).
 
 init(Req, Opts) ->
-	{http, Req, Opts}.
-
-handle(Req, State) ->
 	Req2 = multipart(Req),
-	{ok, cowboy_req:reply(200, Req2), State}.
+	{ok, cowboy_req:reply(200, Req2), Opts}.
 
 multipart(Req) ->
 	case cowboy_req:part(Req) of

test/http_SUITE_data/http_req_attr.erl

@@ -5,15 +5,11 @@
 -module(http_req_attr).
 
 -export([init/2]).
--export([handle/2]).
 
 init(Req, Opts) ->
-	{http, Req, Opts}.
-
-handle(Req, State) ->
 	#{attr := Attr} = cowboy_req:match_qs(Req, [attr]),
 	<<"host_and_port">> = Attr,
 	Host = cowboy_req:host(Req),
 	Port = cowboy_req:port(Req),
 	Value = [Host, "\n", integer_to_list(Port)],
-	{ok, cowboy_req:reply(200, [], Value, Req), State}.
+	{ok, cowboy_req:reply(200, [], Value, Req), Opts}.

test/http_SUITE_data/http_set_resp.erl

@@ -3,7 +3,6 @@
 -module(http_set_resp).
 
 -export([init/2]).
--export([handle/2]).
 
 init(Req, Opts) ->
 	Headers = proplists:get_value(headers, Opts, []),
@@ -14,16 +13,13 @@ init(Req, Opts) ->
 	Req3 = cowboy_req:set_resp_body(Body, Req2),
 	Req4 = cowboy_req:set_resp_header(<<"x-cowboy-test">>, <<"ok">>, Req3),
 	Req5 = cowboy_req:set_resp_cookie(<<"cake">>, <<"lie">>, [], Req4),
-	{http, Req5, undefined}.
-
-handle(Req, State) ->
-	case cowboy_req:has_resp_header(<<"x-cowboy-test">>, Req) of
-		false -> {ok, Req, State};
+	case cowboy_req:has_resp_header(<<"x-cowboy-test">>, Req5) of
+		false -> {ok, Req5, Opts};
 		true ->
-			case cowboy_req:has_resp_body(Req) of
+			case cowboy_req:has_resp_body(Req5) of
 				false ->
-					{ok, Req, State};
+					{ok, Req5, Opts};
 				true ->
-					{ok, cowboy_req:reply(200, Req), State}
+					{ok, cowboy_req:reply(200, Req5), Opts}
 			end
 	end.

test/http_SUITE_data/http_stream_body.erl

@@ -3,14 +3,10 @@
 -module(http_stream_body).
 
 -export([init/2]).
--export([handle/2]).
 
 init(Req, Opts) ->
-	{http, Req, Opts}.
-
-handle(Req, State) ->
-	Body = proplists:get_value(body, State, "http_handler_stream_body"),
-	Reply = proplists:get_value(reply, State),
+	Body = proplists:get_value(body, Opts, "http_handler_stream_body"),
+	Reply = proplists:get_value(reply, Opts),
 	SFun = fun(Socket, Transport) -> Transport:send(Socket, Body) end,
 	Req2 = case Reply of
 		set_resp ->
@@ -23,4 +19,4 @@ handle(Req, State) ->
 			SFun2 = fun(SendFun) -> lists:foreach(SendFun, Body) end,
 			cowboy_req:set_resp_body_fun(chunked, SFun2, Req)
 	end,
-	{ok, cowboy_req:reply(200, Req2), State}.
+	{ok, cowboy_req:reply(200, Req2), Opts}.

test/http_SUITE_data/http_streamed.erl

@@ -3,16 +3,12 @@
 -module(http_streamed).
 
 -export([init/2]).
--export([handle/2]).
 
 init(Req, Opts) ->
-	{http, Req, Opts}.
-
-handle(Req, State) ->
 	Req2 = cowboy_req:set([{resp_state, waiting_stream}], Req),
 	Req3 = cowboy_req:chunked_reply(200, Req2),
 	timer:sleep(100),
 	cowboy_req:chunk("streamed_handler\r\n", Req3),
 	timer:sleep(100),
 	cowboy_req:chunk("works fine!", Req3),
-	{ok, Req3, State}.
+	{ok, Req3, Opts}.

test/http_SUITE_data/rest_empty_resource.erl

@@ -3,4 +3,4 @@
 -export([init/2]).
 
 init(Req, Opts) ->
-	{rest, Req, Opts}.
+	{cowboy_rest, Req, Opts}.

test/http_SUITE_data/rest_expires.erl

@@ -7,7 +7,7 @@
 -export([last_modified/2]).
 
 init(Req, Opts) ->
-	{rest, Req, Opts}.
+	{cowboy_rest, Req, Opts}.
 
 content_types_provided(Req, State) ->
 	{[{{<<"text">>, <<"plain">>, []}, get_text_plain}], Req, State}.

test/http_SUITE_data/rest_expires_binary.erl

@@ -6,7 +6,7 @@
 -export([expires/2]).
 
 init(Req, Opts) ->
-	{rest, Req, Opts}.
+	{cowboy_rest, Req, Opts}.
 
 content_types_provided(Req, State) ->
 	{[{{<<"text">>, <<"plain">>, []}, get_text_plain}], Req, State}.

test/http_SUITE_data/rest_forbidden_resource.erl

@@ -9,7 +9,7 @@
 -export([from_text/2]).
 
 init(Req, [Forbidden]) ->
-	{rest, Req, Forbidden}.
+	{cowboy_rest, Req, Forbidden}.
 
 allowed_methods(Req, State) ->
 	{[<<"GET">>, <<"HEAD">>, <<"POST">>], Req, State}.

test/http_SUITE_data/rest_missing_callbacks.erl

@@ -6,7 +6,7 @@
 -export([content_types_provided/2]).
 
 init(Req, Opts) ->
-	{rest, Req, Opts}.
+	{cowboy_rest, Req, Opts}.
 
 allowed_methods(Req, State) ->
 	{[<<"GET">>, <<"PUT">>], Req, State}.

test/http_SUITE_data/rest_nodelete_resource.erl

@@ -6,7 +6,7 @@
 -export([get_text_plain/2]).
 
 init(Req, Opts) ->
-	{rest, Req, Opts}.
+	{cowboy_rest, Req, Opts}.
 
 allowed_methods(Req, State) ->
 	{[<<"GET">>, <<"HEAD">>, <<"DELETE">>], Req, State}.

test/http_SUITE_data/rest_param_all.erl

@@ -8,7 +8,7 @@
 -export([put_text_plain/2]).
 
 init(Req, Opts) ->
-	{rest, Req, Opts}.
+	{cowboy_rest, Req, Opts}.
 
 allowed_methods(Req, State) ->
 	{[<<"GET">>, <<"PUT">>], Req, State}.

test/http_SUITE_data/rest_patch_resource.erl

@@ -8,7 +8,7 @@
 -export([patch_text_plain/2]).
 
 init(Req, Opts) ->
-	{rest, Req, Opts}.
+	{cowboy_rest, Req, Opts}.
 
 allowed_methods(Req, State) ->
 	{[<<"HEAD">>, <<"GET">>, <<"PATCH">>], Req, State}.

test/http_SUITE_data/rest_post_charset_resource.erl

@@ -6,7 +6,7 @@
 -export([from_text/2]).
 
 init(Req, Opts) ->
-	{rest, Req, Opts}.
+	{cowboy_rest, Req, Opts}.
 
 allowed_methods(Req, State) ->
 	{[<<"POST">>], Req, State}.

test/http_SUITE_data/rest_postonly_resource.erl

@@ -6,7 +6,7 @@
 -export([from_text/2]).
 
 init(Req, Opts) ->
-	{rest, Req, Opts}.
+	{cowboy_rest, Req, Opts}.
 
 allowed_methods(Req, State) ->
 	{[<<"POST">>], Req, State}.

test/http_SUITE_data/rest_resource_etags.erl

@@ -6,7 +6,7 @@
 -export([get_text_plain/2]).
 
 init(Req, Opts) ->
-	{rest, Req, Opts}.
+	{cowboy_rest, Req, Opts}.
 
 generate_etag(Req, State) ->
 	#{type := Type} = cowboy_req:match_qs(Req, [type]),

test/http_SUITE_data/rest_simple_resource.erl

@@ -5,7 +5,7 @@
 -export([get_text_plain/2]).
 
 init(Req, Opts) ->
-	{rest, Req, Opts}.
+	{cowboy_rest, Req, Opts}.
 
 content_types_provided(Req, State) ->
 	{[{{<<"text">>, <<"plain">>, []}, get_text_plain}], Req, State}.

test/ws_SUITE_data/ws_echo.erl

@@ -7,7 +7,7 @@
 -export([websocket_info/3]).
 
 init(Req, _) ->
-	{ws, Req, undefined}.
+	{cowboy_websocket, Req, undefined}.
 
 websocket_handle({text, Data}, Req, State) ->
 	{reply, {text, Data}, Req, State};

test/ws_SUITE_data/ws_echo_timer.erl

@@ -8,7 +8,7 @@
 
 init(Req, _) ->
 	erlang:start_timer(1000, self(), <<"websocket_init">>),
-	{ws, Req, undefined}.
+	{cowboy_websocket, Req, undefined}.
 
 websocket_handle({text, Data}, Req, State) ->
 	{reply, {text, Data}, Req, State};

test/ws_SUITE_data/ws_init_shutdown.erl

@@ -4,5 +4,5 @@
 
 -export([init/2]).
 
-init(Req, _) ->
-	{shutdown, cowboy_req:reply(403, Req), undefined}.
+init(Req, Opts) ->
+	{ok, cowboy_req:reply(403, Req), Opts}.

test/ws_SUITE_data/ws_send_many.erl

@@ -8,7 +8,7 @@
 
 init(Req, Opts) ->
 	erlang:send_after(10, self(), send_many),
-	{ws, Req, Opts}.
+	{cowboy_websocket, Req, Opts}.
 
 websocket_handle(_Frame, Req, State) ->
 	{ok, Req, State}.

test/ws_SUITE_data/ws_timeout_cancel.erl

@@ -8,7 +8,7 @@
 
 init(Req, _) ->
 	erlang:start_timer(500, self(), should_not_cancel_timer),
-	{ws, Req, undefined, 1000}.
+	{cowboy_websocket, Req, undefined, 1000}.
 
 websocket_handle({text, Data}, Req, State) ->
 	{reply, {text, Data}, Req, State};

test/ws_SUITE_data/ws_timeout_hibernate.erl

@@ -7,7 +7,7 @@
 -export([websocket_info/3]).
 
 init(Req, _) ->
-	{ws, Req, undefined, 1000, hibernate}.
+	{cowboy_websocket, Req, undefined, 1000, hibernate}.
 
 websocket_handle(_Frame, Req, State) ->
 	{ok, Req, State, hibernate}.