docs: document more of header directive behavior

[lilnasy]

• Added syntax, usage, and examples for the match directive added in 2.9.1 header: match subdirective for response matching caddy#6765
• Clarified in a few places that the headers are being added/removed/replaced in the responses, not the requests.

[lilnasy]

I might be reading this wrong, but this seemed to suggest that the header value is optional. This change to emphasize that both the header name and the value are required.

[francislavoie]

It's technically optional because you can do -Field to delete a header, in which case no value is passed.

[lilnasy]

Are you talking about the header directive?

[francislavoie]

Oh, yeah sorry. I didn't click through to the files changed so I didn't notice it was the response matcher in encode. That said, ! as a prefix is allowed, meaning "this header doesn't exist in the response" and in that case you omit the value. See https://caddyserver.com/docs/caddyfile/response-matchers#header

[lilnasy]

Thanks, didn't know about the ! syntax. I'll revert.

[francislavoie]

This one's a bit strange cause it's not optional to provide a matcher, so the [] are sorta misplaced.

I think we should probably replace these to just <response_matcher...> instead, similar to how we have <matcher> in places where a request matcher can go. We can add a jquery blob at the top to transform those into links to https://caddyserver.com/docs/caddyfile/response-matchers

[lilnasy]

I think that's a good idea. There are two ways in which response matchers can be used. I documented the difference.

encode and headers allow inline matching, intercept requires creating named response matchers.

[mholt]

Thanks for iterating on this! @francislavoie Does this LGTY?