From 10fe27a51cb1f5ae3256683c1978599f5669d6ae Mon Sep 17 00:00:00 2001 From: =?utf8?q?Oto=20=C5=A0=C5=A5=C3=A1va?= Date: Tue, 8 Feb 2022 10:08:05 +0100 Subject: [PATCH] daemon, lib: document API changes made due to PROXYv2 --- daemon/bindings/net_server.rst | 2 ++ doc/upgrading.rst | 4 ++++ lib/resolve.h | 21 +++++++++++++++------ 3 files changed, 21 insertions(+), 6 deletions(-) diff --git a/daemon/bindings/net_server.rst b/daemon/bindings/net_server.rst index c31353ed2..f346aeb92 100644 --- 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 23afc7c2b..c35fb1b59 100644 --- 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 7b7efb044..f14e1430e 100644 --- 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 */ -- 2.47.3