From 73d20fcb814801531ebdca8577628f69d9c85cb0 Mon Sep 17 00:00:00 2001 From: Matthew Holt Date: Wed, 30 Nov 2022 16:01:43 -0700 Subject: [PATCH] caddyfile: Clarify matcher docs for repeated params --- src/docs/markdown/caddyfile/matchers.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/docs/markdown/caddyfile/matchers.md b/src/docs/markdown/caddyfile/matchers.md index b29318b..187be5e 100644 --- a/src/docs/markdown/caddyfile/matchers.md +++ b/src/docs/markdown/caddyfile/matchers.md @@ -339,6 +339,8 @@ By request header fields. Different header fields within the same set are AND-ed. Multiple values per field are OR'ed. +Note that header fields may be repeated and have different values. Backend applications MUST consider that header field values are arrays, not singular values, and Caddy does not interpret meaning in such quandaries. + #### Example: Match requests with the `Connection` header containing `Upgrade`: @@ -570,12 +572,13 @@ expression query({'': ''}) expression query({'': ['']}) ``` -By query string parameters. Should be a sequence of `key=value` pairs. Keys are matched exactly, case-sensitively. Values can contain placeholders. Values are matched exactly, but also support `*` to match any value. +By query string parameters. Should be a sequence of `key=value` pairs. Keys are matched exactly (case-sensitively) but also support `*` to match any value. Values can use placeholders. There can be multiple `query` matchers per named matcher, and pairs with the same keys will be OR'ed together. Illegal query strings (bad syntax, unescaped semicolons, etc.) will fail to parse and thus will not match. +**NOTE:** Query string parameters are arrays, not singular values. This is because repeated keys are valid in query strings, and each one may have a different value. This matcher will match for a key if any one of its configured values is assigned in the query string. Backend applications using query strings MUST take into consideration that query string values are arrays and can have multiple values. #### Example: Match requests with a `sort` query parameter with the value `asc`: