From a223b5ed55554a9146be77c60617a773326912ea Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Sun, 2 May 2021 14:51:11 -0400 Subject: [PATCH] docs: Warn about the behaviour of `?` in multi-line `header` handlers (#155) * docs: Warn about the behaviour of `?` in multi-line `header` handlers * Apply suggestions from code review Co-authored-by: Matt Holt Co-authored-by: Matt Holt --- src/docs/markdown/caddyfile/directives/header.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/docs/markdown/caddyfile/directives/header.md b/src/docs/markdown/caddyfile/directives/header.md index 46c91eb..33683ab 100644 --- a/src/docs/markdown/caddyfile/directives/header.md +++ b/src/docs/markdown/caddyfile/directives/header.md @@ -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 (`-` prefix) or setting a defualt value (`?` prefix). In those cases, the header operations are automatically deferred until the time they are being written to the client. ## Syntax ```caddy-d -header [] [[+|-|?] [|] []] { +header [] [[+|-|?] [||] []] { [+] - @@ -26,10 +26,12 @@ header [] [[+|-|?] [|] []] { - **<default_value>** is the header field value that will be set only if the header does not already exist. - **<find>** is the substring or regular expression to search for. - **<replace>** 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 setting 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` directive. [Under the hood](https://caddyserver.com/docs/modules/http.handlers.headers#response/require), using `?` configures a response matcher which applies to the directive's entire handler which only applies the header operations if the field is not yet set. For example, if in the same directive, 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