From c004c2509fd259f83c892d867e050ed215f0271f Mon Sep 17 00:00:00 2001
From: Michael M Slusarz <slusarz@users.noreply.github.com>
Date: Thu, 2 Jan 2025 13:40:41 -0700
Subject: [PATCH 1/3] doveadm: Simplify doveadm response display

Doveadm responses are so variable, that creating an abstract system for
documenting would be extremely difficult.

To simplify (for now), do the following:

- Only worry about HTTP API responses
- Allow for free-form description of response info
- Allow for markdown enabled description of the response
---
 components/DoveadmComponent.vue        | 24 +-------------
 components/DoveadmHttpApiComponent.vue | 23 ++++----------
 data/doveadm.js                        | 44 ++++++++++++++------------
 lib/data/doveadm.data.js               | 26 +++------------
 lib/doveadm.js                         |  6 ----
 5 files changed, 36 insertions(+), 87 deletions(-)

diff --git a/components/DoveadmComponent.vue b/components/DoveadmComponent.vue
index 50e55403a..050cec2b9 100644
--- a/components/DoveadmComponent.vue
+++ b/components/DoveadmComponent.vue
@@ -49,7 +49,7 @@ function httpClick(k) {
     <a class="header-anchor" :href="'#' + k"></a>
    </h3>
 
-   <table v-if="v.man_link || v.response || v.added || v.changed || v.deprecated || v.removed">
+   <table v-if="v.man_link || v.added || v.changed || v.deprecated || v.removed">
     <tbody>
      <tr v-if="v.man_link">
       <th style="text-align: right;">Man Page</th>
@@ -79,28 +79,6 @@ function httpClick(k) {
        </ul>
       </td>
     </tr>
-
-     <tr v-if="v.response">
-      <th style="text-align: right;">Response Values</th>
-      <td>
-       <table>
-        <thead>
-         <tr>
-          <th>Key</th>
-          <th>Type</th>
-          <th>Description</th>
-         </tr>
-        </thead>
-        <tbody>
-         <tr v-for="elem in v.response">
-          <td><code>{{ elem.key }}</code></td>
-          <td v-html="elem.type" />
-          <td v-html="elem.text" />
-         </tr>
-        </tbody>
-       </table>
-      </td>
-     </tr>
     </tbody>
    </table>
 
diff --git a/components/DoveadmHttpApiComponent.vue b/components/DoveadmHttpApiComponent.vue
index 4feacb1c2..8217fef44 100644
--- a/components/DoveadmHttpApiComponent.vue
+++ b/components/DoveadmHttpApiComponent.vue
@@ -21,21 +21,10 @@ const jsonReq =
 	]
 ]
 
-const resp = {}
-if (d.response) {
-	for (let elem of d.response) {
-		resp[elem.key] = elem.example
-	}
-}
+const jsonResp = d.response?.example
+	? [ [ "doveadmResponse", [ d.response.example ], "tag1" ] ]
+	: null
 
-const jsonResp =
-[
-	[
-		"doveadmResponse",
-		[ resp ],
-		"tag1"
-	]
-]
 </script>
 
 <template>
@@ -105,10 +94,12 @@ const jsonResp =
    <pre><code>wget --header="Content-Type: application/json" --user=doveadm --password=password --auth-no-challenge --post-data='{{ JSON.stringify(jsonReq) }}' --output-document - http://example.com:8080/doveadm/v1</code></pre>
   </div>
 
-  <template v-if="d.response?.length">
+  <template v-if="d.response">
    <p class="custom-block-title">Example Server Response</p>
 
-   <div class="language- vp-adaptive-theme">
+   <div v-html="d.response.text" />
+
+   <div class="language- vp-adaptive-theme" v-id="jsonResp">
     <button class="copy" title="Copy" />
     <span class="lang"></span>
      <pre><code>{{ JSON.stringify(jsonResp, null, 4) }}</code></pre>
