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.

99s