mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-05-06 11:47:12 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Warn about the behaviour of ? in multi-line header handlers

Browse source
This commit is contained in:
Francis Lavoie 2021-04-24 12:07:12 -04:00
parent 6518711538
commit b6a45f8eeb
No known key found for this signature in database
GPG key ID: 7D1A27F0725BE5D8
1 changed files with 5 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

8
src/docs/markdown/caddyfile/directives/header.md
View file

@ -6,13 +6,13 @@ title: header (Caddyfile directive)
Manipulates HTTP header fields on the response. It can set, add, and delete header values, or perform replacements using regular expressions.
By default, header operations are performed immediately unless any of the headers are being deleted, in which case the header operations are automatically deferred until the time they are being written to the client.
By default, header operations are performed immediately unless any of the headers are being deleted, or attempting to set a defualt value. In that case, the header operations are automatically deferred until the time they are being written to the client.
## Syntax
```caddy-d
header [<matcher>] [[+|-|?]<field> [<value>|<find>] [<replace>]] {
header [<matcher>] [[+|-|?]<field> [<value>|<find>|<default_value>] [<replace>]] {
<field> <find> <replace>
[+]<field> <value>
-<field>
@ -26,10 +26,12 @@ header [<matcher>] [[+|-|?]<field> [<value>|<find>] [<replace>]] {
- **&lt;default_value&gt;** is the header field value that will be set only if the header does not already exist.
- **&lt;find&gt;** is the substring or regular expression to search for.
- **&lt;replace&gt;** is the replacement value; required if performing a search-and-replace.
- **defer** will force the header operations to be deferred until the response is written out to the client. This is automatically enabled if any of the header fields are being deleted.
- **defer** will force the header operations to be deferred until the response is being written out to the client. This is automatically enabled if any of the header fields are being deleted with `-`, or when attempting to set a default value with `?`.
For multiple header manipulations, you can open a block and specify one manipulation per line in the same way.
When using the `?` prefix to set a default header value, it is recommended to separate this into its own `header` handler, because under the hood, it works by configuring a response matcher which applies to the entire handler, to decide whether a header operation should be performed (i.e. when the given header field is empty). For example, if in the same handler (using multi-line syntax) you have these two manipulations: `-Hidden` and `?Foo default`, then the `Hidden` header is _only_ removed if `Foo` is empty, which is typically not the intended effect.
## Examples