From b13c07932dfe76dfee29a0c5ce1166423faee77d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Fri, 23 Dec 2016 15:33:21 +0100 Subject: Update the cowboy_handler manual Also fixes a small mistake in cowboy_websocket. --- doc/src/manual/cowboy_handler.asciidoc | 114 ++++++++++++--------------------- 1 file changed, 42 insertions(+), 72 deletions(-) (limited to 'doc/src/manual/cowboy_handler.asciidoc') diff --git a/doc/src/manual/cowboy_handler.asciidoc b/doc/src/manual/cowboy_handler.asciidoc index fbbe761..28ac311 100644 --- a/doc/src/manual/cowboy_handler.asciidoc +++ b/doc/src/manual/cowboy_handler.asciidoc @@ -2,98 +2,68 @@ == Name -cowboy_handler - handler middleware and behaviour +cowboy_handler - Plain HTTP handlers == Description -The `cowboy_handler` middleware executes the handler passed -through the environment values `handler` and `handler_opts`, -and adds the result of this execution to the environment as -the value `result`, indicating that the request has been -handled and received a response. +The `cowboy_handler` middleware executes the handler selected +by the router or any other preceding middleware. -Environment input: +This middleware takes the handler module and initial state +from the `handler` and `handler_opts` environment values, +respectively. On completion, it adds a `result` value to +the middleware environment, containing the return value +of the `terminate/3` callback (if defined) and `ok` otherwise. -handler = module():: Handler to be executed. -handler_opts = any():: Options to be passed to the handler. - -Environment output: - -result = ok:: Result of the request. - -This module also defines the `cowboy_handler` behaviour that -defines the basic interface for handlers. All Cowboy handlers -implement at least the `init/2` callback, and may implement -the `terminate/3` callback optionally. - -== Terminate reasons - -The following values may be received as the terminate reason -in the optional `terminate/3` callback. Different handler types -may define additional terminate reasons. - -normal:: - The connection was closed normally. - -{crash, Class, Reason}:: - A crash occurred in the handler. `Class` and `Reason` can be - used to obtain more information about the crash. The function - `erlang:get_stacktrace/0` can also be called to obtain the - stacktrace of the process when the crash occurred. +This module also defines a callback interface for handling +HTTP requests. == Callbacks -=== init(Req, Opts) -> {ok, Req, State} | {Module, Req, State} | {Module, Req, State, hibernate | Timeout} | {Module, Req, State, Timeout, hibernate} +Plain HTTP handlers implement the following interface: -Req = cowboy_req:req():: The Req object. -Opts = any():: Handler options. -State = any():: Handler state. -Module = module():: Module of the sub-protocol to use. -Timeout = timeout():: Timeout passed to the sub-protocol, when applicable. +[source,erlang] +---- +init(Req, State) -> {ok, Req, State} -Process the request. +terminate(Reason, Req, State) -> ok %% optional -This function can be used to switch to an alternate handler -type by returning the name of the module to be used, along -with a few options. +Req :: cowboy_req:req() +State :: any() +Reason :: normal + | {crash, error | exit | throw, any()} +---- -For basic handlers this is the function where the response -should be sent. If no response is sent, Cowboy will ensure -that a `204 No Content` response is sent. +These two callbacks are common to all handlers. -A crash in this callback will result in `terminate/3` being -called if it is defined, with the `State` argument set to -the value of `Opts` originally given to the `init/2` callback. +Plain HTTP handlers do all their work in the `init/2` +callback. Returning `ok` terminates the handler. If no +response is sent, Cowboy will send a `204 No Content`. -=== terminate(Reason, Req, State) -> ok +The optional `terminate/3` callback will ultimately be called +with the reason for the termination of the handler. +Cowboy will terminate the process right after this. There +is no need to perform any cleanup in this callback. -Reason = any():: Reason for termination. -Req = cowboy_req:req():: The Req object. -State = any():: Handler state. +The following terminate reasons are defined for plain HTTP +handlers: -Perform any necessary cleanup of the state. - -This callback should release any resource currently in use, -clear any active timer and reset the process to its original -state, as it might be reused for future requests sent on the -same connection. Typical plain HTTP handlers rarely need to -use it. +normal:: + The connection was closed normally. -A crash in this callback or an invalid return value will -result in the closing of the connection and the termination -of the process. +{crash, Class, Reason}:: + A crash occurred in the handler. `Class` and `Reason` can be + used to obtain more information about the crash. The function + `erlang:get_stacktrace/0` can also be called to obtain the + stacktrace of the process when the crash occurred. == Exports -=== terminate(Reason, Req, State, Handler) -> ok +The following function should be called by modules implementing +custom handlers to execute the optional terminate callback: -Reason = any():: Reason for termination. -Req = cowboy_req:req():: The Req object. -State = any():: Handler state. -Handler = module():: Handler module. +* link:man:cowboy_handler:terminate(3)[cowboy_handler:terminate(3)] - Terminate the handler -Call the optional `terminate/3` callback if it exists. +== See also -This function should always be called at the end of the execution -of a handler, to give it a chance to clean up or perform -miscellaneous operations. +link:man:cowboy(7)[cowboy(7)] -- cgit v1.2.3