From f4f2c11eb9a0ca01a9dcdffb2536efde82ee44ea Mon Sep 17 00:00:00 2001
From: Dimitry Kolyshev <dkolyshev@adguard.com>
Date: Mon, 29 May 2023 13:29:41 +0300
Subject: [PATCH] all: export querylog docs

---
 CHANGELOG.md              |  4 ++++
 internal/querylog/http.go |  9 +++++++++
 openapi/CHANGELOG.md      |  5 +++++
 openapi/openapi.yaml      | 41 +++++++++++++++++++++++++++++++++++++++
 4 files changed, 59 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 58dd6c16..58fd79c2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,9 @@ NOTE: Add new changes BELOW THIS COMMENT.
 
 ### Added
 
+- The new HTTP API, `GET /control/querylog/export`, which can be used to
+  export query log items.  See `openapi/openapi.yaml` for the full description
+  ([#3389]).
 - The ability to edit rewrite rules via `PUT /control/rewrite/update` HTTP API
   ([#1577]).
 
@@ -41,6 +44,7 @@ NOTE: Add new changes BELOW THIS COMMENT.
   UDP/TCP upstream servers.
 
 [#1577]: https://github.com/AdguardTeam/AdGuardHome/issues/1577
+[#3389]: https://github.com/AdguardTeam/AdGuardHome/issues/3389
 [#5716]: https://github.com/AdguardTeam/AdGuardHome/issues/5716
 
 <!--
diff --git a/internal/querylog/http.go b/internal/querylog/http.go
index 1a29e23d..122a039c 100644
--- a/internal/querylog/http.go
+++ b/internal/querylog/http.go
@@ -62,6 +62,7 @@ func (l *queryLog) initWeb() {
 	l.conf.HTTPRegister(http.MethodGet, "/control/querylog", l.handleQueryLog)
 	l.conf.HTTPRegister(http.MethodPost, "/control/querylog_clear", l.handleQueryLogClear)
 	l.conf.HTTPRegister(http.MethodGet, "/control/querylog/config", l.handleGetQueryLogConfig)
+	l.conf.HTTPRegister(http.MethodGet, "/control/querylog/export", l.handleQueryLogExport)
 	l.conf.HTTPRegister(
 		http.MethodPut,
 		"/control/querylog/config/update",
@@ -96,6 +97,14 @@ func (l *queryLog) handleQueryLog(w http.ResponseWriter, r *http.Request) {
 	_ = aghhttp.WriteJSONResponse(w, r, resp)
 }
 
+// handleQueryLogExport is the handler for the GET /control/querylog/export
+// HTTP API.
+//
+// TODO(d.kolyshev): !! Implement handleQueryLogExport.
+func (l *queryLog) handleQueryLogExport(w http.ResponseWriter, r *http.Request) {
+	aghhttp.Error(r, w, http.StatusBadRequest, "not implemented")
+}
+
 // handleQueryLogClear is the handler for the POST /control/querylog/clear HTTP
 // API.
 func (l *queryLog) handleQueryLogClear(_ http.ResponseWriter, _ *http.Request) {
diff --git a/openapi/CHANGELOG.md b/openapi/CHANGELOG.md
index 7c68a47b..266bc941 100644
--- a/openapi/CHANGELOG.md
+++ b/openapi/CHANGELOG.md
@@ -6,6 +6,11 @@
 
 ## v0.107.30: API changes
 
+### New HTTP API 'GET /control/querylog/export'
+
+* The new `GET /control/querylog/export` HTTP API allows an export of query log
+  items in the CSV file.
+
 ### `POST /control/version.json` and `GET /control/dhcp/interfaces` content type
 
 * The value of the `Content-Type` header in the `POST /control/version.json` and
diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml
index b1519843..5d63b787 100644
--- a/openapi/openapi.yaml
+++ b/openapi/openapi.yaml
@@ -313,6 +313,47 @@
       'responses':
         '200':
           'description': 'OK.'
+  '/querylog/export':
+    'get':
+      'tags':
+        - 'log'
+      'description': >
+        Returns a CSV file stream with the following fields, sorted a-z:
+        ans_dnssec, ans_rcode, ans_type, ans_value, cached, client_ip,
+        clientid, ecs, elapsed, filter_id, filter_rule, proto, qclass, qname,
+        qtype, reason, time, upstream.  The fields list is a subject to change.
+        The content is UTF-8 encoded with quotation marks.
+
+      'operationId': 'getQueryLogExport'
+      'summary': 'Get DNS server query log items in a CSV stream.'
+      'parameters':
+        - 'name': 'search'
+          'in': 'query'
+          'description': 'Filter by domain name or client IP'
+          'schema':
+            'type': 'string'
+        - 'name': 'response_status'
+          'in': 'query'
+          'description': 'Filter by response status'
+          'schema':
+            'type': 'string'
+            'enum':
+              - 'all'
+              - 'filtered'
+              - 'blocked'
+              - 'blocked_safebrowsing'
+              - 'blocked_parental'
+              - 'whitelisted'
+              - 'rewritten'
+              - 'safe_search'
+              - 'processed'
+      'responses':
+        '200':
+          'description': 'OK.'
+          'content':
+            'text/csv':
+              schema:
+                type: string
   '/stats':
     'get':
       'tags':