docs: A few more updates for v2.4.0

src/docs/markdown/caddyfile/directives/encode.md

@@ -10,14 +10,15 @@ Encodes responses using the configured encoding(s). A typical use for encoding i
 
 ```caddy-d
 encode [<matcher>] <formats...> {
+	# encoding formats
 	gzip [<level>]
 	zstd
+	
 	minimum_length <length>
-	prefer <formats...>
 
 	# response matcher single line syntax
 	match [header <field> [<value>]] | [status <code...>]
-	# or response matcher block
+	# or response matcher block for multiple conditions
 	match {
 		status <code...>
 		header <field> [<value>]
@@ -25,12 +26,10 @@ encode [<matcher>] <formats...> {
 }
 ```
 
-- **&lt;formats...&gt;** is the list of encoding formats to enable.
+- **&lt;formats...&gt;** is the list of encoding formats to enable. If multiple encodings are enabled, the encoding is chosen based the request's Accept-Encoding header; if the client has no strong preference (q-factor), then the first supported encoding is used.
 - **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.
+- **minimum_length** the minimum number of bytes a response should have to be encoded (default: 512).
 - **match** is a [Response matcher](#responsematcher). Only matching Responses are encoded. The default looks like this:
 
   ```caddy-d
@@ -71,18 +70,8 @@ Enable Gzip compression:
 encode gzip
 ```
 
-Enable Zstandard and Gzip compression:
+Enable Zstandard and Gzip compression (with Zstandard implicitly preferred, since it is first):
 
 ```caddy-d
 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.

src/docs/markdown/caddyfile/directives/file_server.md

@@ -25,7 +25,7 @@ file_server [<matcher>] [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`
-- **<template_file>** 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).
+- **<template_file>** 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). Browse templates can use actions from [the standard templates module](/docs/modules/http.handlers.templates#docs) as well.
 - **precompressed** is the list of encoding formats to search for precompressed sidecar files.
 - **&lt;formats...&gt;** is the ordered list of encoding formats to search for precompressed sidecar files. Supported formats are `gzip`, `zstd` and `br`.
 - **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.

src/docs/markdown/caddyfile/directives/reverse_proxy.md

@@ -65,6 +65,15 @@ reverse_proxy [<matcher>] [<upstreams...>] {
     transport <name> {
         ...
     }
+
+	# optionally intercept responses from upstream
+	@name {
+		status <code...>
+		header <field> [<value>]
+	}
+	handle_response [<matcher>] [status_code] {
+		<directives...>
+	}
 }
 ```
 
@@ -246,6 +255,15 @@ transport fastcgi {
 - **write_timeout** is how long to wait when sending to the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout.
 
 
+### Intercepting responses
+
+The reverse proxy can be configured to intercept responses from the backend. To facilitate this, response matchers can be defined (similar to the syntax for request matchers) and the first matching `handle_response` route will be invoked. When this happens, the response from the backend is not written to the client, and the configured `handle_response` route will be executed instead, and it is up to that route to write a response.
+
+- **@name** is the name of a response matcher. As long as each response matcher has a unique name, multiple matchers can be defined. A response can be matched on the status code and presence or value of a response header.
+- **handle_response** defines the route to execute when matched by the given matcher (or, if a matcher is omitted, all responses). The first matching block will be applied. Inside a `handle_response` block, any other [directives](/docs/caddyfile/directives) can be used.
+
+
+
 
 ## Examples
 
@@ -302,3 +320,16 @@ handle_path /old-prefix/* {
 	reverse_proxy localhost:9000
 }
 ```
+
+X-Accel-Redirect support:
+
+```caddy-d
+reverse_proxy localhost:8080 {
+	@accel header X-Accel-Redirect *
+	handle_response @accel {
+		root    * /path/to/private/files
+		rewrite   {http.response.header.X-Accel-Redirect}
+		file_server
+	}
+}
+```

src/docs/markdown/caddyfile/directives/tls.md

@@ -41,7 +41,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 - **&lt;email&gt;** is the email address to use for the ACME account managing the site's certificates.
 - **&lt;cert_file&gt;** and **&lt;key_file&gt;** are the paths to the certificate and private key PEM files. Specifying just one is invalid.
 - **protocols** specifies the minimum and maximum protocol versions. Default min: `tls1.2`. Default max: `tls1.3`
-- **ciphers** specifies the list of cipher suite names in descending preference order. Note that cipher suites are not customizable with TLS 1.3. The supported names are (in no particular order here):
+- **ciphers** specifies the list of cipher suite names in descending preference order. It is recommended to not change these unless you know what you're doing. Note that cipher suites are not customizable for TLS 1.3; and not all TLS 1.2 ciphers are enabled by default. The supported names are (in no particular order here):
 	- TLS_RSA_WITH_3DES_EDE_CBC_SHA
 	- TLS_RSA_WITH_AES_128_CBC_SHA
 	- TLS_RSA_WITH_AES_256_CBC_SHA
@@ -61,7 +61,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 	- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
 	- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
 	- TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
-- **curves** specifies the list of EC curves to support. Supported values are:
+- **curves** specifies the list of EC curves to support. It is recommended to not change these. Supported values are:
 	- x25519
 	- secp256r1
 	- secp384r1
@@ -73,7 +73,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 - **dns** enables the [DNS challenge](/docs/automatic-https#dns-challenge) using the specified provider plugin, which must be plugged in from one of the [caddy-dns](https://github.com/caddy-dns) repositories. Each provider plugin may have their own syntax following their name; refer to their docs for details. Maintaining support for each DNS provider is a community effort. [Learn how to enable the DNS challenge for your provider at our wiki.](https://caddy.community/t/how-to-use-dns-provider-modules-in-caddy-2/8148)
 - **resolvers** customizes the DNS resolvers used when performing the DNS challenge; these take precedence over system resolvers or any default ones. If set here, the resolvers will propagate to all configured certificate issuers.
 - **eab** configures ACME external account binding (EAB) for this site, using the key ID and MAC key provided by your CA.
-- **on_demand** enables [on-demand TLS](/docs/automatic-https#on-demand-tls) for the hostnames given in the site block's address(es).
+- **on_demand** enables [on-demand TLS](/docs/automatic-https#on-demand-tls) for the hostnames given in the site block's address(es). **Security warning:** Doing so in production is insecure unless you also configure the [`on_demand_tls` global option](https://caddyserver.com/docs/caddyfile/options#on-demand-tls) to mitigate abuse.
 - **client_auth** enables and configures TLS client authentication:
 	- **mode** is the mode for authenticating the client. Allowed values are: