Add an example of onresponse hooks

Also fix the guide entry on hooks.

examples/README.md

@@ -22,6 +22,9 @@ Cowboy Examples
  *  [elixir_hello_world](./elixir_hello_world):
     simplest example application with Elixir
 
+ *  [error_hook](./error_hook):
+    provide custom error pages
+
  *  [eventsource](./eventsource):
     eventsource emitter and consumer
 

examples/error_hook/README.md

@@ -0,0 +1,30 @@
+Cowboy Error Hook
+=================
+
+To compile this example you need rebar in your PATH.
+
+Type the following command:
+```
+$ rebar get-deps compile
+```
+
+You can then start the Erlang node with the following command:
+```
+./start.sh
+```
+
+Then point your browser to the indicated URL.
+
+Example
+-------
+
+``` bash
+$ curl -i http://localhost:8080
+HTTP/1.1 404 Not Found
+connection: keep-alive
+server: Cowboy
+date: Wed, 27 Feb 2013 23:32:55 GMT
+content-length: 56
+
+404 Not Found: "/" is not the path you are looking for.
+```

examples/error_hook/rebar.config

@@ -0,0 +1,4 @@
+{deps, [
+	{cowboy, ".*",
+		{git, "git://github.com/extend/cowboy.git", "master"}}
+]}.

examples/error_hook/src/error_hook.app.src

@@ -0,0 +1,15 @@
+%% Feel free to use, reuse and abuse the code in this file.
+
+{application, error_hook, [
+	{description, "Cowboy error handler example."},
+	{vsn, "1"},
+	{modules, []},
+	{registered, []},
+	{applications, [
+		kernel,
+		stdlib,
+		cowboy
+	]},
+	{mod, {error_hook_app, []}},
+	{env, []}
+]}.

examples/error_hook/src/error_hook.erl

@@ -0,0 +1,14 @@
+%% Feel free to use, reuse and abuse the code in this file.
+
+-module(error_hook).
+
+%% API.
+-export([start/0]).
+
+%% API.
+
+start() ->
+	ok = application:start(crypto),
+	ok = application:start(ranch),
+	ok = application:start(cowboy),
+	ok = application:start(error_hook).

examples/error_hook/src/error_hook_app.erl

@@ -0,0 +1,24 @@
+%% Feel free to use, reuse and abuse the code in this file.
+
+%% @private
+-module(error_hook_app).
+-behaviour(application).
+
+%% API.
+-export([start/2]).
+-export([stop/1]).
+
+%% API.
+
+start(_Type, _Args) ->
+	Dispatch = cowboy_router:compile([
+		{'_', []}
+	]),
+	{ok, _} = cowboy:start_http(http, 100, [{port, 8080}], [
+		{env, [{dispatch, Dispatch}]},
+		{onresponse, fun error_hook_responder:respond/4}
+	]),
+	error_hook_sup:start_link().
+
+stop(_State) ->
+	ok.

examples/error_hook/src/error_hook_responder.erl

@@ -0,0 +1,21 @@
+%% Feel free to use, reuse and abuse the code in this file.
+
+-module(error_hook_responder).
+
+-export([respond/4]).
+
+respond(404, Headers, <<>>, Req) ->
+	{Path, Req2} = cowboy_req:path(Req),
+	Body = <<"404 Not Found: \"", Path/binary, "\" is not the path you are looking for.\n">>,
+	Headers2 = lists:keyreplace(<<"content-length">>, 1, Headers,
+		{<<"content-length">>, integer_to_list(byte_size(Body))}),
+	{ok, Req3} = cowboy_req:reply(404, Headers2, Body, Req2),
+	Req3;
+respond(Code, Headers, <<>>, Req) when is_integer(Code), Code >= 400 ->
+	Body = ["HTTP Error ", integer_to_list(Code), $\n],
+	Headers2 = lists:keyreplace(<<"content-length">>, 1, Headers,
+		{<<"content-length">>, integer_to_list(iolist_size(Body))}),
+	{ok, Req2} = cowboy_req:reply(Code, Headers2, Body, Req),
+	Req2;
+respond(_Code, _Headers, _Body, Req) ->
+	Req.

examples/error_hook/src/error_hook_sup.erl

@@ -0,0 +1,23 @@
+%% Feel free to use, reuse and abuse the code in this file.
+
+%% @private
+-module(error_hook_sup).
+-behaviour(supervisor).
+
+%% API.
+-export([start_link/0]).
+
+%% supervisor.
+-export([init/1]).
+
+%% API.
+
+-spec start_link() -> {ok, pid()}.
+start_link() ->
+	supervisor:start_link({local, ?MODULE}, ?MODULE, []).
+
+%% supervisor.
+
+init([]) ->
+	Procs = [],
+	{ok, {{one_for_one, 10, 10}, Procs}}.

examples/error_hook/start.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+erl -pa ebin deps/*/ebin -s error_hook \
+	-eval "io:format(\"Point your browser at http://localhost:8080~n\")."

guide/hooks.md

@@ -48,7 +48,8 @@ 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.
+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 also.
 
@@ -68,7 +69,10 @@ the default response otherwise.
 
 ``` erlang
 custom_404_hook(404, Headers, <<>>, Req) ->
-    {ok, Req2} = cowboy_req:reply(404, Headers, <<"404 Not Found.">>, Req),
+    Body = <<"404 Not Found.">>,
+    Headers2 = lists:keyreplace(<<"content-length">>, 1, Headers,
+        {<<"content-length">>, integer_to_list(byte_size(Body))}),
+    {ok, Req2} = cowboy_req:reply(404, Headers2, Body, Req),
     Req2;
 custom_404_hook(_, _, _, Req) ->
     Req.