daemon/http: documentation

diff --git a/NEWS b/NEWS
index 0d90f6e1c6fe9c4777f84dd6394d7f5c68884d82..35e3378c1c2c01f276272bbe09c72bf759fe3182 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -4,6 +4,7 @@ Knot Resolver 5.5.1 (2022-mm-dd)
 Improvements
 ------------
 - daemon/tls: disable TLS resumption via tickets for TLS <= 1.2 (#742, !1295)
+- daemon/http: DoH now responds with proper HTTP codes (#728, !1279)
 
 Bugfixes
 --------

diff --git a/daemon/bindings/net_tlssrv.rst b/daemon/bindings/net_tlssrv.rst
index 8306cfc225c37c82cd14c7e338ea575a2ba9af74..519a0b5690b15f5ff7ee80f489ce29eb5e8ce66d 100644 (file)
--- a/daemon/bindings/net_tlssrv.rst
+++ b/daemon/bindings/net_tlssrv.rst
@@ -68,6 +68,28 @@ additional considerations for TLS 1.2 required by HTTP/2 are not implemented
 
 .. _dot-doh-config-options:
 
+HTTP status codes
+"""""""""""""""""
+
+As specified by :rfc:`8484`, the resolver responds with status **200 OK** whenever 
+it can produce a valid DNS reply for a given query, even in cases where the DNS
+``rcode`` indicates an error (like ``NXDOMAIN``, ``SERVFAIL``, etc.).
+
+For DoH queries malformed at the HTTP level, the resolver may respond with
+the following status codes:
+
+ * **400 Bad Request** for a generally malformed query, like one not containing
+   a valid DNS packet
+ * **404 Not Found** when an incorrect HTTP endpoint is queried - the only 
+   supported ones are ``/dns-query`` and ``/doh``
+ * **413 Payload Too Large** when the DNS query exceeds its maximum size
+ * **415 Unsupported Media Type** when the query's ``Content-Type`` header
+   is not ``application/dns-message``
+ * **431 Request Header Fields Too Large** when a header in the query is too
+   large to process
+ * **501 Not Implemented** when the query uses a method other than
+   ``GET``, ``POST``, or ``HEAD``
+
 Configuration options for DoT and DoH
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^