diff options
Diffstat (limited to 'doc/src/manual/cowboy_handler.asciidoc')
-rw-r--r-- | doc/src/manual/cowboy_handler.asciidoc | 99 |
1 files changed, 99 insertions, 0 deletions
diff --git a/doc/src/manual/cowboy_handler.asciidoc b/doc/src/manual/cowboy_handler.asciidoc new file mode 100644 index 0000000..fbbe761 --- /dev/null +++ b/doc/src/manual/cowboy_handler.asciidoc @@ -0,0 +1,99 @@ += cowboy_handler(3) + +== Name + +cowboy_handler - handler middleware and behaviour + +== 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. + +Environment input: + +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. + +== Callbacks + +=== init(Req, Opts) -> {ok, Req, State} | {Module, Req, State} | {Module, Req, State, hibernate | Timeout} | {Module, Req, State, Timeout, hibernate} + +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. + +Process the request. + +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. + +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. + +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. + +=== terminate(Reason, Req, State) -> ok + +Reason = any():: Reason for termination. +Req = cowboy_req:req():: The Req object. +State = any():: Handler state. + +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. + +A crash in this callback or an invalid return value will +result in the closing of the connection and the termination +of the process. + +== Exports + +=== terminate(Reason, Req, State, Handler) -> ok + +Reason = any():: Reason for termination. +Req = cowboy_req:req():: The Req object. +State = any():: Handler state. +Handler = module():: Handler module. + +Call the optional `terminate/3` callback if it exists. + +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. |