Add status pages (a share link kind) and a downloadable Grafana dashboard
- Share links can open a status page: an admin picks servers, integrations and Uptime Kuma monitors and names them; the public sees only those names, Working / Not working / Being worked on / Can't tell, an optional message and the 30-day figure (share_links.kind/ title/message and status_items, migration 0033). A status address doesn't open the wall and the other way round; Uptime Kuma is asked at most every 30 seconds - Grafana dashboard built from code (download in Settings -> API and webhooks); a test checks it only uses series /metrics serves - Tests and docs Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
2744a84719
commit
5cc51c57de
24 files changed
+4880
-35
No files matched your search
@@ -0,0 +1,176 @@
|
||||
/**
|
||||
* The Grafana dashboard: that it is a dashboard Grafana will import, that every panel sits on the grid, and — the point of building it
|
||||
* here — that it only asks for series `/metrics` really serves, so renaming one can't quietly blank a panel.
|
||||
*
|
||||
* Run with: npm test --workspace server
|
||||
*/
|
||||
import { test, describe, before, after } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { mkdtempSync, readFileSync, rmSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { dirname, join } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import type { AddressInfo } from "node:net";
|
||||
import type { Server } from "node:http";
|
||||
|
||||
const dir = mkdtempSync(join(tmpdir(), "hm-grafana-"));
|
||||
process.env.DATABASE_PATH = join(dir, "test.sqlite");
|
||||
process.env.SESSION_DIR = join(dir, "sessions");
|
||||
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
|
||||
|
||||
const express = (await import("express")).default;
|
||||
const { db } = await import("../src/db/client.js");
|
||||
const { users } = await import("../src/db/schema.js");
|
||||
const { runMigrations } = await import("../src/db/migrate.js");
|
||||
const { buildGrafanaDashboard } = await import("../src/services/grafanaDashboard.js");
|
||||
const { metricsTokensRouter } = await import("../src/routes/metrics.js");
|
||||
|
||||
await runMigrations();
|
||||
|
||||
type Panel = { id: number; type: string; title: string; gridPos: { h: number; w: number; x: number; y: number }; targets?: { expr: string; legendFormat: string; refId: string; datasource: { uid: string } }[]; datasource?: { uid: string } };
|
||||
const dashboard = buildGrafanaDashboard() as { panels: Panel[]; templating: { list: { name: string }[] }; __inputs: { name: string }[]; uid: string; title: string; schemaVersion: number };
|
||||
const panels = dashboard.panels;
|
||||
const withQueries = panels.filter((p) => p.targets);
|
||||
const exprs = withQueries.flatMap((p) => p.targets!.map((t) => t.expr));
|
||||
|
||||
// What /metrics can serve: every series the code that builds it adds.
|
||||
const here = dirname(fileURLToPath(import.meta.url));
|
||||
const served = new Set([...readFileSync(join(here, "..", "src", "services", "metrics.ts"), "utf8").matchAll(/out\.add\(\s*"(homelab_[a-z0-9_]+)"/g)].map((m) => m[1]));
|
||||
|
||||
describe("the dashboard is one Grafana will import", () => {
|
||||
test("it has a title, a fixed id, asks which Prometheus to use, and every query uses that choice", () => {
|
||||
assert.equal(dashboard.title, "Homelab Manager");
|
||||
assert.equal(dashboard.uid, "homelab-manager");
|
||||
assert.ok(dashboard.schemaVersion >= 36);
|
||||
assert.deepEqual(dashboard.__inputs.map((i) => i.name), ["DS_PROMETHEUS"]);
|
||||
for (const p of withQueries) {
|
||||
assert.equal(p.datasource?.uid, "${DS_PROMETHEUS}", p.title);
|
||||
for (const t of p.targets!) assert.equal(t.datasource.uid, "${DS_PROMETHEUS}", `${p.title} / ${t.refId}`);
|
||||
}
|
||||
});
|
||||
|
||||
test("it survives being written out and read back, as an import does", () => {
|
||||
const again = JSON.parse(JSON.stringify(dashboard));
|
||||
assert.equal(again.panels.length, panels.length);
|
||||
assert.ok(panels.length >= 30, `${panels.length} panels`);
|
||||
});
|
||||
|
||||
test("every panel has an id of its own, a title, and sits on the 24-column grid without overlapping another", () => {
|
||||
assert.equal(new Set(panels.map((p) => p.id)).size, panels.length, "ids are unique");
|
||||
for (const p of panels) {
|
||||
assert.ok(p.title, `panel ${p.id} has no title`);
|
||||
const g = p.gridPos;
|
||||
assert.ok(g.x >= 0 && g.w >= 1 && g.x + g.w <= 24, `${p.title} sits outside the grid: ${JSON.stringify(g)}`);
|
||||
assert.ok(g.h >= 1 && g.y >= 0);
|
||||
}
|
||||
for (let i = 0; i < panels.length; i++) {
|
||||
for (let j = i + 1; j < panels.length; j++) {
|
||||
const a = panels[i].gridPos;
|
||||
const b = panels[j].gridPos;
|
||||
const overlap = a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
|
||||
assert.equal(overlap, false, `${panels[i].title} overlaps ${panels[j].title}`);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
test("it is in rows, and the rows come in a sensible order", () => {
|
||||
const rows = panels.filter((p) => p.type === "row").map((p) => p.title);
|
||||
assert.deepEqual(rows, ["Needs attention", "Servers", "Disks", "Backups", "Secrets, power and the app itself"]);
|
||||
const ys = panels.filter((p) => p.type === "row").map((p) => p.gridPos.y);
|
||||
assert.deepEqual([...ys].sort((a, b) => a - b), ys, "top to bottom");
|
||||
});
|
||||
});
|
||||
|
||||
describe("what it asks for", () => {
|
||||
test("it asks only for series /metrics serves (and says so if one is renamed)", () => {
|
||||
assert.ok(served.size >= 30, `found ${served.size} served series in metrics.ts`);
|
||||
const asked = new Set(exprs.flatMap((e) => e.match(/\bhomelab_[a-z0-9_]+\b/g) ?? []));
|
||||
assert.ok(asked.size >= 25, `the dashboard uses ${asked.size} series`);
|
||||
const missing = [...asked].filter((m) => !served.has(m));
|
||||
assert.deepEqual(missing, [], `series the dashboard uses that /metrics doesn't serve: ${missing.join(", ")}`);
|
||||
});
|
||||
|
||||
test("the big groups of series are all covered", () => {
|
||||
const asked = new Set(exprs.flatMap((e) => e.match(/\bhomelab_[a-z0-9_]+\b/g) ?? []));
|
||||
for (const m of [
|
||||
"homelab_alerts", "homelab_incidents_open", "homelab_server_up", "homelab_server_disk_used_percent", "homelab_server_disk_days_to_full", "homelab_server_disk_healthy",
|
||||
"homelab_server_zfs_pool_online", "homelab_backup_guests", "homelab_backup_last_age_seconds", "homelab_selfbackup_last_success_timestamp_seconds", "homelab_secret_expiry_days",
|
||||
"homelab_integration_up", "homelab_server_uptime_ratio_30d", "homelab_server_pending_updates",
|
||||
]) assert.ok(asked.has(m), `${m} has no panel`);
|
||||
});
|
||||
|
||||
test("each query is well-formed: not empty, brackets and quotes balanced, no stray template text", () => {
|
||||
for (const p of withQueries) {
|
||||
for (const t of p.targets!) {
|
||||
const e = t.expr;
|
||||
assert.ok(e.trim().length > 0, `${p.title}: empty query`);
|
||||
for (const [open, close] of [["(", ")"], ["{", "}"], ["[", "]"]]) assert.equal(e.split(open).length, e.split(close).length, `${p.title}: unbalanced ${open}${close} in ${e}`);
|
||||
assert.equal(e.split('"').length % 2, 1, `${p.title}: an unclosed quote in ${e}`);
|
||||
assert.doesNotMatch(e, /undefined|\[object/, `${p.title}: ${e}`);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
test("the server picker exists, takes its values from the series, and everything that uses it is told how", () => {
|
||||
const names = dashboard.templating.list.map((v) => v.name);
|
||||
assert.deepEqual(names, ["server"]);
|
||||
const variable = dashboard.templating.list[0] as unknown as { query: { query: string }; allValue: string; multi: boolean };
|
||||
assert.equal(variable.query.query, "label_values(homelab_server_up, server)");
|
||||
assert.equal(variable.multi, true);
|
||||
assert.equal(variable.allValue, ".+", "all servers, including ones with no label at all, matches");
|
||||
const using = exprs.filter((e) => e.includes("$server"));
|
||||
assert.ok(using.length >= 10);
|
||||
for (const e of using) assert.match(e, /\{server=~"\$server"\}/);
|
||||
});
|
||||
|
||||
test("series that exist only once something happens use 'or vector(0)' where a stat would otherwise read 'No data'", () => {
|
||||
for (const title of ["Critical alerts", "Warnings", "Servers down", "Integrations failing", "Servers up"]) {
|
||||
const p = withQueries.find((x) => x.title === title)!;
|
||||
assert.match(p.targets![0].expr, /or vector\(0\)/, title);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("downloading it", () => {
|
||||
let app: Server;
|
||||
let base = "";
|
||||
let who = "ada";
|
||||
before(async () => {
|
||||
await db.insert(users).values([
|
||||
{ oidcSub: "ada", name: "Ada", role: "admin" },
|
||||
{ oidcSub: "olle", name: "Olle", role: "operator" },
|
||||
]);
|
||||
const a = express();
|
||||
a.use(express.json());
|
||||
a.use((req, _res, next) => {
|
||||
(req as unknown as { session: unknown }).session = { user: { sub: who } };
|
||||
next();
|
||||
});
|
||||
a.use("/api/metrics-tokens", metricsTokensRouter);
|
||||
app = await new Promise<Server>((resolve) => {
|
||||
const x = a.listen(0, "127.0.0.1", () => resolve(x));
|
||||
});
|
||||
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/metrics-tokens`;
|
||||
});
|
||||
after(() => {
|
||||
app.close();
|
||||
try {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
} catch {
|
||||
// Windows keeps the database file locked until the process exits.
|
||||
}
|
||||
});
|
||||
|
||||
test("an administrator gets it as a file; nobody else does", async () => {
|
||||
who = "olle";
|
||||
assert.equal((await fetch(`${base}/grafana-dashboard.json`)).status, 403);
|
||||
who = "ada";
|
||||
const res = await fetch(`${base}/grafana-dashboard.json`);
|
||||
assert.equal(res.status, 200);
|
||||
assert.match(res.headers.get("content-disposition") ?? "", /attachment; filename="homelab-manager-dashboard\.json"/);
|
||||
assert.match(res.headers.get("content-type") ?? "", /application\/json/);
|
||||
const body = await res.json();
|
||||
assert.equal(body.uid, "homelab-manager");
|
||||
assert.equal(body.panels.length, panels.length);
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user