umgeher/cowboy
0
Fork 0
mirror of https://github.com/ninenines/cowboy.git synced 2025-07-15 12:40:25 +00:00
Code Issues Wiki Activity

Unify the init and terminate callbacks

Browse source 
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 commit is contained in:
Loïc Hoguin 2014-09-26 15:58:44 +03:00
parent fd37fad592
commit 5ce4c2bfb4
70 changed files with 668 additions and 1015 deletions
Download patch file Download diff file Expand all files Collapse all files

33
doc/src/guide/rest_handlers.ezdoc
View file

@ -8,18 +8,20 @@ The REST handler is the recommended way to handle requests.
:: Initialization
First, the `init/3` callback is called. This callback is common
First, the `init/2` callback is called. This callback is common
to all handlers. To use REST for the current request, this function
must return an `upgrade` tuple.
must return a `rest` tuple.
``` erlang
init({tcp, http}, Req, Opts) ->
{upgrade, protocol, cowboy_rest}.
init(Req, Opts) ->
{rest, Req, Opts}.
```
Cowboy will then switch to the REST protocol and start executing
the state machine, starting from `rest_init/2` if it's defined,
and ending with `rest_terminate/2` also if defined.
the state machine.
After reaching the end of the flowchart, the `terminate/3` callback
will be called if it is defined.
:: Methods
@ -36,28 +38,17 @@ on what other defined callbacks return. The various flowcharts
in the next chapter should be a useful to determine which callbacks
you need.
When the request starts being processed, Cowboy will call the
`rest_init/2` function if it is defined, with the Req object
and the handler options as arguments. This function must return
`{ok, Req, State}` where `State` is the handler's state that all
subsequent callbacks will receive.
All callbacks take two arguments, the Req object and the State,
and return a three-element tuple of the form `{Value, Req, State}`.
At the end of every request, the special callback `rest_terminate/2`
will be called if it is defined. It cannot be used to send a reply,
and must always return `ok`.
All other callbacks are resource callbacks. They all take two
arguments, the Req object and the State, and return a three-element
tuple of the form `{Value, Req, State}`.
All callbacks can also return `{halt, Req, State}` to stop execution
of the request.
The following table summarizes the callbacks and their default values.
If the callback isn't defined, then the default value will be used.
Please look at the flowcharts to find out the result of each return
value.
All callbacks can also return `{halt, Req, State}` to stop execution
of the request, at which point `rest_terminate/2` will be called.
In the following table, "skip" means the callback is entirely skipped
if it is undefined, moving directly to the next step. Similarly,
"none" means there is no default value for this callback.