Updated for v2.8.0 (#389)

Co-authored-by: Mohammed Al Sahaf <msaa1990@gmail.com>
Co-authored-by: Francis Lavoie <lavofr@gmail.com>
Co-authored-by: Nebez Briefkani <me@nebezb.com>
Co-authored-by: Mohammed Al Sahaf <mohammed@caffeinatedwonders.com>
This commit is contained in:
Francis Lavoie 2024-05-29 18:18:32 -04:00 committed by GitHub
parent 1a82466537
commit ca9ce7b2b5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
22 changed files with 549 additions and 107 deletions

View file

@ -8,6 +8,8 @@ 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.
The directive may be repeated with different status codes to handle different errors differently. If no status codes are specified, then it will match any error, acting as a fallback if any other error handlers does not match.
A request's context is carried into error routes, so any values set on the request context such as [site root](root) or [vars](vars) will be preserved in error handlers, too. Additionally, [new placeholders](#placeholders) are available when handling errors.
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.
@ -18,11 +20,13 @@ You may use the [`error`](error) directive to explicitly trigger an error based
## Syntax
```caddy-d
handle_errors {
handle_errors [<status_codes...>] {
<directives...>
}
```
- **<status_codes...>** is one or more HTTP status codes to match against the error being handled. The status codes may be 3-digit numbers, or a special case of `4xx` or `5xx` which match against all status codes in the range of 400-499 or 500-599, respectively. If no status codes are specified, then it will match any error, acting as a fallback if any other error handlers does not match.
- **<directives...>** is a list of HTTP handler [directives](/docs/caddyfile/directives) and [matchers](/docs/caddyfile/matchers), one per line.
@ -93,7 +97,23 @@ handle_errors {
}
```
To handle specific error codes differently, use an [`expression`](/docs/caddyfile/matchers#expression) matcher, using [`handle`](handle) for mutual exclusivity:
To handle specific error codes differently:
```caddy-d
handle_errors 404 410 {
respond "It's a 404 or 410 error!"
}
handle_errors 5xx {
respond "It's a 5xx error."
}
handle_errors {
respond "It's another error"
}
```
The above behaves the same as the below, which uses an [`expression`](/docs/caddyfile/matchers#expression) matcher against the status codes, and using [`handle`](handle) for mutual exclusivity:
```caddy-d
handle_errors {