aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/cowboy_handler.asciidoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/manual/cowboy_handler.asciidoc')
-rw-r--r--doc/src/manual/cowboy_handler.asciidoc114
1 files changed, 42 insertions, 72 deletions
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)]