Add automx_rows, a read-only tool for the rows automx answers from (issue 1630)

modules/mailu/automx.ts

@@ -0,0 +1,59 @@
+// What the autoconfiguration module (automx2) holds, as stored: its provider, server, domain and server_domain
+// rows, read from its SQLite file inside its container with the sqlite3 program the image carries, opened
+// read-only. Nothing is written and nothing is interpreted: the rows are the evidence for what automx answers
+// to mail clients (novox/hq issue 1630, ADR 0480), and the reason the answer may be empty.
+
+import type { Exec } from "./health.js";
+
+export const AUTOMX_DATABASE = "/data/db.sqlite";
+
+/** The tables read, each with the one query that reads it. Fixed text: the tool takes no query from its caller. */
+export const AUTOMX_TABLES: Record<string, string> = {
+  provider: "SELECT id, name, short_name FROM provider ORDER BY id",
+  server: "SELECT id, prio, name, port, type, socket_type, user_name, authentication FROM server ORDER BY id",
+  domain: "SELECT id, name, provider_id, ldapserver_id FROM domain ORDER BY id",
+  server_domain: "SELECT server_id, domain_id FROM server_domain ORDER BY domain_id, server_id",
+};
+
+export type Row = Record<string, string | number | null>;
+
+export type AutomxRows = {
+  database: string;
+  tables: Record<string, Row[]>;
+  /** servers whose name is empty: the client is told an empty host name for them */
+  empty_names: { id: number; type: string }[];
+  /** tables that could not be read, each with what sqlite3 or docker said on one line */
+  unreadable: Record<string, string>;
+};
+
+/** sqlite3 -json prints one JSON array, or nothing at all for a table without rows. */
+export function parseRows(output: string): Row[] {
+  const text = output.trim();
+  if (text === "") return [];
+  const rows = JSON.parse(text) as unknown;
+  if (!Array.isArray(rows)) throw new Error("sqlite3 did not print a list of rows");
+  return rows as Row[];
+}
+
+/** The command that reads one table: read-only, JSON, one fixed statement. */
+export function readCommand(sql: string): string[] {
+  return ["sqlite3", "-readonly", "-json", AUTOMX_DATABASE, sql];
+}
+
+/** Read every table; one that fails is said in `unreadable` and does not hide the others. */
+export async function readAutomx(exec: Exec, container: string): Promise<AutomxRows> {
+  const answer: AutomxRows = { database: AUTOMX_DATABASE, tables: {}, empty_names: [], unreadable: {} };
+  for (const [table, sql] of Object.entries(AUTOMX_TABLES)) {
+    try {
+      answer.tables[table] = parseRows(await exec(container, readCommand(sql)));
+    } catch (e) {
+      const err = e as { stderr?: string; message?: string };
+      const text = (err?.stderr ?? "").trim() || (err?.message ?? String(e)).trim();
+      answer.unreadable[table] = text.split("\n").map((l) => l.trim()).filter(Boolean)[0] ?? "it failed and said nothing";
+    }
+  }
+  for (const s of answer.tables.server ?? []) {
+    if (String(s.name ?? "").trim() === "") answer.empty_names.push({ id: Number(s.id), type: String(s.type) });
+  }
+  return answer;
+}

modules/mailu/module.json

@@ -71,7 +71,8 @@
     "mailu_list_domains",
     "mailu_read_mail",
     "mailu_search_mail",
