Open Administration on a dashboard of what the role can read

Administration used to open on its first section. It opens on a grid of
cards now: users, domains, messages waiting in the delivery queue, server
memory, and the last 24 hours' received and sent. Each card is there only
when the role holds what its number needs -- a count is a query, the
metric history a query and a get -- so a helpdesk role that reads accounts
and domains sees those two cards and nothing about the server.

What the cards count is whatever Stalwart answers for the signed-in
account, which scopes a tenant administrator's accounts, domains and queue
to the tenancy. The metric history has no tenant in it, and Stalwart's
Tenant Administrator role does not hold it, so a tenant's dashboard is
users, domains and pending.

The history is Enterprise-only and switched off by default. A server that
refuses it leaves those cards off; one that records nothing says so rather
than showing zeroes. Received and sent add up the queue counters Stalwart's
own dashboard uses, filtered with the comparison names the live server
accepts (a bare timestamp is unsupportedFilter). The column count follows
the number of cards so rows stay even, and falls back by the grid's own
width rather than the window's.

The server's test for whether an account is offered Administration matches
the client's again, now that a count is enough. The mock answers the queue
and an hourly history ending in the current hour; MOCK_METRICS=off refuses
the history as Community does, a tenant administrator gets the queue, and
helpdesk reads domains, as the demo's does.

ROADMAP and FEATURES said reporting and queues were out of scope; they say
the dashboard reads a handful of numbers and that managing queues, logs
and settings stays out. KNOWN-ISSUES records what was settled on the live
server and what was only read from source.

Fourteen new strings, in all nine catalogues.

web/src/lib/adminDashboard.ts

@@ -0,0 +1,128 @@
+import { client, JmapMethodError } from "@/jmap/client";
+
+/**
+ * The numbers on Administration's dashboard, over the ordinary JMAP proxy.
+ *
+ * Counts are queries with `calculateTotal` and `limit: 0`: Stalwart lifts its
+ * own limit when asked for a total, so the number is the whole count, and no
+ * ids come back to be thrown away. For a tenant administrator the server scopes
+ * all three to the tenancy -- accounts and domains to its members, the queue to
+ * messages touching its domains.
+ *
+ * The rest is read from `x:Metric`, the history Stalwart records once per
+ * collection interval (hourly by default): a Counter holds what happened in
+ * that interval, a Gauge the reading at its end. Received and sent are the sums
+ * Stalwart's own dashboard shows, over the same metric names. The history is
+ * Enterprise-only and has to be switched on (`x:MetricsStore`); a Community
+ * server refuses the query as `forbidden`, and one that records nothing
+ * answers with nothing -- the two cases the dashboard tells apart.
+ */
+
+export const RECEIVED_METRICS = ["queue.message-queued"] as const;
+export const SENT_METRICS = ["queue.authenticated-message-queued", "queue.dsn-queued", "queue.report-queued"] as const;
+export const MEMORY_METRIC = "server.memory";
+
+/** The window received and sent cover. */
+export const DASHBOARD_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+export interface MetricRecord {
+  "@type": "Counter" | "Gauge" | "Histogram";
+  metric: string;
+  count: number;
+  timestamp: string;
+  sum?: number;
+}
+
+export interface MessageStats {
+  received: number;
+  sent: number;
+  /** The latest memory reading, or null when none was recorded in the window. */
+  memory: { bytes: number; at: string } | null;
+  /**
+   * Whether the server recorded anything in the window. Memory is written every
+   * interval, so a window with no records at all is a history that is switched
+   * off -- not a quiet day, which would still say zero.
+   */
+  recorded: boolean;
+}
+
+export function summariseMetrics(records: readonly MetricRecord[]): MessageStats {
+  let received = 0;
+  let sent = 0;
+  let memory: MessageStats["memory"] = null;
+  const receivedNames = new Set<string>(RECEIVED_METRICS);
+  const sentNames = new Set<string>(SENT_METRICS);
+  for (const r of records) {
+    if (r["@type"] === "Counter") {
+      if (receivedNames.has(r.metric)) received += r.count;
+      else if (sentNames.has(r.metric)) sent += r.count;
+    } else if (r["@type"] === "Gauge" && r.metric === MEMORY_METRIC) {
+      if (!memory || r.timestamp > memory.at) memory = { bytes: r.count, at: r.timestamp };
+    }
+  }
+  return { received, sent, memory, recorded: records.length > 0 };
+}
+
+type CountedObject = "Account" | "Domain" | "QueuedMessage";
+
+/** How many there are. Accounts are counted as users: groups are accounts too. */
+export async function countObjects(object: CountedObject): Promise<number> {
+  const res = await client.call<{ total?: number; ids?: string[] }>(`x:${object}/query`, {
+    ...(object === "Account" ? { filter: { "@type": "User" } } : {}),
+    limit: 0,
+    calculateTotal: true,
+  });
+  return res.total ?? res.ids?.length ?? 0;
+}
+
+/**
+ * Every record of the dashboard's metrics since `since`, newest first.
+ *
+ * The filter keys are Stalwart's comparison names for the property -- a bare
+ * `timestamp` is `unsupportedFilter`. A day at the default hourly interval is
+ * well under one page; the paging is for a server that collects far more often.
+ */
+export async function loadMetrics(since: Date): Promise<MetricRecord[]> {
+  const filter = {
+    timestampIsGreaterThanOrEqual: since.toISOString().replace(/\.\d{3}Z$/, "Z"),
+    metric: [...RECEIVED_METRICS, ...SENT_METRICS, MEMORY_METRIC],
+  };
+  const step = client.maxObjectsInGet;
+  const out: MetricRecord[] = [];
+  for (let position = 0; ; position += step) {
+    const q = await client.call<{ ids?: string[] }>("x:Metric/query", { filter, sort: [{ property: "timestamp", isAscending: false }], position, limit: step });
+    const ids = q.ids ?? [];
+    if (ids.length) out.push(...(await client.call<{ list: MetricRecord[] }>("x:Metric/get", { ids })).list);
+    if (ids.length < step) return out;
+  }
+}
+
+/**
+ * How many columns the cards take, so no row is left short.
+ *
+ * `wide` is the most that divides the cards evenly without going past four;
+ * `mid` is what they drop to when that no longer fits, again only a count the
+ * cards divide into -- three cards go to one column rather than two and one.
+ * Five is the one count nothing divides, and takes three over two. A phone
+ * always gets one column, which the stylesheet decides.
+ */
+export function balancedColumns(cards: number): { wide: number; mid: number } {
+  switch (cards) {
+    case 0:
+    case 1:
+      return { wide: 1, mid: 1 };
+    case 2:
+      return { wide: 2, mid: 2 };
+    case 3:
+      return { wide: 3, mid: 1 };
+    case 4:
+      return { wide: 4, mid: 2 };
+    default:
+      return { wide: 3, mid: 2 };
+  }
+}
+
+/** A refusal from the server itself, as opposed to a failure to reach it. */
+export function isRefused(err: unknown): boolean {
+  return err instanceof JmapMethodError && err.error.type === "forbidden";
+}