From 9dc0156ceb9ecbbd45cfa1fa574279e0fa67d717 Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Fri, 16 Apr 2021 13:37:53 -0400 Subject: [PATCH] docs: Add `error` caddyfile directive (#143) Docs for the new directive in https://github.com/caddyserver/caddy/pull/4034. Also adding a bit in `handle_errors` mentioning that `reverse_proxy` doesn't trigger errors when a response has an "error" HTTP status; not sure how to word this clearly, cause `reverse_proxy` still can trigger errors if there's no upstream or whatever. We should probably add examples for that later, and augment this paragraph to mention `handle_response` once that's merged (https://github.com/caddyserver/caddy/pull/4021) --- src/docs/markdown/caddyfile/directives.md | 2 + .../markdown/caddyfile/directives/error.md | 46 +++++++++++++++++++ .../caddyfile/directives/handle_errors.md | 9 +++- 3 files changed, 55 insertions(+), 2 deletions(-) create mode 100644 src/docs/markdown/caddyfile/directives/error.md diff --git a/src/docs/markdown/caddyfile/directives.md b/src/docs/markdown/caddyfile/directives.md index 076bc76..24c0257 100644 --- a/src/docs/markdown/caddyfile/directives.md +++ b/src/docs/markdown/caddyfile/directives.md @@ -13,6 +13,7 @@ Directive | Description **[basicauth](/docs/caddyfile/directives/basicauth)** | Enforces HTTP Basic Authentication **[bind](/docs/caddyfile/directives/bind)** | Customize the server's socket address **[encode](/docs/caddyfile/directives/encode)** | Encodes (usually compresses) responses +**[error](/docs/caddyfile/directives/error)** | Trigger an error **[file_server](/docs/caddyfile/directives/file_server)** | Serve files from disk **[handle](/docs/caddyfile/directives/handle)** | A mutually-exclusive group of directives **[handle_errors](/docs/caddyfile/directives/handle_errors)** | Defines routes for handling errors @@ -104,6 +105,7 @@ php_fastcgi file_server acme_server abort +error ``` You can override/customize this ordering by using the [`order` global option](/docs/caddyfile/options) or the [`route` directive](/docs/caddyfile/directives/route). diff --git a/src/docs/markdown/caddyfile/directives/error.md b/src/docs/markdown/caddyfile/directives/error.md new file mode 100644 index 0000000..5cf9833 --- /dev/null +++ b/src/docs/markdown/caddyfile/directives/error.md @@ -0,0 +1,46 @@ +--- +title: error (Caddyfile directive) +--- + +# error + +Triggers an error in the HTTP handler chain, with an optional message and recommended HTTP status code. + +This handler does not write a response. Instead, it's meant to be paired with the [`handle_errors`](handle_errors) directive to invoke your custom error handling logic. + + +## Syntax + +```caddy-d +error [] | [] { + message +} +``` + +- **<status>** is the HTTP status code to write. Default is `500`. +- **<message>** is the error message. Default is no error message. +- **message** is an alternate way to provide an error message; convenient if it is multiple lines. + +To clarify, the first non-matcher argument can be either a 3-digit status code, or an error message string. If it is an error message, the next argument can be the status code. + +## Examples + +Trigger an error on certain request paths, and use [`handle_errors`](handle_errors) to write a response: + +```caddy +example.com { + root * /srv + + # Trigger errors for certain paths + error /private* "Unauthorized" 403 + error /hidden* "Not found" 404 + + # Handle the error by serving an HTML page + handle_errors { + rewrite * /{http.error.status_code}.html + file_server + } + + file_server +} +``` diff --git a/src/docs/markdown/caddyfile/directives/handle_errors.md b/src/docs/markdown/caddyfile/directives/handle_errors.md index 63ee4d3..6e1493b 100644 --- a/src/docs/markdown/caddyfile/directives/handle_errors.md +++ b/src/docs/markdown/caddyfile/directives/handle_errors.md @@ -8,7 +8,12 @@ Sets up error handlers. When the normal HTTP request handlers return an error, normal processing stops and the error handlers are invoked. Error handlers form a route which is just like normal routes, and they can do anything that normal routes can do. This enables great control and flexibility when handling errors during HTTP requests. For example, you can serve static error pages, templated error pages, or reverse proxy to another backend to handle errors. -A request's context is carried into error routes, so any values set on the request context such as [site root](/docs/caddyfile/directives/root) will be preserved in error handlers, too. Additionally, new placeholders are available when handling errors. [The JSON docs for an HTTP server's error routes](/docs/json/apps/http/servers/errors/#routes) describe these placeholders. The `handle_errors` directive simply adds error routes, so you can use those placeholders within a `handle_errors` block. +A request's context is carried into error routes, so any values set on the request context such as [site root](root) will be preserved in error handlers, too. Additionally, new placeholders are available when handling errors. [The JSON docs for an HTTP server's error routes](/docs/json/apps/http/servers/errors/#routes) describe these placeholders. The `handle_errors` directive simply adds error routes, so you can use those placeholders within a `handle_errors` block. + +Note that certain directives, for example [`reverse_proxy`](reverse_proxy) which may write a response with an HTTP status which is classified as an error, will _not_ trigger the error routes. + +You may use the [`error`](error) directive to explicitly trigger an error based on your own routing decisions. + ## Syntax @@ -71,4 +76,4 @@ handle_errors { respond "It's not a 4xx error." } -``` \ No newline at end of file +```