-    "mailu_health"
+    "mailu_health",
+    "automx_rows"
   ],
   "emits": [
     "user.created",

modules/mailu/test/automx-rows.test.ts

@@ -0,0 +1,81 @@
+// What automx_rows reads (novox/hq issue 1630): the rows of automx2's database as stored, through a read-only
+// sqlite3 inside its container. The database here is a real SQLite file made by the test with the tables
+// automx/files/setup-db creates and the rows add-domains writes — with the IMAP server's name empty, the case
+// the live instance is in. The fake container runs each command's statement against that database and prints
+// it the way `sqlite3 -json` does (one JSON array, nothing for no rows). Run against the compiled module.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { DatabaseSync } from "node:sqlite";
+
+import { readAutomx, readCommand, AUTOMX_DATABASE } from "../dist/automx.js";
+
+function database(imapName: string): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(`
+    CREATE TABLE provider(id INT PRIMARY KEY NOT NULL, name TEXT NOT NULL, short_name TEXT NOT NULL);
+    CREATE TABLE server(id INT PRIMARY KEY NOT NULL, prio INT NOT NULL DEFAULT 10, name TEXT NOT NULL, port INT NOT NULL,
+      type TEXT NOT NULL, socket_type TEXT NOT NULL, user_name TEXT NOT NULL, authentication TEXT NOT NULL);
+    CREATE TABLE domain(id INT PRIMARY KEY NOT NULL, name TEXT NOT NULL, provider_id INT NOT NULL, ldapserver_id INT NULL);
+    CREATE TABLE server_domain(server_id INT NOT NULL, domain_id INT NOT NULL);
+    INSERT INTO provider VALUES (1, 'example.org', 'example.org');
+    INSERT INTO server(id, port, type, name, socket_type, user_name, authentication)
+      VALUES (2, 143, 'imap', '${imapName}', 'STARTTLS', '%EMAILADDRESS%', 'password-cleartext');
+    INSERT INTO server(id, port, type, name, socket_type, user_name, authentication)
+      VALUES (3, 587, 'smtp', 'mail.example.org', 'STARTTLS', '%EMAILADDRESS%', 'password-cleartext');
+    INSERT INTO domain VALUES (5, 'example.org', 1, NULL);
+    INSERT INTO server_domain VALUES (2, 5), (3, 5);
+  `);
+  return db;
+}
+
+function container(db: DatabaseSync, asked: string[][] = []) {
+  return async (_name: string, command: string[]) => {
+    asked.push(command);
+    const rows = db.prepare(command[command.length - 1]).all();
+    return rows.length === 0 ? "" : JSON.stringify(rows) + "\n";
+  };
+}
+
+test("the rows come back as stored, and an empty server name is said", async () => {
+  const answer = await readAutomx(container(database("")), "mailu-automx");
+  assert.equal(answer.database, AUTOMX_DATABASE);
+  assert.deepEqual(answer.unreadable, {});
+  assert.deepEqual(answer.tables.provider, [{ id: 1, name: "example.org", short_name: "example.org" }]);
+  assert.deepEqual(answer.tables.domain, [{ id: 5, name: "example.org", provider_id: 1, ldapserver_id: null }]);
+  assert.deepEqual(answer.tables.server_domain, [{ server_id: 2, domain_id: 5 }, { server_id: 3, domain_id: 5 }]);
+  assert.deepEqual(
+    answer.tables.server.map((s) => [s.id, s.type, s.name, s.port]),
+    [[2, "imap", "", 143], [3, "smtp", "mail.example.org", 587]],
+  );
+  assert.deepEqual(answer.empty_names, [{ id: 2, type: "imap" }]);
+});
+
+test("a named IMAP server is not reported empty", async () => {
+  const answer = await readAutomx(container(database("mail.example.org")), "mailu-automx");
+  assert.deepEqual(answer.empty_names, []);
+});
+
+test("every command opens the file read-only and runs one fixed SELECT", async () => {
+  const asked: string[][] = [];
+  await readAutomx(container(database("x"), asked), "mailu-automx");
+  assert.equal(asked.length, 4);
+  for (const c of asked) {
+    assert.deepEqual(c.slice(0, 4), ["sqlite3", "-readonly", "-json", AUTOMX_DATABASE]);
+    assert.match(c[4], /^SELECT /);
+    assert.equal(c.length, 5);
+  }
+  assert.deepEqual(readCommand("SELECT 1").length, 5);
+});
+
+test("a table that cannot be read is said and does not hide the others", async () => {
+  const db = database("x");
+  const exec = async (name: string, command: string[]) => {
+    if (command[4].includes("FROM domain ")) throw Object.assign(new Error("Command failed: docker exec"), { stderr: "Error: unable to open database file\nmore" });
+    return container(db)(name, command);
+  };
+  const answer = await readAutomx(exec, "mailu-automx");
+  assert.deepEqual(answer.unreadable, { domain: "Error: unable to open database file" });
+  assert.equal(answer.tables.provider.length, 1);
+  assert.equal(answer.tables.domain, undefined);
+});

modules/mailu/test/mail-flows.test.ts

@@ -135,6 +135,7 @@ test("the health tool is served without the admin API, on the smtp container it
   await import("../dist/tools/index.js");
   const mailu = collectTools({ MESH_MAILU_SMTP_CONTAINER: "mailu-smtp" }).find((m) => m.module === "mailu");
   const names = (mailu?.tools ?? []).map((t) => t.name);
-  assert.deepEqual(names, ["mailu_health"]);
+  assert.deepEqual(names, ["mailu_health", "automx_rows"]);
   assert.match(mailu!.tools[0].description, /inside mailu-smtp/);
+  assert.match(mailu!.tools[1].description, /read-only, inside mailu-automx/);
 });

modules/mailu/tools/index.ts

@@ -4,6 +4,7 @@
 
 import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
 import { MailuClient } from "../client.js";
+import { readAutomx } from "../automx.js";
 import { dockerExec, mailFlows, DEFERRED_BOUND_SECONDS, PUBLIC_NAME, SPREAD_DOMAINS } from "../health.js";
 
 /**
@@ -26,6 +27,23 @@ export function getHealthTool(env: NodeJS.ProcessEnv): ToolDefinition {
   };
 }
 
+/**
+ * What automx holds, as stored (novox/hq issue 1630): the rows behind the answers it gives mail clients. It needs
+ * no admin API, only the automx container, so like the health tool it is served without the API.
+ */
+export function getAutomxTool(env: NodeJS.ProcessEnv): ToolDefinition {
+  const container = env.MESH_MAILU_AUTOMX_CONTAINER || "mailu-automx";
+  return {
+    name: "automx_rows",
+    description:
+      `Read the autoconfiguration module's database, as stored, read-only, inside ${container}: its provider, ` +
+      "server, domain and server_domain rows, and the servers whose name is empty (a mail client is then told " +
+      "an empty host name). Writes nothing.",
+    input: {},
+    run: async () => readAutomx(dockerExec(), container),
+  };
+}
+
 export function getMailuTools(mailu: MailuClient): ToolDefinition[] {
   return [
     {
@@ -173,5 +191,5 @@ registerModuleTools("mailu", (env) => {
   } catch {
     tools = [];
   }
-  return [...tools, getHealthTool(env)];
+  return [...tools, getHealthTool(env), getAutomxTool(env)];
 });

modules/mailu/tsconfig.json

@@ -8,5 +8,5 @@
     "skipLibCheck": true,
     "noEmit": true
   },
-  "include": ["client.ts", "health.ts", "index.ts", "tools/index.ts"]
+  "include": ["client.ts", "health.ts", "automx.ts", "index.ts", "tools/index.ts"]
 }