Files
Homelab-manager/server/test/inspector.test.ts
T
bobbanandClaude Sonnet 5.5 386d77b351 Inspect for n8n and Home Assistant
Both read through the shared HTTP helper but were missing from the web list of inspectable kinds, so no Inspect button showed. Home Assistant's reader was named listEntities, which the inspect route doesn't recognise; it now also answers to read. Test and INTEGRATIONS.md updated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-17 18:27:04 +01:00

235 lines
14 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, readFileSync, 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"]]);
});
test("n8n and Home Assistant can be inspected too, and the web page offers the button for both", async () => {
const other = createHttpServer((req, res) => {
res.setHeader("content-type", "application/json");
const u = new URL(req.url ?? "", "http://x");
if (u.pathname === "/api/v1/workflows") return void res.end(JSON.stringify({ data: [{ id: "1", name: "Backup", active: true }], nextCursor: null }));
if (u.pathname === "/api/v1/executions") return void res.end(JSON.stringify({ data: [{ workflowId: "1", status: "success", stoppedAt: "2026-01-01T00:00:00Z" }] }));
if (u.pathname === "/api/states") return void res.end(JSON.stringify([{ entity_id: "sensor.t", state: "21.5", attributes: { friendly_name: "Temp", unit_of_measurement: "°C" }, last_changed: "2026-01-01T00:00:00Z" }]));
res.statusCode = 404;
res.end("{}");
});
await new Promise<void>((r) => other.listen(0, "127.0.0.1", r));
try {
const url = `http://127.0.0.1:${(other.address() as AddressInfo).port}`;
const n8nId = (await db.insert(integrations).values({ type: "n8n", name: "Flows", baseUrl: url, config: JSON.stringify({ url, apiKey: "n8n_secret" }) }).returning({ id: integrations.id }))[0].id;
const haId = (await db.insert(integrations).values({ type: "homeassistant", name: "Home", baseUrl: url, config: JSON.stringify({ url, token: "ha_secret" }) }).returning({ id: integrations.id }))[0].id;
for (const [id, path] of [[n8nId, "/api/v1/workflows"], [haId, "/api/states"]] as const) {
const text = await (await call("admin", id)).text();
assert.doesNotMatch(text, /n8n_secret|ha_secret/);
const body = JSON.parse(text) as { ok: boolean; calls: { path: string; status: number }[] };
assert.equal(body.ok, true, text);
assert.ok(body.calls.some((c) => c.path.startsWith(path) && c.status === 200), path);
}
} finally {
other.close();
}
const types = readFileSync(new URL("../../web/src/utils/integrationTypes.ts", import.meta.url), "utf8");
const list = types.match(/INSPECTABLE[^=]*=\s*\[([^\]]*)\]/)?.[1] ?? "";
for (const kind of ["n8n", "homeassistant"]) assert.ok(list.includes(`"${kind}"`), kind);
});
});