diff --git a/data/doveadm.js b/data/doveadm.js
index 6cef96428..b4b4c38fe 100644
--- a/data/doveadm.js
+++ b/data/doveadm.js
@@ -2,8 +2,7 @@
 import { doveadm_arg_types,
 		 doveadm_args_query,
 		 doveadm_args_usermask,
-		 doveadm_flag_types,
-		 doveadm_response_types } from '../lib/doveadm.js'
+		 doveadm_flag_types } from '../lib/doveadm.js'
 
 export const doveadm = {
 
@@ -52,20 +51,21 @@ export const doveadm = {
 		// deprecated: {},
 		// removed: {},
 
-		// Response data.
-		// KEY = identifier
-		// response: {
-		//     key: {
-		//         // An example value to be used in documentation.
-		//         example: 0,
+		// Response data. (HTTP API)
+		//
+		// Since doveadm responses are so variable, it is difficult to create
+		// an abstracted system to document the format.
 		//
-		//         // The description of the response data type.
-		//         // Rendered w/Markdown.
-		//         text: `Description`,
+		// Thus, (for now) simply provide a place to describe HTTP API
+		// responses.
+		// response: {
+		//     // This is the JSON data returned from the server. Do NOT
+		//     // include the enclosing array, as this will be added
+		//     // automatically when displaying.
+		//     example: {},
 		//
-		//         // The response data type
-		//         type: doveadm_response_types.INTEGER,
-		//     }
+		//     // A description of the response. Rendered w/Markdown.
+		//     text: ``,
 		// },
 
 		// What doveadm flags does this command support (bit field)
@@ -252,10 +252,14 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only.
 			},
 		},
 		response: {
-			entries: {
-				type: doveadm_response_types.INTEGER,
-				text: `The number of cache entries flushed.`
+			example: {
+				entries: 1
 			},
+			text: `
+| Key | Description |
+| --- | ----------- |
+| \`entries\` | The number of cache entries flushed. |
+`
 		},
 		man: 'doveadm-auth',
 		text: `Flush authentication cache.`,
@@ -1372,7 +1376,7 @@ to secure it.
 				text: `Mailbox mask.`
 			},
 		},
-		response: {},
+		response: null,
 		flags: doveadm_flag_types.USER,
 		plugin: 'mail-crypt',
 		man: 'doveadm-mailbox-cryptokey',
@@ -1392,7 +1396,7 @@ to secure it.
 				text: `Mailbox mask.`
 			},
 		},
-		response: {},
+		response: null,
 		flags: doveadm_flag_types.USER,
 		plugin: 'mail-crypt',
 		man: 'doveadm-mailbox-cryptokey',
@@ -1427,7 +1431,7 @@ to secure it.
 				text: `Old password.`
 			},
 		},
-		response: {},
+		response: null,
 		flags: doveadm_flag_types.USER,
 		plugin: 'mail-crypt',
 		man: 'doveadm-mailbox-cryptokey',
diff --git a/lib/data/doveadm.data.js b/lib/data/doveadm.data.js
index d783c8b14..e2d70181b 100644
--- a/lib/data/doveadm.data.js
+++ b/lib/data/doveadm.data.js
@@ -1,4 +1,4 @@
-import { doveadm_arg_types, doveadm_flag_types, doveadm_response_types, getDoveadmCmdLine } from '../doveadm.js'
+import { doveadm_arg_types, doveadm_flag_types, getDoveadmCmdLine } from '../doveadm.js'
 import { getVitepressMd } from '../markdown.js'
 import { addWatchPaths, loadData, normalizeArrayData } from '../utility.js'
 import camelCase from 'camelcase'
@@ -53,15 +53,6 @@ function typeToString(type) {
 	}
 }
 
