You can easily customize all error responses generated by Dream, whether from
your application, or at lower levels in the HTTP stack. This is done by passing
the ~error_handler parameter to
Dream.run. The easiest way to
get an error_handler is to call
Dream.error_template:
let my_error_template _error debug_info suggested_response =
let status = Dream.status suggested_response in
let code = Dream.status_to_int status
and reason = Dream.status_to_string status in
Dream.set_header suggested_response "Content-Type" Dream.text_html;
Dream.set_body suggested_response begin
<html>
<body>
<h1><%i code %> <%s reason %></h1>
<pre><%s debug_info %></pre>
</body>
</html>
end;
Lwt.return suggested_response
let () =
Dream.run ~error_handler:(Dream.error_template my_error_template)
@@ Dream.logger
@@ Dream.not_found$ cd example/9-error
$ opam install --deps-only --yes .
$ dune exec --root . ./error.exeWe kept the error template simple for the sake of the example, but this is where you'd put in neat graphics to make a beautiful error page!
Dream will call the error template for every single error response it generates:
4xxand5xxerror responses returned by your application.- Exceptions raised by your application.
- Whenever the lower-level HTTP servers want to send a response; for instance,
a
400 Bad Requestdue to malformed headers.
The suggested_response argument contains a skeleton response. It is either the
response returned by your application in case (1), an empty 500 Internal Server Error if your application raised an exception (2), or a 500 Internal Server Error or 400 Bad Request suggested by the HTTP servers in response to
lower-level failures (3).
The easiest thing to do is to decorate suggested_response with a fancy
response body, and maybe add some headers. However, you can do anything here,
including return a completely new response.
debug_info is a multiline string containing the same information as in the
previous example, 8-debug.
If you don't customize the error handler, Dream defaults to sending only empty responses, so that your application can be fully localization-friendly — even at the lowest levels. Rather than leaking hardcoded English strings, Dream relies on the user's browser to display its own built-in, localized error pages. This choice is also in accordance with the OWASP Error Handling Cheat Sheet.
Next steps:
a-logshows how to write messages to Dream's log.b-sessionadds session management for associating state with clients.