diff --git a/src/docs/markdown/caddyfile/directives/encode.md b/src/docs/markdown/caddyfile/directives/encode.md index 30b9bd8..4f55273 100644 --- a/src/docs/markdown/caddyfile/directives/encode.md +++ b/src/docs/markdown/caddyfile/directives/encode.md @@ -12,13 +12,56 @@ Encodes responses using the configured encoding(s). A typical use for encoding i encode [] { gzip [] zstd + minimum_length + prefer + + # response matcher single line syntax + match [header []] | [status ] + # or response matcher block + match { + status + header [] + } } ``` - **<formats...>** is the list of encoding formats to enable. - **gzip** enables Gzip compression, optionally at the specified level. - **zstd** enables Zstandard compression. +- **minimum_length** the minimum number of bytes a response should have to be encoded. (Default is 512) +- **prefer** is the ordered list of enabled encoding formats to determine, which encoding to choose if the client has no strong preference (via q-factors in the `Accept-Encoding` header). + If **prefer** is not specified the first supported encoding from the `Accept-Encoding` header is used. +- **match** is a [Response matcher](#responsematcher). Only matching Responses are encoded. The default looks like this: + ```caddy-d + match { + header Content-Type text/* + header Content-Type application/json* + header Content-Type application/javascript* + header Content-Type application/xhtml+xml* + header Content-Type application/atom+xml* + header Content-Type application/rss+xml* + header Content-Type image/svg+xml* + } + ``` + +## Response matcher + +**Response matchers** can be used to filter (or classify) responses by specific criteria. + +### status + +```caddy-d +status +``` + +By HTTP status code. + +- **<code...>** is a list of HTTP status codes. Special cases are `2xx`, `3xx`, ... which match against all status codes in the range of 200-299, 300-399, ... respectively + +### header + +See Request matcher [header](/docs/caddyfile/matchers#header). ## Examples @@ -34,3 +77,12 @@ Enable Zstandard and Gzip compression: encode zstd gzip ``` +Enable Zstandard and Gzip compression and prefer Zstandard over Gzip: + +```caddy-d +encode zstd gzip { + prefer zstd gzip +} +``` + +Without the **prefer** setting, a `--compressed` HTTP request via [curl](https://curl.se/) (meaning `Accept-Encoding: deflate, gzip, br, zstd` in curl >=7.72.0) would be served with Gzip encoding, because it is the first accepted encoding that both client and server support. With the **prefer** setting Zstandard encoding is served, because the client has no preference but the server (caddy) has. diff --git a/src/docs/markdown/caddyfile/directives/file_server.md b/src/docs/markdown/caddyfile/directives/file_server.md index b8f55af..fc93e96 100644 --- a/src/docs/markdown/caddyfile/directives/file_server.md +++ b/src/docs/markdown/caddyfile/directives/file_server.md @@ -8,7 +8,6 @@ A static file server. It works by appending the request's URI path to the [site' Most often, the `file_server` directive is paired with the [`root`](/docs/caddyfile/directives/root) directive to set file root for the whole site. - ## Syntax ```caddy-d @@ -17,6 +16,7 @@ file_server [] [browse] { hide index browse [] + precompressed } ``` @@ -24,8 +24,9 @@ file_server [] [browse] { - **root** sets the path to the site root for just this file server instance, overriding any other. Default: `{http.vars.root}` or the current working directory. Note: This subdirective only changes the root for this directive. 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. - **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. - **index** is a list of filenames to look for as index files. Default: `index.html index.txt` -- **** is an optional custom template file to use for directory listings. Defaults to the template that can be found [here in the source code ](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/fileserver/browsetpl.go). - +- **** is an optional custom template file to use for directory listings. Defaults to the template that can be found [here in the source code ![external link](/resources/images/external-link.svg)](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/fileserver/browsetpl.go). +- **precompressed** is the list of encoding formats to search for precompressed sidecar files. +- **<formats...>** is the ordered list of encoding formats to search for precompressed sidecar files. Supported formats are `gzip`, `zstd` and `br`. ## Examples @@ -61,3 +62,11 @@ file_server { hide .git } ``` + +If supported by the client (`Accept-Encoding` header) checks the existence of precompressed files along side the requested file. So if `/path/to/file` is requested, it checks for `/path/to/file.zst`, `/path/to/file.br` and `/path/to/file.gz` in that order and serves the first available file with corresponding Content-Encoding: + +```caddy-d +file_server { + precompressed zstd br gzip +} +```