DOC: config: clarify some known limitations of the json_query() converter

Oula Kivalo reported that different JSON libraries may process duplicate
keys differently and that most JSON libraries usually decode the stream
before extracting keys, while the current mjson implementation decodes the
contents during extraction instead. Let's document this point so that
users are aware of the limitations and do not rely on the current behavior
and do not use it for what it's not made for (e.g. content sanitization).

This is also the case for jwt_header_query(), jwt_payload_query() and
jwt_verify(), which already refer to this converter for specificities.

(cherry picked from commit 67603162c1d5baaf17f6bf1a3a4c58d5c0524d35)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>
(cherry picked from commit d808c48fb926813438f58dad2654bd9a6a923ce4)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>
(cherry picked from commit e09bf0ff4e73819e32075fd37abefb746799f373)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>

diff --git a/doc/configuration.txt b/doc/configuration.txt
index abad35b..45ee86e 100644 (file)
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -20031,6 +20031,12 @@ json_query(<json_path>,[<output_type>])
   <json_path> must be a valid JSON Path string as defined in
   https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/
 
+  Note: depending on the context and the underlying implementation, extraction
+        of duplicate JSON keys is undefined and might return the first, last,
+        or any other occurrence of the same key from the input content, and if
+        key names are passed encoded, they might not always be matched. In
+        short, this converter is not suitable for content sanitization.
+
   Example:
      # get a integer value from the request body
      # "{"integer":4}" => 5