diff options
authorLoïc Hoguin <[email protected]>2016-12-23 15:33:21 +0100
committerLoïc Hoguin <[email protected]>2016-12-23 15:33:21 +0100
commitb13c07932dfe76dfee29a0c5ce1166423faee77d (patch)
parent98ae01b599fcaa91f0f66ca1218cdf6c3e28d3c4 (diff)
Update the cowboy_handler manual
Also fixes a small mistake in cowboy_websocket.
3 files changed, 107 insertions, 73 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.
- 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.
+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
-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.
+ 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.
diff --git a/doc/src/manual/cowboy_handler.terminate.asciidoc b/doc/src/manual/cowboy_handler.terminate.asciidoc
new file mode 100644
index 0000000..f10d945
--- /dev/null
+++ b/doc/src/manual/cowboy_handler.terminate.asciidoc
@@ -0,0 +1,64 @@
+= cowboy_handler:terminate(3)
+== Name
+cowboy_handler:terminate - Terminate the handler
+== Description
+terminate(Reason, Req | undefined, State, Handler) -> ok
+Reason :: any()
+Req :: cowboy_req:req()
+State :: any()
+Handler :: module()
+Call the optional terminate callback if it is defined.
+Make sure to use this function at the end of the execution
+of modules that implement custom handler behaviors.
+== Arguments
+Reason for termination.
+The Req object.
+It is possible to pass `undefined` if the handler has no concept
+of requests/responses and discarded the Req object before calling
+this function.
+Handler state.
+Handler module.
+== Return value
+The atom `ok` is always returned. It can be safely ignored.
+== Changelog
+* *2.0*: Function introduced.
+== Examples
+.Terminate a handler normally
+cowboy_handler:terminate(normal, Req, State, Handler).
+== See also
diff --git a/doc/src/manual/cowboy_websocket.asciidoc b/doc/src/manual/cowboy_websocket.asciidoc
index a884811..3ae811a 100644
--- a/doc/src/manual/cowboy_websocket.asciidoc
+++ b/doc/src/manual/cowboy_websocket.asciidoc
@@ -52,7 +52,7 @@ websocket_init(State) -> CallResult %% optional
websocket_handle(InFrame, State) -> CallResult
websocket_info(Info, State) -> CallResult
-terminate(Reason, undefined, State) -> any() %% optional
+terminate(Reason, undefined, State) -> ok %% optional
Req :: cowboy_req:req()
State :: any()