docs: Revise the handle cross-linking, add another example

This commit is contained in:
Francis Lavoie 2021-02-17 19:43:32 -05:00
parent cd27d391ca
commit 98af4363d1
No known key found for this signature in database
GPG key ID: 4EE5207CCECBACD7
2 changed files with 27 additions and 4 deletions

View file

@ -8,10 +8,6 @@ Evaluates a group of directives mutually exclusively from other `handle` blocks
The `handle` directive is kind of similar to the `location` directive from nginx config: the first matching `handle` block will be evaluated. Handle blocks can be nested if needed. Only HTTP handler directives can be used inside handle blocks. The `handle` directive is kind of similar to the `location` directive from nginx config: the first matching `handle` block will be evaluated. Handle blocks can be nested if needed. Only HTTP handler directives can be used inside handle blocks.
<aside class="tip">
See also the [`handle_path`](/docs/caddyfile/directives/handle_path) directive if you need to strip the matched path prefix.
</aside>
## Syntax ## Syntax
```caddy-d ```caddy-d
@ -27,6 +23,14 @@ handle [<matcher>] {
If you prefer crafting HTTP handler logic in a more inheritence-based way like nginx location blocks, you may prefer the use of `handle` blocks rather than defining mutually-exclusive matchers for your directives. If inheritence is a desired characteristic of your HTTP handler configurations, then the `handle` directive may suit you well. If you prefer crafting HTTP handler logic in a more inheritence-based way like nginx location blocks, you may prefer the use of `handle` blocks rather than defining mutually-exclusive matchers for your directives. If inheritence is a desired characteristic of your HTTP handler configurations, then the `handle` directive may suit you well.
## Similar directives
There are other directives that can wrap other HTTP handler directives, but but imply a different intent or behave subtly differently:
- [`handle_path`](handle_path) does the same as `handle`, but also has built-in path prefix stripping logic built-in before handling the directives within.
- [`handle_errors`](handle_errors), similarly to `handle`, wraps other directives, but is instead invoked when Caddy encounters an error during request handling.
- [`route`](route) similarly to `handle`, wraps other directives, but instead of providing mutual exclusivity, allows overriding the default [directive order](/docs/caddyfile/directives#directive-order).
## Examples ## Examples
Handle requests in `/foo/` by the static file server, and send all other requests to the reverse proxy: Handle requests in `/foo/` by the static file server, and send all other requests to the reverse proxy:
@ -39,3 +43,15 @@ handle {
reverse_proxy 127.0.0.1:8080 reverse_proxy 127.0.0.1:8080
} }
``` ```
You can mix `handle` and [`handle_path`](handle_path) directives in the same site, and they will still be mutually exclusive from eachother:
```caddy-d
handle_path /foo/* {
# The path has the "/foo" prefix stripped
}
handle /bar/* {
# The path still retains "/bar"
}
```

View file

@ -63,6 +63,13 @@ route {
And now `file_server` will be chained in before `redir` because the order is taken literally. And now `file_server` will be chained in before `redir` because the order is taken literally.
## Similar directives
There are other directives that can wrap other HTTP handler directives, but but imply a different intent or behave subtly differently:
- [`handle`](route) similarly to `route`, wraps other directives, but instead overriding the default directive order, provides mutual exclusivity with other `handle` blocks.
- [`handle_path`](handle_path) does the same as `handle`, but also has built-in path prefix stripping logic built-in before handling the directives within.
- [`handle_errors`](handle_errors), similarly to `route`, wraps other directives, but is instead invoked when Caddy encounters an error during request handling.
## Examples ## Examples