Files
Homelab-manager/server/test/inspector.test.ts
T
bobbanandClaude Sonnet 5.5 93aaf5476d Lidarr/Readarr, integration inspector, app versions, grouped alerts
Lidarr and Readarr join the shared *arr reader. Integrations get an Inspect button that
runs the reader once and shows what each request returned as shapes (never values) and
where the result is empty. Operations -> App versions compares each application's version
with its newest GitHub release (lookup off until an admin switches it on; optional alert).
The Alerts page can group by source, kind of problem or type of alert. The shared HTTP
helper no longer reuses connections (stale-socket resets). Migration 0078; docs and tests
included.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-29 20:07:36 +01:00

205 lines
12 KiB
TypeScript

/**
* The integration inspector: what an answer looks like (names and kinds, never values), where what a reader made of it is empty, the requests written down while a read runs, and the route that
* runs one for an administrator.
*
* Run with: npm test --workspace server
*/
import { test, describe, before, after } from "node:test";
import assert from "node:assert/strict";
import { createServer as createHttpServer, type Server } from "node:http";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { AddressInfo } from "node:net";
const dir = mkdtempSync(join(tmpdir(), "hm-inspect-"));
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, integrations, auditLog } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const insp = await import("../src/integrations/inspector.js");
const { requestJson } = await import("../src/integrations/httpJson.js");
const { integrationsRouter } = await import("../src/routes/integrations.js");
const { eq } = await import("drizzle-orm");
await runMigrations();
describe("what an answer looks like", () => {
test("keys and the kinds of what they hold — and never a value", () => {
const s = insp.shapeOf({ id: 7, name: "super-secret-name", ok: true, nothing: null, tags: ["a", "b"], nested: { when: "2026-01-01", n: 1.5 } });
assert.equal(s, "{ id: number, name: string, ok: boolean, nothing: null, tags: array(2) of string, nested: { when: string, n: number } }");
assert.doesNotMatch(s, /super-secret|2026|7\b/);
});
test("a list of objects shows the keys of them all, and marks a key that only some have", () => {
const s = insp.shapeOf([{ id: 1, name: "a" }, { id: 2, name: "b", extra: 1 }, { id: 3, name: "c" }]);
assert.equal(s, "array(3) of { id: number, name: string, extra?: number }");
assert.equal(insp.shapeOf([]), "array(0)");
assert.equal(insp.shapeOf([1, "x", null]), "array(3) of number | string | null");
assert.equal(insp.shapeOf("text"), "string");
});
test("it goes three levels down and no further, caps the keys and the length", () => {
assert.equal(insp.shapeOf({ a: { b: { c: { d: { e: 1 } } } } }), "{ a: { b: { c: object } } }");
const many = Object.fromEntries(Array.from({ length: 40 }, (_, i) => [`k${i}`, i]));
assert.match(insp.shapeOf(many), /, … \}$/);
assert.ok(insp.shapeOf(Object.fromEntries(Array.from({ length: 30 }, (_, i) => [`key${i}_${"x".repeat(80)}`, "v"]))).length <= 1810);
});
test("a path is reported with the names of its query, not what they were set to", () => {
assert.equal(insp.pathForReport(new URL("http://x/api/v3/queue?page=1&pageSize=100&apikey=SECRET")), "/api/v3/queue?page&pageSize&apikey");
assert.equal(insp.pathForReport(new URL("http://x/api/health")), "/api/health");
});
});
describe("where it is empty", () => {
test("null, empty text, empty lists — and a field null in every item of a list", () => {
const e = insp.emptyFields({ version: null, name: "", queue: { total: 0, items: [] }, servers: [{ id: 1, usage: null, name: "a" }, { id: 2, usage: null, name: "b" }], fine: "yes" });
assert.deepEqual(e.map((x) => [x.path, x.what]), [["version", "null"], ["name", "text"], ["queue.items", "list"], ["servers[].usage", "every-item"]]);
});
test("a field that is null in some items only is not reported; numbers such as 0 are not empty", () => {
assert.deepEqual(insp.emptyFields({ servers: [{ usage: null }, { usage: 5 }], count: 0, ok: false }), []);
});
test("a result that is itself empty, and a limit", () => {
assert.deepEqual(insp.emptyFields(null), [{ path: "(the result)", what: "null" }]);
assert.equal(insp.emptyFields(Object.fromEntries(Array.from({ length: 80 }, (_, i) => [`f${i}`, null])), 10).length, 10);
});
});
describe("the requests written down while a read runs", () => {
let http: Server;
let url = "";
before(async () => {
http = createHttpServer((req, res) => {
res.setHeader("content-type", "application/json");
if (req.url?.startsWith("/json")) return void res.end(JSON.stringify({ items: [{ id: 1, secret: "hidden-value" }], total: 1 }));
if (req.url?.startsWith("/html")) return void res.end("<html>nope</html>");
res.statusCode = 404;
res.end("{}");
});
await new Promise<void>((r) => http.listen(0, "127.0.0.1", r));
url = `http://127.0.0.1:${(http.address() as AddressInfo).port}`;
});
after(() => http.close());
test("each request: method, path (no values), status, time, size and the shape of the answer; a failed one too", async () => {
const { calls, value, error } = await insp.inspectCalls(async () => {
await requestJson(`${url}/json?token=hidden&page=2`);
await requestJson(`${url}/html`);
await requestJson(`${url}/missing`);
await requestJson("http://127.0.0.1:1/refused").catch(() => undefined);
return "done";
});
assert.deepEqual([value, error], ["done", null]);
assert.deepEqual(calls.map((c) => [c.method, c.path, c.status]), [["GET", "/json?token&page", 200], ["GET", "/html", 200], ["GET", "/missing", 404], ["GET", "/refused", 0]]);
assert.equal(calls[0].shape, "{ items: array(1) of { id: number, secret: string }, total: number }");
assert.equal(calls[1].shape, null, "not JSON");
assert.ok(calls[0].bytes > 10 && calls[0].ms >= 0);
assert.ok(calls[3].error);
assert.doesNotMatch(JSON.stringify(calls), /hidden-value|hidden/);
});
test("a read that throws is reported with what it asked before it did; and nothing is written down outside an inspection", async () => {
const { calls, value, error } = await insp.inspectCalls(async () => {
await requestJson(`${url}/json`);
throw new Error("the reader gave up");
});
assert.deepEqual([calls.length, value, error], [1, undefined, "the reader gave up"]);
assert.equal(insp.isInspecting(), false);
await requestJson(`${url}/json`);
const second = await insp.inspectCalls(async () => 1);
assert.deepEqual(second.calls, [], "the earlier request was not kept");
});
test("two inspections at once keep their own requests", async () => {
const [a, b] = await Promise.all([insp.inspectCalls(async () => requestJson(`${url}/json?a=1`)), insp.inspectCalls(async () => requestJson(`${url}/html?b=1`))]);
assert.deepEqual([a.calls.map((c) => c.path), b.calls.map((c) => c.path)], [["/json?a"], ["/html?b"]]);
});
});
describe("the route", () => {
let grafana: Server;
let app: Server;
let base = "";
let grafanaId = 0;
let tailscaleId = 0;
let offId = 0;
const call = (sub: string, id: number) => fetch(`${base}/${id}/inspect`, { method: "POST", headers: { "content-type": "application/json", "x-sub": sub } });
before(async () => {
await db.insert(users).values([{ oidcSub: "viewer", name: "Vic", role: "viewer" }, { oidcSub: "admin", name: "Ada", role: "admin" }]);
grafana = createHttpServer((req, res) => {
res.setHeader("content-type", "application/json");
const u = new URL(req.url ?? "", "http://x");
if (u.pathname === "/api/health") return void res.end(JSON.stringify({ database: "ok", version: "11.2.0" }));
if (u.pathname === "/api/prometheus/grafana/api/v1/rules") return void res.end(JSON.stringify({ status: "success", data: { groups: [{ name: "g", file: "f", rules: [{ name: "r", state: "inactive", health: "ok" }] }] } }));
if (u.pathname === "/api/datasources") return void res.end(JSON.stringify([]));
res.statusCode = 404;
res.end("{}");
});
await new Promise<void>((r) => grafana.listen(0, "127.0.0.1", r));
const gurl = `http://127.0.0.1:${(grafana.address() as AddressInfo).port}`;
grafanaId = (await db.insert(integrations).values({ type: "grafana", name: "Dashboards", baseUrl: gurl, config: JSON.stringify({ url: gurl, token: "glsa_x" }) }).returning({ id: integrations.id }))[0].id;
tailscaleId = (await db.insert(integrations).values({ type: "tailscale", name: "Tailnet", baseUrl: "http://x", config: JSON.stringify({}) }).returning({ id: integrations.id }))[0].id;
offId = (await db.insert(integrations).values({ type: "grafana", name: "Off", baseUrl: gurl, enabled: false, config: JSON.stringify({ url: gurl, token: "t" }) }).returning({ id: integrations.id }))[0].id;
const a = express();
a.use(express.json());
a.use((req, _res, next) => {
(req as unknown as { session: unknown }).session = { user: { sub: String(req.headers["x-sub"]) } };
next();
});
a.use("/api/integrations", integrationsRouter);
app = await new Promise<Server>((resolve) => {
const s = a.listen(0, "127.0.0.1", () => resolve(s));
});
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/integrations`;
});
after(() => {
app.close();
grafana.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows keeps the database file locked until the process exits.
}
});
test("an administrator gets what it asked, what came back (as shapes) and where the result is empty; the token is nowhere in it", async () => {
const res = await call("admin", grafanaId);
assert.equal(res.status, 200);
const text = await res.text();
assert.doesNotMatch(text, /glsa_x/);
const body = JSON.parse(text) as { ok: boolean; type: string; calls: { path: string; status: number; shape: string | null }[]; resultShape: string; empty: { path: string; what: string }[] };
assert.deepEqual([body.ok, body.type], [true, "grafana"]);
assert.ok(body.calls.some((c) => c.path === "/api/health" && c.status === 200 && c.shape === "{ database: string, version: string }"));
assert.ok(body.calls.some((c) => c.path === "/api/prometheus/grafana/api/v1/rules"));
assert.match(body.resultShape, /^\{ version: string, rules: \{ total: number, items: array\(0\) \}, datasources: array\(0\) \}$/);
assert.ok(body.empty.some((e) => e.path === "rules.items" && e.what === "list"));
assert.ok(body.empty.some((e) => e.path === "datasources" && e.what === "list"));
});
test("a failed read is reported with what it asked, not as an error of the route", async () => {
await db.update(integrations).set({ config: JSON.stringify({ url: "http://127.0.0.1:1", token: "t" }) }).where(eq(integrations.id, grafanaId));
const body = (await (await call("admin", grafanaId)).json()) as { ok: boolean; error: string; calls: { status: number; error?: string }[]; resultShape: string | null };
assert.deepEqual([body.ok, body.resultShape, body.calls.some((c) => c.status === 0)], [false, null, true]);
assert.ok(body.error);
});
test("only an administrator; a kind with no reader, a switched-off integration and an unknown one are refused; each inspection is in the audit log", async () => {
assert.equal((await call("viewer", grafanaId)).status, 403);
assert.equal((await call("admin", tailscaleId)).status, 400);
assert.equal(((await (await call("admin", tailscaleId)).json()) as { error: string }).error, "not_inspectable");
assert.equal(((await (await call("admin", offId)).json()) as { error: string }).error, "integration_disabled");
assert.equal((await call("admin", 99999)).status, 404);
const entries = (await db.select().from(auditLog)).filter((e) => e.action === "inspect");
assert.equal(entries.length, 2, "the two that ran");
assert.deepEqual(entries.map((e) => [e.category, e.targetType]), [["integration", "integration"], ["integration", "integration"]]);
});
});