From 84e15ba5ee7cd41172dc3ecdd813a54077df7600 Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Mon, 6 Nov 2023 05:34:36 -0500 Subject: [PATCH] Clarify file_server error handling, clarify proxy single-upstream LB retries --- .../caddyfile/directives/file_server.md | 28 +++++++++++++------ .../caddyfile/directives/handle_errors.md | 8 +++--- .../caddyfile/directives/reverse_proxy.md | 4 ++- 3 files changed, 26 insertions(+), 14 deletions(-) diff --git a/src/docs/markdown/caddyfile/directives/file_server.md b/src/docs/markdown/caddyfile/directives/file_server.md index bca1c51..06f79fd 100644 --- a/src/docs/markdown/caddyfile/directives/file_server.md +++ b/src/docs/markdown/caddyfile/directives/file_server.md @@ -16,11 +16,14 @@ window.$(function() { # file_server -A static file server that supports real and virtual file systems. It forms file paths by appending the request's URI path to the [site's root path](/docs/caddyfile/directives/root). +A static file server that supports real and virtual file systems. It forms file paths by appending the request's URI path to the [site's root path](root). -By default, it enforces canonical URIs; meaning HTTP redirects will be issued for requests to directories that do not end with a trailing slash (to add it) or requests to files that have a trailing slash (to remove it). Redirects are not issued, however, if an internal rewrite modifies the last element of the path (the filename). +By default, it enforces canonical URIs; meaning HTTP redirects will be issued for requests to directories that do not end with a trailing slash (to add it), or requests to files that have a trailing slash (to remove it). However, redirects are not issued if an internal rewrite modifies the last element of the path (the filename). + +Most often, the `file_server` directive is paired with the [`root`](root) directive to set the file root for the whole site. This directive also has a `root` subdirective (see below) to set the root only for this handler (not recommended). Note that a site root does not carry sandbox guarantees: the file server does prevent directory traversal from path components, but symbolic links within the root can still allow accesses outside of the root. + +When errors occur (e.g. file not found `404`, permission denied `403`), the error routes will be invoked. Use the [`handle_errors`](handle_errors) directive to define error routes, and display custom error pages. -Most often, the `file_server` directive is paired with the [`root`](/docs/caddyfile/directives/root) directive to set the file root for the whole site, but this directive also has a `root` subdirective (below) to set the root only for this handler if preferred. Note that a site root does not carry sandbox guarantees: the file server does prevent directory traversal from path components, but symbolic links within the root can still allow accesses outside of the root. ## Syntax @@ -40,7 +43,7 @@ file_server [] [browse] { - **fs** specifies an alternate (perhaps virtual) file system to use. Any Caddy module in the `caddy.fs` namespace can be used here. Any root path/prefix will still apply to alternate file system modules. By default, the local disk is used. -- **root** sets the path to the site root. It's similar to the [`root`](/docs/caddyfile/directives/root) directive except it applies to this file server instance only and overrides any other site root that may have been defined. Default: `{http.vars.root}` or the current working directory. Note: This subdirective only changes the root for this handler. For other directives (like [`try_files`](/docs/caddyfile/directives/try_files) or [`templates`](/docs/caddyfile/directives/templates)) to know the same site root, use the [`root`](/docs/caddyfile/directives/root) directive, not this subdirective. +- **root** sets the path to the site root. It's similar to the [`root`](root) directive except it applies to this file server instance only and overrides any other site root that may have been defined. Default: `{http.vars.root}` or the current working directory. Note: This subdirective only changes the root for this handler. For other directives (like [`try_files`](try_files) or [`templates`](templates)) to know the same site root, use the [`root`](root) directive instead. - **hide** is a list of files or folders to hide; if requested, the file server will pretend they do not exist. Accepts placeholders and glob patterns. Note that these are _file system_ paths, NOT request paths. In other words, relative paths use the current working directory as a base, NOT the site root; and all paths are transformed to their absolute form before comparisons (if possible). Specifying a file name or pattern without a path separator will hide all files with a matching name regardless of its location; otherwise, a path prefix match will be attempted, and then a globular match. Since this is a Caddyfile config, the active configuration file(s) will be added by default. @@ -52,13 +55,13 @@ file_server [] [browse] { - **precompressed** is the list of encoding formats to search for precompressed sidecar files. Arguments are an ordered list of encoding formats to search for precompressed [sidecar files](https://en.wikipedia.org/wiki/Sidecar_file). Supported formats are `gzip` (`.gz`), `zstd` (`.zst`) and `br` (`.br`). - All file lookups will look for the existence of the uncompressed file first. Once found Caddy will look for sidecar files with the file extension of each enabled format. If a precompressed sidecar file is found, Caddy will respond with the precompressed file, with the `Content-Encoding` response header set appropriately. Otherwise, Caddy will respond with the uncompressed file as normal. If the [`encode` directive](/docs/caddyfile/directives/encode) is enabled, then it may compress the response on-the-fly if not precompressed. + All file lookups will look for the existence of the uncompressed file first. Once found Caddy will look for sidecar files with the file extension of each enabled format. If a precompressed sidecar file is found, Caddy will respond with the precompressed file, with the `Content-Encoding` response header set appropriately. Otherwise, Caddy will respond with the uncompressed file as normal. If the [`encode` directive](encode) is enabled, then it may compress the response on-the-fly if not precompressed. -- **status** is an optional status code override to be used when writing the response. Particularly useful when responding to a request with a custom error page. Can be a 3-digit status code, For example: `404`. Placeholders are supported. By default, the written status code will typically be `200`, or `206` for partial content. +- **status** is an optional status code override to be used when writing the response. Particularly useful when responding to a request with a [custom error page](handle_errors). Can be a 3-digit status code, For example: `404`. Placeholders are supported. By default, the written status code will typically be `200`, or `206` for partial content. -- **disable_canonical_uris** disables the default behaviour of redirecting to add a trailing slash if the request path is a directory, or remove the trailing slash if the request path is a file. Note that by default, canonicalization will not happen if the last element of the request's path (the filename) underwent an internal rewrite, to avoid clobbering an explicit rewrite with implicit behaviour. +- **disable_canonical_uris** disables the default behaviour of redirecting (to add a trailing slash if the request path is a directory, or remove the trailing slash if the request path is a file). Note that by default, canonicalization will not happen if the last element of the request's path (the filename) underwent an internal rewrite, to avoid clobbering an explicit rewrite with implicit behaviour. -- **pass_thru** enables pass-thru mode, which continues to the next HTTP handler in the route if the requested file is not found, instead of returning a `404`. Practically, this is likely only be useful inside of a [`route`](/docs/caddyfile/directives/route) block, because the `file_server` directive is effectively [ordered last](/docs/caddyfile/directives#directive-order) otherwise. +- **pass_thru** enables pass-thru mode, which continues to the next HTTP handler in the route if the requested file is not found, instead of triggering a `404` error (invoking [`handle_errors`](handle_errors) routes). Practically, this is only useful inside of a [`route`](route) block with other handler directives following `file_server`, because this directive is effectively [ordered last](/docs/caddyfile/directives#directive-order). ## Examples @@ -80,13 +83,20 @@ Only serve static files within the `/static` folder: file_server /static/* ``` -The `file_server` directive is usually paired with the [`root` directive](/docs/caddyfile/directives/root) to set the root path from which to serve files: +The `file_server` directive is usually paired with the [`root` directive](root) to set the root path from which to serve files: ```caddy-d root * /home/user/public_html file_server ``` + + + Hide all `.git` folders and their contents: ```caddy-d diff --git a/src/docs/markdown/caddyfile/directives/handle_errors.md b/src/docs/markdown/caddyfile/directives/handle_errors.md index 2ed7947..5ace9f2 100644 --- a/src/docs/markdown/caddyfile/directives/handle_errors.md +++ b/src/docs/markdown/caddyfile/directives/handle_errors.md @@ -41,7 +41,7 @@ The following placeholders are available while handling errors. They are [Caddyf ## Examples -Custom error pages based on the status code (i.e. a page called `404.html` for 404 errors). Note that [`file_server`](file_server) preserves the error's HTTP status code when run in `handle_errors` (assumes you set a [site root](/docs/caddyfile/directives/root) in your site beforehand): +Custom error pages based on the status code (i.e. a page called `404.html` for `404` errors). Note that [`file_server`](file_server) preserves the error's HTTP status code when run in `handle_errors` (assumes you set a [site root](root) in your site beforehand): ```caddy-d handle_errors { @@ -50,7 +50,7 @@ handle_errors { } ``` -A single error page that uses [`templates`](/docs/caddyfile/directives/templates) to write a custom error message: +A single error page that uses [`templates`](templates) to write a custom error message: ```caddy-d handle_errors { @@ -85,7 +85,7 @@ handle_errors { } ``` -Simply use [`respond`](/docs/caddyfile/directives/respond) to return the error code and name +Simply use [`respond`](respond) to return the error code and name ```caddy-d handle_errors { @@ -93,7 +93,7 @@ handle_errors { } ``` -To handle specific error codes differently, use an [`expression`](/docs/caddyfile/matchers#expression) matcher, using [`handle`](/docs/caddyfile/directives/handle) for mutual exclusivity: +To handle specific error codes differently, use an [`expression`](/docs/caddyfile/matchers#expression) matcher, using [`handle`](handle) for mutual exclusivity: ```caddy-d handle_errors { diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index 9cc13ab..fba3197 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -238,7 +238,9 @@ Append the results of multiple dynamic upstream modules. Useful if you want redu ### Load balancing -Load balancing is used whenever more than one upstream is defined. This is enabled by default, with the `random` load balancing policy. +Load balancing is typically used to split traffic between multiple upstreams. By enabling retries, it can also be used with one or more upstreams, to hold requests until a healthy upstream can be selected (e.g. to wait and mitigate errors while rebooting or redeploying an upstream). + +This is enabled by default, with the `random` policy. Retries are disabled by default. - **lb_policy** is the name of the load balancing policy, along with any options. Default: `random`.