-function responseTypeLookup(type) {
-	switch (type) {
-	case doveadm_response_types.INTEGER:
-		return [ 'integer', 1 ]
-	case doveadm_response_types.STRING:
-		return [ 'string', 'example' ]
-	}
-}
-
 function argToHttpParam(arg) {
 	return arg.split('-').reduce((s, c) =>
 		s + (c.charAt(0).toUpperCase() + c.slice(1)))
@@ -108,19 +99,10 @@ async function normalizeDoveadm(doveadm) {
 
 		/* Response values. */
 		if (v.response) {
-			const response = []
-			for (const [k2, v2] of Object.entries(v.response)) {
-				var rtl = responseTypeLookup(v2.type)
-				response.push({
-					example: v2.example ?? rtl[1],
-					key: k2,
-					type: rtl[0],
-					text: v2.text ? md.renderInline(String(v2.text)) : null
-				})
+			if (v.response.text) {
+				v.response.text = md.render(String(v.response.text))
 			}
-			v.response = response
-		}
-		if (!v.response || !v.response.length) {
+		} else {
 			delete v['response']
 		}
 
diff --git a/lib/doveadm.js b/lib/doveadm.js
index b6367db44..548a9f057 100644
--- a/lib/doveadm.js
+++ b/lib/doveadm.js
@@ -16,12 +16,6 @@ export const doveadm_flag_types = {
 	USERMASK:		4,
 }
 
-/* List of Doveadm response value types. */
-export const doveadm_response_types = {
-	INTEGER:	1,
-	STRING:		2,
-}
-
 export const doveadm_args_query = {
 	//example: ['mailbox', 'INBOX/myfoldertoo', 'savedbefore', 'since', '30d'],
 	positional: true,

From 0ec2bb7fab1d96ab66467d811e50349ff4ced151 Mon Sep 17 00:00:00 2001
From: Michael M Slusarz <slusarz@users.noreply.github.com>
Date: Fri, 3 Jan 2025 12:58:50 -0700
Subject: [PATCH 2/3] doveadm: Improve HTTP API documentation

---
 docs/core/admin/doveadm.md | 109 +++++++++++++++++++++++++++----------
 1 file changed, 80 insertions(+), 29 deletions(-)

diff --git a/docs/core/admin/doveadm.md b/docs/core/admin/doveadm.md
index 12ae61dac..c1d67849d 100644
--- a/docs/core/admin/doveadm.md
+++ b/docs/core/admin/doveadm.md
@@ -101,27 +101,54 @@ service doveadm {
 Connecting to the endpoint can be done by using standard HTTP protocol and
 authentication headers.
 
-To get list the commands supported by the endpoint, the following example
-commands can be used:
+::: info
+There is also https://github.com/dovecot/doveadm-http-cli that can be
+used for accessing the API.
+:::
+
+All doveadm commands are accessed under the `/doveadm/v1` path.
+
+#### Command List
 
-#### `X-Dovecot-API` Auth
+To get the list of commands supported by the endpoint, send an authenticated
+GET request to the root of the endpoint (for all endpoint commands), or to
+`/doveadm/v1` path (for doveadm API commands).
+
+For example, using [[setting,doveadm_password]] authentication:
 
 ```console
-$ curl -H "Authorization: X-Dovecot-API <base64 dovecot_api_key>" \
-      http://host:port/doveadm/v1
+curl -X GET –u doveadm:password http://host:port/
 ```
 
-#### Basic Auth
+#### Authentication
+
+##### Basic Auth
+
+Use password as configured in [[setting,doveadm_password]]. User name is
+`doveadm`.
 
 ```
 curl -H "Authorization: Basic <base64 doveadm:doveadm_password>" http://host:port/doveadm/v1
+```
+
+or
+
+```console
 curl –u doveadm:password http://host:port/doveadm/v1
 ```
 
-There is also https://github.com/dovecot/doveadm-http-cli that can be
-used for accessing the API.
+##### `X-Dovecot-API` Auth
+
+Use API Key as configured in [[setting,doveadm_api_key]].
 
-### API overview
+```console
+$ curl -H "Authorization: X-Dovecot-API <base64 dovecot_api_key>" \
+      http://host:port/doveadm/v1
+```
+
+### API Overview
+
+#### Request
 
 All commands sent to the API needs to be posted in json format using
 `Content-Type: application/json` in headers for the request type and the
@@ -176,30 +203,28 @@ Also it is not guaranteed that the commands will be processed in order.
 All commands are case sensitive.
 :::
 
-### Example Session
-
-Reload Dovecot configuration:
+#### Response
 
-```json
-[
-    [
-        "reload",
-        {},
-        "tag1"
-    ]
-]
-```
+Requests that fail *before* the doveadm command is run returns 400/500
+HTTP response codes:
 
-Then we execute it with curl:
+| Code | Reason |
+| ---- | ------ |
+| 400 | Invalid request. Response body contains error message in text/plain. |
+| 401 | Unauthorized (missing authentication). |
+| 403 | Forbidden (authentication failed). |
+| 404 | Unknown doveadm command. |
+| 500 | Internal server error (see Dovecot logs for more information). |
 
-```console
-$ curl -v -u doveadm:secretpassword -X POST http://localhost:8080/doveadm/v1 \
-      -H "Content-Type: application/json" -d '[["reload",{},"tag1"]]'
-```
+Otherwise, the response will be a 200 code, Content-Type `application/json`,
+and the body will be a JSON object.
 
-This is equivalent to the command [[doveadm,reload]].
+##### Success
 
-Successful Response:
+::: info Note
+All data returned in the JSON object will be strings (e.g., counting fields
+will be strings, not numbers/integers).
+:::
 
 ```json
 [
@@ -211,7 +236,10 @@ Successful Response:
 ]
 ```
 
-Failure Response:
+##### Failure
+
+`exitCode` are the [[link,doveadm_error_codes]].
+
 ```json
 [
     [
@@ -225,6 +253,29 @@ Failure Response:
 ]
 ```
 
+### Example Session
+
+Reload Dovecot configuration:
+
+```json
+[
+    [
+        "reload",
+        {},
+        "tag1"
+    ]
+]
+```
+
+Then we execute it with curl:
+
+```console
+$ curl -v -u doveadm:secretpassword -X POST http://localhost:8080/doveadm/v1 \
+      -H "Content-Type: application/json" -d '[["reload",{},"tag1"]]'
+```
+
+This is equivalent to the command [[doveadm,reload]].
+
 ## Mailbox Commands
 
 These commands should be run on one of the Dovecot proxies. The proxy is then

From 5d862c851cbcb2e5d53778250c82710ab6623e24 Mon Sep 17 00:00:00 2001
From: Michael M Slusarz <slusarz@users.noreply.github.com>
Date: Fri, 3 Jan 2025 11:57:38 -0700
Subject: [PATCH 3/3] WIP: doveadm: Add responses to commands

---
 data/doveadm.js | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/data/doveadm.js b/data/doveadm.js
index b4b4c38fe..083e31d11 100644
--- a/data/doveadm.js
+++ b/data/doveadm.js
@@ -2273,6 +2273,37 @@ returned.`,
 				text: `UID mask.`,
 			},
 		},
+		response: {
+			example: [
+				{
+					username: "foo",
+					connections: "1",
+					service: "imap",
+					pid: "(47)",
+					ip: "(10.0.2.100)"
+				}
+			],
+			text: `
+Returns an array of objects.
+
+If \`separate-connections\` is \`false\`, each object represents a single
+username/service combination, and the \`pid\` and \`ip\` fields will include
+all entries for that combination.
+
+If \`separate-connections\` is \`true\`, each object will contain a single
+connection.
+
+Object fields:
+
+| Key | Description |
+| --- | ----------- |
+| \`connections\` | The total number of connections for the user. This is only returned if \`separate-connections\` is \`false\`. |
+| \`ip\` | IP addresses where the user's connections are originating. |
+| \`pid\` | Process IDs of the session. |
+| \`service\` | The Dovecot service. |
+| \`username\` | Username |
+`
+		},
 		man: 'doveadm-who',
 		text: `Show who is logged into the Dovecot server.`,
 	},