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.
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { ADMIN_BASELINE, adminSections, can, canGrantRole, generatePassword, hasAdministration, outranks, permissionSet, resolveRoles, type RoleDef } from "@/lib/adminAccess";
|
||||
import { ADMIN_BASELINE, adminSections, can, dashboardCards, canGrantRole, generatePassword, hasAdministration, outranks, permissionSet, resolveRoles, type RoleDef } from "@/lib/adminAccess";
|
||||
|
||||
const set = (...p: string[]) => permissionSet(p);
|
||||
const everything = set(...ADMIN_BASELINE, "sysTenantGet", "jmapEmailGet", "impersonate");
|
||||
@@ -12,17 +12,27 @@ const roles = new Map<string, RoleDef>([
|
||||
]);
|
||||
|
||||
describe("who is offered administration", () => {
|
||||
it("needs both halves of reading the account list", () => {
|
||||
expect(hasAdministration(set("sysAccountQuery", "sysAccountGet"))).toBe(true);
|
||||
expect(hasAdministration(set("sysAccountQuery"))).toBe(false);
|
||||
it("needs both halves of reading the account list to list accounts", () => {
|
||||
expect(adminSections(set("sysAccountQuery", "sysAccountGet"))).toEqual(["dashboard", "accounts"]);
|
||||
// A query alone is a count on the dashboard, not a list.
|
||||
expect(adminSections(set("sysAccountQuery"))).toEqual(["dashboard"]);
|
||||
expect(hasAdministration(set("sysAccountGet"))).toBe(false);
|
||||
expect(hasAdministration(permissionSet(undefined))).toBe(false);
|
||||
});
|
||||
|
||||
it("offers each section only with both halves of reading it", () => {
|
||||
expect(adminSections(set("sysDomainQuery", "sysDomainGet"))).toEqual(["domains"]);
|
||||
expect(adminSections(set("sysDomainQuery", "sysDomainGet"))).toEqual(["dashboard", "domains"]);
|
||||
expect(hasAdministration(set("sysDomainQuery", "sysDomainGet"))).toBe(true);
|
||||
expect(adminSections(set("sysAccountQuery", "sysAccountGet", "sysDomainQuery"))).toEqual(["accounts"]);
|
||||
expect(adminSections(set("sysAccountQuery", "sysAccountGet", "sysDomainQuery"))).toEqual(["dashboard", "accounts"]);
|
||||
});
|
||||
|
||||
it("gives the dashboard a card for each number the role can read", () => {
|
||||
expect(dashboardCards(set("sysAccountQuery", "sysAccountGet", "sysDomainQuery", "sysDomainGet"))).toEqual(["users", "domains"]);
|
||||
expect(dashboardCards(set("sysQueuedMessageQuery"))).toEqual(["pending"]);
|
||||
// The history takes its get as well: the query only finds the records.
|
||||
expect(dashboardCards(set("sysMetricQuery"))).toEqual([]);
|
||||
expect(dashboardCards(set("sysMetricQuery", "sysMetricGet"))).toEqual(["memory", "received", "sent"]);
|
||||
expect(adminSections(set("jmapEmailGet"))).toEqual([]);
|
||||
});
|
||||
|
||||
it("reads one permission per object and operation", () => {
|
||||
|
||||
@@ -0,0 +1,87 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import { client, JmapMethodError } from "@/jmap/client";
|
||||
import { balancedColumns, countObjects, isRefused, loadMetrics, summariseMetrics, type MetricRecord } from "@/lib/adminDashboard";
|
||||
|
||||
const counter = (metric: string, count: number, timestamp = "2026-09-15T14:00:00Z"): MetricRecord => ({ "@type": "Counter", metric, count, timestamp });
|
||||
|
||||
describe("the dashboard's message numbers", () => {
|
||||
it("adds received and sent up over the metric names Stalwart's own dashboard uses", () => {
|
||||
const stats = summariseMetrics([
|
||||
counter("queue.message-queued", 6),
|
||||
counter("queue.message-queued", 4, "2026-09-15T13:00:00Z"),
|
||||
counter("queue.authenticated-message-queued", 2),
|
||||
counter("queue.dsn-queued", 1),
|
||||
counter("queue.report-queued", 3),
|
||||
// Recorded, but not either number.
|
||||
counter("message-ingest.ham", 50),
|
||||
]);
|
||||
expect(stats.received).toBe(10);
|
||||
expect(stats.sent).toBe(6);
|
||||
});
|
||||
|
||||
it("reads memory from the newest gauge, not the first one listed", () => {
|
||||
const stats = summariseMetrics([
|
||||
{ "@type": "Gauge", metric: "server.memory", count: 100, timestamp: "2026-09-15T12:00:00Z" },
|
||||
{ "@type": "Gauge", metric: "server.memory", count: 300, timestamp: "2026-09-15T14:00:00Z" },
|
||||
{ "@type": "Gauge", metric: "queue.count", count: 7, timestamp: "2026-09-15T15:00:00Z" },
|
||||
]);
|
||||
expect(stats.memory).toEqual({ bytes: 300, at: "2026-09-15T14:00:00Z" });
|
||||
});
|
||||
|
||||
it("tells a history that records nothing from a quiet day", () => {
|
||||
expect(summariseMetrics([]).recorded).toBe(false);
|
||||
const quiet = summariseMetrics([{ "@type": "Gauge", metric: "server.memory", count: 1, timestamp: "2026-09-15T14:00:00Z" }]);
|
||||
expect(quiet).toMatchObject({ recorded: true, received: 0, sent: 0 });
|
||||
});
|
||||
});
|
||||
|
||||
describe("the dashboard's queries", () => {
|
||||
it("counts users rather than accounts, and asks for no ids", async () => {
|
||||
const call = vi.spyOn(client, "call").mockResolvedValue({ ids: [], total: 5 });
|
||||
expect(await countObjects("Account")).toBe(5);
|
||||
expect(call).toHaveBeenCalledWith("x:Account/query", { filter: { "@type": "User" }, limit: 0, calculateTotal: true });
|
||||
await countObjects("QueuedMessage");
|
||||
expect(call).toHaveBeenLastCalledWith("x:QueuedMessage/query", { limit: 0, calculateTotal: true });
|
||||
call.mockRestore();
|
||||
});
|
||||
|
||||
it("filters the history with Stalwart's comparison names, and pages the gets", async () => {
|
||||
// A bare `timestamp` or `after` is unsupportedFilter on a live server.
|
||||
vi.spyOn(client, "maxObjectsInGet", "get").mockReturnValue(2);
|
||||
const call = vi.spyOn(client, "call").mockImplementation(async (method, args) => {
|
||||
if (method === "x:Metric/query") return (args as { position: number }).position === 0 ? { ids: ["a", "b"] } : { ids: ["c"] };
|
||||
return { list: ((args as { ids: string[] }).ids).map((id) => counter("queue.message-queued", 1, id)) };
|
||||
});
|
||||
const records = await loadMetrics(new Date("2026-09-14T15:30:00.123Z"));
|
||||
expect(records).toHaveLength(3);
|
||||
expect(call.mock.calls[0]).toEqual([
|
||||
"x:Metric/query",
|
||||
{
|
||||
filter: { timestampIsGreaterThanOrEqual: "2026-09-14T15:30:00Z", metric: ["queue.message-queued", "queue.authenticated-message-queued", "queue.dsn-queued", "queue.report-queued", "server.memory"] },
|
||||
sort: [{ property: "timestamp", isAscending: false }],
|
||||
position: 0,
|
||||
limit: 2,
|
||||
},
|
||||
]);
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
it("treats only a forbidden answer as the server refusing", () => {
|
||||
expect(isRefused(new JmapMethodError("x:Metric/query", { type: "forbidden" }))).toBe(true);
|
||||
expect(isRefused(new JmapMethodError("x:Metric/query", { type: "serverFail" }))).toBe(false);
|
||||
expect(isRefused(new Error("offline"))).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("the card grid", () => {
|
||||
it("never leaves a row short when the cards can be divided evenly", () => {
|
||||
for (const n of [1, 2, 3, 4, 6]) {
|
||||
const { wide, mid } = balancedColumns(n);
|
||||
expect(n % wide, `${n} cards across ${wide}`).toBe(0);
|
||||
expect(n % mid, `${n} cards across ${mid}`).toBe(0);
|
||||
expect(wide).toBeLessThanOrEqual(4);
|
||||
}
|
||||
expect(balancedColumns(6)).toEqual({ wide: 3, mid: 2 });
|
||||
expect(balancedColumns(3)).toEqual({ wide: 3, mid: 1 });
|
||||
});
|
||||
});
|
||||
@@ -14,7 +14,7 @@
|
||||
* for a check Stalwart does not make. See there.
|
||||
*/
|
||||
|
||||
export type AdminObject = "Account" | "Domain" | "Role" | "MailingList" | "DkimSignature" | "DnsServer" | "Tenant";
|
||||
export type AdminObject = "Account" | "Domain" | "Role" | "MailingList" | "DkimSignature" | "DnsServer" | "Tenant" | "QueuedMessage" | "Metric";
|
||||
export type AdminOp = "Get" | "Query" | "Create" | "Update" | "Destroy";
|
||||
|
||||
export type Permissions = ReadonlySet<string>;
|
||||
@@ -27,16 +27,39 @@ export function can(perms: Permissions, object: AdminObject, op: AdminOp): boole
|
||||
return perms.has(`sys${object}${op}`);
|
||||
}
|
||||
|
||||
export type AdminSection = "accounts" | "domains";
|
||||
export type AdminSection = "dashboard" | "accounts" | "domains";
|
||||
|
||||
export type DashboardCard = "users" | "domains" | "pending" | "memory" | "received" | "sent";
|
||||
|
||||
/**
|
||||
* The dashboard's cards an account may see.
|
||||
*
|
||||
* A count is a query with `calculateTotal`, so a query alone earns one. The
|
||||
* three read from the metric history need the get as well, since the query
|
||||
* only finds the records. Stalwart scopes the first three to a tenant
|
||||
* administrator's own tenancy; the metric history has no tenant in it at all,
|
||||
* and the Tenant Administrator role Stalwart creates does not hold it -- which
|
||||
* is how a tenant's dashboard comes to show only what is theirs.
|
||||
*/
|
||||
export function dashboardCards(perms: Permissions): DashboardCard[] {
|
||||
const out: DashboardCard[] = [];
|
||||
if (can(perms, "Account", "Query")) out.push("users");
|
||||
if (can(perms, "Domain", "Query")) out.push("domains");
|
||||
if (can(perms, "QueuedMessage", "Query")) out.push("pending");
|
||||
if (can(perms, "Metric", "Query") && can(perms, "Metric", "Get")) out.push("memory", "received", "sent");
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* The sections an account may open, in the order they are listed.
|
||||
*
|
||||
* A list that cannot be read is not worth an entry, so each takes both halves
|
||||
* of reading one: the query that finds the objects and the get that shows them.
|
||||
* The dashboard comes first, and is there whenever it has a card to show.
|
||||
*/
|
||||
export function adminSections(perms: Permissions): AdminSection[] {
|
||||
const out: AdminSection[] = [];
|
||||
if (dashboardCards(perms).length) out.push("dashboard");
|
||||
if (can(perms, "Account", "Query") && can(perms, "Account", "Get")) out.push("accounts");
|
||||
if (can(perms, "Domain", "Query") && can(perms, "Domain", "Get")) out.push("domains");
|
||||
return out;
|
||||
|
||||
@@ -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";
|
||||
}
|
||||
Reference in New Issue
Block a user