diff options
Diffstat (limited to 'doc/src/guide/hooks.ezdoc')
-rw-r--r-- | doc/src/guide/hooks.ezdoc | 48 |
1 files changed, 5 insertions, 43 deletions
diff --git a/doc/src/guide/hooks.ezdoc b/doc/src/guide/hooks.ezdoc index e835a6f..1c19648 100644 --- a/doc/src/guide/hooks.ezdoc +++ b/doc/src/guide/hooks.ezdoc @@ -1,45 +1,7 @@ ::: Hooks -Cowboy provides two hooks. `onrequest` is called once the request -line and headers have been received. `onresponse` is called just -before sending the response. - -:: Onrequest - -The `onrequest` hook is called as soon as Cowboy finishes fetching -the request headers. It occurs before any other processing, including -routing. It can be used to perform any modification needed on the -request object before continuing with the processing. If a reply is -sent inside this hook, then Cowboy will move on to the next request, -skipping any subsequent handling. - -This hook is a function that takes a request object as argument, -and returns a request object. This function MUST NOT crash. Cowboy -will not send any reply if a crash occurs in this function. - -You can specify the `onrequest` hook when creating the listener, -inside the request options. - -``` erlang -cowboy:start_http(my_http_listener, 100, - [{port, 8080}], - [ - {env, [{dispatch, Dispatch}]}, - {onrequest, fun ?MODULE:debug_hook/1} - ] -). -``` - -The following hook function prints the request object everytime a -request is received. This can be useful for debugging, for example. - -``` erlang -debug_hook(Req) -> - erlang:display(Req), - Req. -``` - -Make sure to always return the last request object obtained. +Hooks allow the user to customize Cowboy's behavior during specific +operations. :: Onresponse @@ -48,9 +10,9 @@ to the socket. It can be used for the purposes of logging responses, or for modifying the response headers or body. The best example is providing custom error pages. -Note that like the `onrequest` hook, this function MUST NOT crash. -Cowboy may or may not send a reply if this function crashes. If a reply -is sent, the hook MUST explicitly provide all headers that are needed. +Note that this function MUST NOT crash. Cowboy may or may not send a +reply if this function crashes. If a reply is sent, the hook MUST +explicitly provide all headers that are needed. You can specify the `onresponse` hook when creating the listener. |