daemon, lib: document API changes made due to PROXYv2

diff --git a/daemon/bindings/net_server.rst b/daemon/bindings/net_server.rst
index c31353ed2af02340e6fdb756e3280464a2c7b5dc..f346aeb921c7d8ec627ac893b06d4745f0495636 100644 (file)
--- a/daemon/bindings/net_server.rst
+++ b/daemon/bindings/net_server.rst
@@ -66,6 +66,8 @@ Examples:
         addresses if the network address ranges overlap,
         and clients would probably refuse such a response.
 
+.. _proxyv2:
+
 PROXYv2 protocol
 ^^^^^^^^^^^^^^^^
 

diff --git a/doc/upgrading.rst b/doc/upgrading.rst
index 23afc7c2b1c89aead6112d01c1b2e0894b381761..c35fb1b598a4eae366371cb53fb3b5099722dd83 100644 (file)
--- a/doc/upgrading.rst
+++ b/doc/upgrading.rst
@@ -41,6 +41,10 @@ Module API changes
 ------------------
 * Function `cache.zone_import` was removed;
   you can use `ffi.C.zi_zone_import` instead (different API).
+* When using :ref:`proxyv2`, the meaning of ``qsource.flags`` and ``qsource.comm_flags``
+  in :c:member:`kr_request` changes so that ``flags`` describes the original client
+  communicating with the proxy, while ``comm_flags`` describes the proxy communicating
+  with the resolver. When there is no proxy, ``flags`` and ``comm_flags`` are the same.
 
 
 5.3 to 5.4

diff --git a/lib/resolve.h b/lib/resolve.h
index 7b7efb044dab429a18c8d150bfda1ee552bc7681..f14e1430e57119758ad9346c78f9892b2fe392e6 100644 (file)
--- a/lib/resolve.h
+++ b/lib/resolve.h
@@ -210,18 +210,27 @@ struct kr_request {
        knot_pkt_t *answer; /**< See kr_request_ensure_answer() */
        struct kr_query *current_query;    /**< Current evaluated query. */
        struct {
-               /** Address that originated the request. NULL for internal origin. */
+               /** Address that originated the request. May be that of a client
+                * behind a proxy, if PROXYv2 is used. Otherwise, it will be
+                * the same as `comm_addr`. `NULL` for internal origin. */
                const struct sockaddr *addr;
-               /** Address that communicated the request (e.g. a proxy). Same as
-                * addr if no proxy is used. */
+               /** Address that communicated the request. This may be the address
+                * of a proxy. It is the same as `addr` if no proxy is used.
+                * `NULL` for internal origin. */
                const struct sockaddr *comm_addr;
-               /** Address that accepted the request.  NULL for internal origin.
+               /** Address that accepted the request. `NULL` for internal origin.
                 * Beware: in case of UDP on wildcard address it will be wildcard;
                 * closely related: issue #173. */
                const struct sockaddr *dst_addr;
                const knot_pkt_t *packet;
-               struct kr_request_qsource_flags flags; /**< Flags for the original client. */
-               struct kr_request_qsource_flags comm_flags; /**< Flags for the actual client (may be a proxy). */
+               /** Request flags from the point of view of the original client.
+                * This client may be behind a proxy. */
+               struct kr_request_qsource_flags flags;
+               /** Request flags from the point of view of the client actually
+                * communicating with the resolver. When PROXYv2 protocol is used,
+                * this describes the request from the proxy. When there is no
+                * proxy, this will have exactly the same value as `flags`. */
+               struct kr_request_qsource_flags comm_flags;
                size_t size; /**< query packet size */
                int32_t stream_id; /**< HTTP/2 stream ID for DoH requests */
                kr_http_header_array_t headers;  /**< HTTP/2 headers for DoH requests */