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.
This set of changes is the first step to simplify the
writing of handlers, by removing some extraneous
callbacks and making others optional.
init/3 is now init/2, its first argument being removed.
rest_init/2 and rest_terminate/2 have been removed.
websocket_init/3 and websocket_terminate/3 have been removed.
terminate/3 is now optional. It is called regardless of
the type of handler, including rest and websocket.
The return value of init/2 changed. It now returns
{Mod, Req, Opts} with Mod being either one of the four
handler type or a custom module. It can also return extra
timeout and hibernate options.
The signature for sub protocols has changed, they now
receive these extra timeout and hibernate options.
Loop handlers are now implemented in cowboy_long_polling,
and will be renamed throughout the project in a future commit.
This is a first step to improve the HTTP status codes returned
by Cowboy on crashes. We will tweak it over time.
Also fixes a small bug where two replies may have been sent
when using loop handlers under rare conditions.
Previously if a loop handler received the timeout message from a
previous request on the same connection the socket would be set to
{active, once} incorrectly - when a socket packet was already in the
message queue. This second packet would not be added to the buffer
before a Handler:info/3 call if a user message was in the message
queue before both socket packets.
When something went wrong in a handler we used to report errors
and then terminate the process normally. This doesn't work so
well with links which won't detect failure.
Now we still catch the error, but throw another one with more
details on why it happened, including the Req object information
and the stacktrace. Ranch will then print an error message with
all this information.
Because we crash directly, this also means that we will not hog
resources unnecessarily for too long when something bad happens.
If a loop handler sent a response (e.g. cowboy_req:chunked_reply/2,/3)
and then returns {loop, Req, HandlerState, hibernate} it
would have a {cowboy_req, resp_sent} message in its message queue. This
message would cause the process to immediately awaken, so it is flushed
before hibernation.
It is sometimes important to make a socket passive as it was initially
and as it is expected to be by cowboy_protocol, right after we've done
with loop handling.
We now read from the socket to be able to detect errors or TCP close
events, and buffer the data if any. Once the data receive goes over
a certain limit, which defaults to 5000 bytes, we simply close the
connection with an {error, overflow} reason.
This should have been done a *long* time ago, back when I initially
added Websocket support. This is the first part of two in improving
loop handler support with regards to socket closure.
Reason may include: {normal, shutdown} for the most normal shutdown,
{normal, timeout} for a loop handler timeout shutdown, or {error, _}
if an error occured.
Middlewares allow customizing the request processing.
All existing Cowboy project are incompatible with this commit.
You need to change `{dispatch, Dispatch}` in the protocol options
to `{env, [{dispatch, Dispatch}]}` to fix your code.
