From 2f0d68362245535f121f65a2b1b1723d8453a661 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Fri, 18 Jan 2013 00:54:41 +0100
Subject: Add hooks documentation to the guide

---
 guide/hooks.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 2 deletions(-)

(limited to 'guide')

diff --git a/guide/hooks.md b/guide/hooks.md
index ba48c4a..d4b520a 100644
--- a/guide/hooks.md
+++ b/guide/hooks.md
@@ -4,9 +4,74 @@ Hooks
 On request
 ----------
 
-@todo Describe.
+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.
 
 On response
 -----------
 
-@todo Describe.
+The `onresponse` hook is called right before sending the response
+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.
+
+You can specify the `onresponse` hook when creating the listener also.
+
+``` erlang
+cowboy:start_http(my_http_listener, 100,
+    [{port, 8080}],
+    [
+        {env, [{dispatch, Dispatch}]},
+        {onresponse, fun ?MODULE:custom_404_hook/4}
+    ]
+).
+```
+
+The following hook function will provide a custom body for 404 errors
+when it has not been provided before, and will let Cowboy proceed with
+the default response otherwise.
+
+``` erlang
+custom_404_hook(404, Headers, <<>>, Req) ->
+    {ok, Req2} = cowboy_req:reply(404, Headers, <<"404 Not Found.">>, Req),
+    Req2;
+custom_404_hook(_, _, _, Req) ->
+    Req.
+```
+
+Again, make sure to always return the last request object obtained.
-- 
cgit v1.2.3