From ae77a56ac8761bfe064904bd7098a952d3221034 Mon Sep 17 00:00:00 2001 From: Matthew Holt Date: Wed, 30 Nov 2022 16:03:31 -0700 Subject: Clarify some docs --- modules/caddyhttp/matchers.go | 15 +++++++++++++++ modules/caddyhttp/reverseproxy/healthchecks.go | 8 ++++---- 2 files changed, 19 insertions(+), 4 deletions(-) (limited to 'modules') diff --git a/modules/caddyhttp/matchers.go b/modules/caddyhttp/matchers.go index e39ba3f..93c7e69 100644 --- a/modules/caddyhttp/matchers.go +++ b/modules/caddyhttp/matchers.go @@ -123,6 +123,7 @@ type ( // keyed by the query keys, with an array of string values to match for that key. // Query key matches are exact, but wildcards may be used for value matches. Both // keys and values may be placeholders. + // // An example of the structure to match `?key=value&topic=api&query=something` is: // // ```json @@ -135,6 +136,13 @@ type ( // // Invalid query strings, including those with bad escapings or illegal characters // like semicolons, will fail to parse and thus fail to match. + // + // **NOTE:** Notice that query string values 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 relyon on query + // strings MUST take into consideration that query string values are arrays and can + // have multiple values. MatchQuery url.Values // MatchHeader matches requests by header fields. The key is the field @@ -144,6 +152,13 @@ type ( // surrounding the value with the wildcard `*` character, respectively. // If a list is null, the header must not exist. If the list is empty, // the field must simply exist, regardless of its value. + // + // **NOTE:** Notice that header values are arrays, not singular values. This is + // because repeated fields are valid in headers, and each one may have a + // different value. This matcher will match for a field if any one of its configured + // values matches in the header. Backend applications relying on headers MUST take + // into consideration that header field values are arrays and can have multiple + // values. MatchHeader http.Header // MatchHeaderRE matches requests by a regular expression on header fields. diff --git a/modules/caddyhttp/reverseproxy/healthchecks.go b/modules/caddyhttp/reverseproxy/healthchecks.go index cf22d26..e4c732a 100644 --- a/modules/caddyhttp/reverseproxy/healthchecks.go +++ b/modules/caddyhttp/reverseproxy/healthchecks.go @@ -46,10 +46,10 @@ type HealthChecks struct { // Passive health checks monitor proxied requests for errors or timeouts. // To minimally enable passive health checks, specify at least an empty - // config object. Passive health check state is shared (stored globally), - // so a failure from one handler will be counted by all handlers; but - // the tolerances or standards for what defines healthy/unhealthy backends - // is configured per-proxy-handler. + // config object with fail_duration > 0. Passive health check state is + // shared (stored globally), so a failure from one handler will be counted + // by all handlers; but the tolerances or standards for what defines + // healthy/unhealthy backends is configured per-proxy-handler. // // Passive health checks technically do operate on dynamic upstreams, // but are only effective for very busy proxies where the list of -- cgit v1.2.3