A web check can read a value out of a JSON answer (power.now, state, data.result[0].value[1]) and judge it: below, above, equal to, contains, is there. The value read is shown on the Endpoints page, charted under History, exported as homelab_endpoint_value and in the read API. A check can also send one header (a token), stored encrypted, never returned, and not forwarded to another host on a redirect. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
355 lines
21 KiB
TypeScript
355 lines
21 KiB
TypeScript
/**
|
|
* Checking a value in an answer: reading a path out of JSON, judging the value against a limit, asking a local server with and without a header, what is
|
|
* remembered and charted, and the routes that keep a header's value to themselves.
|
|
*
|
|
* 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 IncomingMessage, type Server } from "node:http";
|
|
import { mkdtempSync, rmSync } from "node:fs";
|
|
import { networkInterfaces, tmpdir } from "node:os";
|
|
import { join } from "node:path";
|
|
import type { AddressInfo } from "node:net";
|
|
|
|
const dir = mkdtempSync(join(tmpdir(), "hm-values-"));
|
|
process.env.DATABASE_PATH = join(dir, "test.sqlite");
|
|
process.env.SESSION_DIR = join(dir, "sessions");
|
|
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
|
|
process.env.HEALTH_STARTUP_GRACE_MS = "0";
|
|
|
|
const express = (await import("express")).default;
|
|
const { db } = await import("../src/db/client.js");
|
|
const { users, endpointChecks, endpointResults } = await import("../src/db/schema.js");
|
|
const { runMigrations } = await import("../src/db/migrate.js");
|
|
const value = await import("../src/services/valueCheck.js");
|
|
const { probe, runCheck, bucketValues, getEndpointHistory, endpointConditions } = await import("../src/services/endpointChecks.js");
|
|
const { endpointsRouter } = await import("../src/routes/endpoints.js");
|
|
const { buildMetrics } = await import("../src/services/metrics.js");
|
|
const { endpointsV1 } = await import("../src/services/publicApi.js");
|
|
const { eq } = await import("drizzle-orm");
|
|
|
|
await runMigrations();
|
|
|
|
describe("where a value is", () => {
|
|
test("dots, brackets, quoted names and a leading $", () => {
|
|
assert.deepEqual(value.parsePath("power.now"), ["power", "now"]);
|
|
assert.deepEqual(value.parsePath("data.result[0].value[1]"), ["data", "result", 0, "value", 1]);
|
|
assert.deepEqual(value.parsePath("$.items[2].name"), ["items", 2, "name"]);
|
|
assert.deepEqual(value.parsePath('["a.b"].c'), ["a.b", "c"]);
|
|
assert.deepEqual(value.parsePath("[0].x"), [0, "x"]);
|
|
for (const bad of ["", "a..b", "a.", "a[", "a[x]", "a[]", ".", "$"]) assert.equal(value.parsePath(bad), null, `"${bad}"`);
|
|
});
|
|
|
|
test("it reads what is there, and says how far it got when it isn't", () => {
|
|
const json = { power: { now: 120.5, unit: "W" }, data: { result: [{ value: [1700, "42.5"] }] }, "a.b": { c: true }, nothing: null, list: [] };
|
|
assert.deepEqual(value.readPath(json, "power.now"), { found: true, value: 120.5 });
|
|
assert.deepEqual(value.readPath(json, "data.result[0].value[1]"), { found: true, value: "42.5" });
|
|
assert.deepEqual(value.readPath(json, '["a.b"].c'), { found: true, value: true });
|
|
assert.deepEqual(value.readPath(json, "nothing"), { found: true, value: null }, "null is a value that is there");
|
|
assert.deepEqual(value.readPath(json, "power.later"), { found: false, at: "power.later" });
|
|
assert.deepEqual(value.readPath(json, "data.result[3]"), { found: false, at: "data.result[3]" });
|
|
assert.deepEqual(value.readPath(json, "list[0]"), { found: false, at: "list[0]" });
|
|
assert.deepEqual(value.readPath(json, "power.now.deeper"), { found: false, at: "power.now.deeper" }, "a number has nothing inside it");
|
|
assert.equal(value.readPath(json, "toString").found, false, "nothing is inherited from the language");
|
|
assert.equal(value.readPath([1, 2], "[1]").found, true);
|
|
});
|
|
|
|
test("numbers are numbers, and so is text that is one", () => {
|
|
assert.deepEqual([12, "12.5", " 7 ", "", "abc", null, true, Infinity].map(value.asNumber), [12, 12.5, 7, null, null, null, null, null]);
|
|
});
|
|
});
|
|
|
|
describe("whether a value is fine", () => {
|
|
const read = (v: unknown) => ({ found: true as const, value: v });
|
|
const j = (v: unknown, op: (typeof value.VALUE_OPS)[number], expected: string | null, unit: string | null = null) => value.judgeValue(read(v), "p", op, expected, unit);
|
|
|
|
test("below, above and the edges", () => {
|
|
assert.equal(j(4999, "<", "5000").ok, true);
|
|
assert.equal(j(5000, "<", "5000").ok, false);
|
|
assert.equal(j(5000, "<=", "5000").ok, true);
|
|
assert.equal(j(5000, ">", "5000").ok, false);
|
|
assert.equal(j(5000, ">=", "5000").ok, true);
|
|
assert.equal(j("42.5", "<", "50").ok, true, "a number given as text, as Prometheus does");
|
|
});
|
|
|
|
test("equal and not equal compare numbers as numbers and anything else as the same text", () => {
|
|
assert.equal(j(5, "=", "5.0").ok, true);
|
|
assert.equal(j("5", "=", "5").ok, true);
|
|
assert.equal(j("playing", "=", "playing").ok, true);
|
|
assert.equal(j("Playing", "=", "playing").ok, false, "case matters");
|
|
assert.equal(j("idle", "!=", "error").ok, true);
|
|
assert.equal(j("error", "!=", "error").ok, false);
|
|
assert.equal(j(true, "=", "true").ok, true);
|
|
});
|
|
|
|
test("contains, and exists (being there is enough, even a null)", () => {
|
|
assert.equal(j("all systems go", "contains", "systems").ok, true);
|
|
assert.equal(j("all systems go", "contains", "fault").ok, false);
|
|
assert.equal(j(null, "exists", null).ok, true);
|
|
assert.equal(value.judgeValue({ found: false, at: "x.y" }, "x.y.z", "exists", null, null).ok, false);
|
|
});
|
|
|
|
test("it says what it found and what it wanted, with the unit when the value is a number", () => {
|
|
assert.equal(j(5200, "<", "5000", "W").message, "p is 5200 W, but should be below 5000 W");
|
|
assert.equal(j(120, "<", "5000", "W").message, "p is 120 W (should be below 5000 W)");
|
|
assert.equal(j("error", "=", "playing").message, "p is error, but should be equal to “playing”");
|
|
assert.equal(j("x", "=", "playing", "W").message, "p is x, but should be equal to “playing”", "no unit on text");
|
|
assert.match(j("hot", "<", "50").message, /“hot”, which isn't a number/);
|
|
assert.match(value.judgeValue({ found: false, at: "data" }, "data.x", "<", "5", null).message, /no “data.x” in the answer \(it stops at data\)/);
|
|
const long = j("x".repeat(500), "contains", "y");
|
|
assert.ok(long.shown.length <= 120 && long.shown.endsWith("…"), "what is kept is short");
|
|
assert.equal(j({ a: 1 }, "contains", "a").shown, '{"a":1}', "an object is shown as JSON");
|
|
});
|
|
|
|
test("a saved setting is refused when it doesn't make sense, with the reason", () => {
|
|
assert.equal(value.valueProblem(null, null, null), null, "no value check at all is fine");
|
|
assert.match(value.valueProblem(null, ">", "5")!, /where in the answer/);
|
|
assert.match(value.valueProblem("a..b", ">", "5")!, /path I can read/);
|
|
assert.match(value.valueProblem("a", null, "5")!, /how the value should compare/);
|
|
assert.match(value.valueProblem("a", ">", null)!, /compare it with/);
|
|
assert.match(value.valueProblem("a", ">", "lots")!, /has to be a number/);
|
|
assert.equal(value.valueProblem("a", "=", "playing"), null);
|
|
assert.equal(value.valueProblem("a", "exists", null), null, "exists needs nothing to compare with");
|
|
});
|
|
});
|
|
|
|
describe("the values over time", () => {
|
|
test("readings fall into slices as their average with the lowest and highest, and nothing outside the stretch", () => {
|
|
const H = 3_600_000;
|
|
const pts = bucketValues([{ t: 0, v: 10 }, { t: H, v: 20 }, { t: 2 * H, v: 30 }, { t: 3 * H, v: 50 }, { t: 99 * H, v: 999 }], 0, 4 * H, 2);
|
|
assert.deepEqual(pts.map((p) => [p.v, p.lo, p.hi]), [[15, 10, 20], [40, 30, 50]]);
|
|
assert.deepEqual(bucketValues([], 0, 10, 5), []);
|
|
});
|
|
});
|
|
|
|
/** An address of this machine that isn't loopback (the checks refuse that), if it has one. */
|
|
function lanAddress(): string | null {
|
|
for (const list of Object.values(networkInterfaces())) {
|
|
for (const i of list ?? []) if (i.family === "IPv4" && !i.internal && !i.address.startsWith("169.254.")) return i.address;
|
|
}
|
|
return null;
|
|
}
|
|
const LAN = lanAddress();
|
|
|
|
describe("asking for a value", { skip: LAN === null && "this machine has no address other than loopback" }, () => {
|
|
let web: Server;
|
|
let other: Server;
|
|
let port = 0;
|
|
let otherPort = 0;
|
|
let app: Server;
|
|
let base = "";
|
|
let who = "admin";
|
|
const seen: { url: string; auth: string | undefined }[] = [];
|
|
let power = 120;
|
|
|
|
before(async () => {
|
|
await db.insert(users).values([
|
|
{ oidcSub: "admin", name: "Ada", role: "admin" },
|
|
{ oidcSub: "viewer", name: "Vic", role: "viewer" },
|
|
]);
|
|
web = createHttpServer((req: IncomingMessage, res) => {
|
|
seen.push({ url: req.url ?? "", auth: req.headers.authorization });
|
|
const json = (o: unknown) => {
|
|
res.setHeader("content-type", "application/json");
|
|
res.end(JSON.stringify(o));
|
|
};
|
|
if (req.url === "/power") return json({ power: { now: power }, state: "playing", data: { result: [{ value: [1700000000, "42.5"] }] } });
|
|
if (req.url === "/secure") {
|
|
if (req.headers.authorization !== "Bearer s3cret") {
|
|
res.statusCode = 401;
|
|
return void res.end("no");
|
|
}
|
|
return json({ ok: 1 });
|
|
}
|
|
if (req.url === "/html") return void res.end("<h1>hello</h1>");
|
|
if (req.url === "/big") return void res.end(`{"x":"${"y".repeat(100_000)}"}`);
|
|
if (req.url === "/hop") {
|
|
res.statusCode = 302;
|
|
res.setHeader("location", `http://${LAN}:${otherPort}/power`);
|
|
return void res.end();
|
|
}
|
|
res.statusCode = 404;
|
|
res.end("no");
|
|
});
|
|
await new Promise<void>((r) => web.listen(0, "0.0.0.0", r));
|
|
port = (web.address() as AddressInfo).port;
|
|
other = createHttpServer((req, res) => {
|
|
seen.push({ url: `other${req.url}`, auth: req.headers.authorization });
|
|
res.setHeader("content-type", "application/json");
|
|
res.end(JSON.stringify({ power: { now: 1 } }));
|
|
});
|
|
await new Promise<void>((r) => other.listen(0, "0.0.0.0", r));
|
|
otherPort = (other.address() as AddressInfo).port;
|
|
|
|
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/endpoints", endpointsRouter);
|
|
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/endpoints`;
|
|
});
|
|
|
|
after(() => {
|
|
web.close();
|
|
other.close();
|
|
app.close();
|
|
try {
|
|
rmSync(dir, { recursive: true, force: true });
|
|
} catch {
|
|
// Windows keeps the database file locked until the process exits.
|
|
}
|
|
});
|
|
|
|
type Row = typeof endpointChecks.$inferSelect;
|
|
const check = (path: string, extra: Partial<Row> = {}): Row =>
|
|
({
|
|
id: 1, name: "Meter", kind: "http", target: `http://${LAN}:${port}${path}`, port: null, expectStatus: null, keyword: null, valuePath: null, valueOp: null, valueExpected: null, valueUnit: null, headerName: null, headerValue: null, lastValue: null,
|
|
insecure: false, intervalMinutes: 5, timeoutSeconds: 3, failuresBeforeAlert: 2, warnDays: 14, serverId: null, enabled: true, lastCheckedAt: null, lastOk: null, lastMessage: null, lastResponseMs: null, certExpiresAt: null, consecutiveFailures: 0, lastChangeAt: null,
|
|
createdAt: "2026-10-01 00:00:00", ...extra,
|
|
}) as Row;
|
|
|
|
test("a value under its limit is fine, over it is not, and either way what was read comes back", async () => {
|
|
const fine = await probe(check("/power", { valuePath: "power.now", valueOp: "<", valueExpected: "5000", valueUnit: "W" }));
|
|
assert.deepEqual([fine.ok, fine.value, fine.valueNumber], [true, "120", 120]);
|
|
assert.equal(fine.message, "power.now is 120 W (should be below 5000 W)");
|
|
const over = await probe(check("/power", { valuePath: "power.now", valueOp: "<", valueExpected: "100", valueUnit: "W" }));
|
|
assert.deepEqual([over.ok, over.value], [false, "120"]);
|
|
assert.equal(over.message, "power.now is 120 W, but should be below 100 W");
|
|
assert.ok(over.ms !== null, "it did answer");
|
|
});
|
|
|
|
test("text, and a number a query gives as text", async () => {
|
|
assert.equal((await probe(check("/power", { valuePath: "state", valueOp: "=", valueExpected: "playing" }))).ok, true);
|
|
const bad = await probe(check("/power", { valuePath: "state", valueOp: "=", valueExpected: "paused" }));
|
|
assert.deepEqual([bad.ok, bad.valueNumber], [false, null]);
|
|
const prom = await probe(check("/power", { valuePath: "data.result[0].value[1]", valueOp: ">", valueExpected: "40" }));
|
|
assert.deepEqual([prom.ok, prom.valueNumber], [true, 42.5]);
|
|
});
|
|
|
|
test("an answer that isn't JSON, a value that isn't there and a path that goes nowhere each say so", async () => {
|
|
assert.match((await probe(check("/html", { valuePath: "a", valueOp: "exists" }))).message, /isn't JSON/);
|
|
assert.match((await probe(check("/power", { valuePath: "power.gone", valueOp: "exists" }))).message, /no “power.gone” in the answer \(it stops at power.gone\)/);
|
|
assert.match((await probe(check("/big", { valuePath: "x", valueOp: "exists" }))).message, /more than 64 KB/);
|
|
const wrongStatus = await probe(check("/nope", { valuePath: "a", valueOp: "exists" }));
|
|
assert.match(wrongStatus.message, /answered 404/, "the status is judged before the value");
|
|
});
|
|
|
|
test("a header goes with the request, and its value is read back from the sealed form", async () => {
|
|
const { sealSecret } = await import("../src/services/sealed.js");
|
|
seen.length = 0;
|
|
const ok = await probe(check("/secure", { headerName: "Authorization", headerValue: sealSecret("Bearer s3cret") }));
|
|
assert.equal(ok.ok, true);
|
|
assert.equal(seen[0].auth, "Bearer s3cret");
|
|
assert.equal((await probe(check("/secure"))).ok, false, "without it the service says no");
|
|
const lost = await probe(check("/secure", { headerName: "Authorization", headerValue: "enc:v1:not-decryptable" }));
|
|
assert.match(lost.message, /can't be read — enter it again/);
|
|
});
|
|
|
|
test("the header is not sent on to another host a redirect leads to", async () => {
|
|
const { sealSecret } = await import("../src/services/sealed.js");
|
|
seen.length = 0;
|
|
const r = await probe(check("/hop", { valuePath: "power.now", valueOp: "<", valueExpected: "5", headerName: "Authorization", headerValue: sealSecret("Bearer s3cret") }));
|
|
assert.equal(r.ok, true, "the redirect is followed to read the value");
|
|
assert.deepEqual(seen.map((s) => [s.url, s.auth]), [["/hop", "Bearer s3cret"], ["other/power", undefined]]);
|
|
});
|
|
|
|
test("a run remembers the value on the check and with the result; one that can't reach it keeps the last it read", async () => {
|
|
const [row] = await db.insert(endpointChecks).values({ name: "Meter", kind: "http", target: `http://${LAN}:${port}/power`, valuePath: "power.now", valueOp: "<", valueExpected: "5000", valueUnit: "W" }).returning();
|
|
await runCheck(row, new Date("2026-10-18T10:00:00Z"));
|
|
let [after1] = await db.select().from(endpointChecks).where(eq(endpointChecks.id, row.id));
|
|
assert.deepEqual([after1.lastOk, after1.lastValue], [true, "120"]);
|
|
power = 160;
|
|
await runCheck(after1, new Date("2026-10-18T10:05:00Z"));
|
|
const results = await db.select().from(endpointResults).where(eq(endpointResults.checkId, row.id)).orderBy(endpointResults.at);
|
|
assert.deepEqual(results.map((r) => r.value), [120, 160]);
|
|
[after1] = await db.select().from(endpointChecks).where(eq(endpointChecks.id, row.id));
|
|
await db.update(endpointChecks).set({ target: `http://${LAN}:1/never` }).where(eq(endpointChecks.id, row.id));
|
|
const [gone] = await db.select().from(endpointChecks).where(eq(endpointChecks.id, row.id));
|
|
await runCheck(gone, new Date("2026-10-18T10:10:00Z"));
|
|
const [kept] = await db.select().from(endpointChecks).where(eq(endpointChecks.id, row.id));
|
|
assert.deepEqual([kept.lastOk, kept.lastValue], [false, "160"]);
|
|
power = 120;
|
|
});
|
|
|
|
test("a value that is off is an alert that says what is wrong with it, not that it isn't answering", async () => {
|
|
const list = endpointConditions([check("/power", { valuePath: "power.now", valueOp: "<", valueExpected: "100", lastOk: false, consecutiveFailures: 2, lastMessage: "power.now is 120, but should be below 100" }), check("/power", { id: 2, lastOk: false, consecutiveFailures: 2, lastMessage: "answered 500" })], new Date());
|
|
assert.equal(list[0].message, "Meter — power.now is 120, but should be below 100");
|
|
assert.equal(list[1].message, "Meter isn't answering — answered 500");
|
|
});
|
|
|
|
test("the history carries the values, charted as far back as the results are kept", async () => {
|
|
const [row] = await db.select().from(endpointChecks).where(eq(endpointChecks.valuePath, "power.now"));
|
|
const h = await getEndpointHistory(row.id, 7, new Date("2026-10-18T12:00:00Z"));
|
|
assert.ok(h.values);
|
|
assert.deepEqual([h.values.unit, h.values.latest, h.values.lowest, h.values.highest], ["W", 160, 120, 160]);
|
|
assert.equal(h.values.days, 7);
|
|
assert.ok(h.values.points.length >= 1);
|
|
const plain = await db.insert(endpointChecks).values({ name: "Plain", kind: "http", target: "https://x/" }).returning();
|
|
assert.equal((await getEndpointHistory(plain[0].id, 7)).values, null, "a check that reads no value has none");
|
|
});
|
|
|
|
test("/metrics and the read API carry it", async () => {
|
|
const text = await buildMetrics();
|
|
assert.match(text, /homelab_endpoint_value\{[^}]*name="Meter"[^}]*\} 160/);
|
|
const [api] = (await endpointsV1()).filter((e) => e.name === "Meter");
|
|
assert.deepEqual(api.value, { path: "power.now", operator: "<", expected: "5000", unit: "W", last: "160" });
|
|
});
|
|
|
|
const send = (method: string, path: string, body?: unknown) => fetch(`${base}${path}`, { method, headers: { "content-type": "application/json", connection: "close" }, body: body === undefined ? undefined : JSON.stringify(body) });
|
|
|
|
test("a value check is made over the API; a wrong one is refused with the reason; the header's value never comes back", async () => {
|
|
const good = { name: "Solar", kind: "http", target: "https://inverter.lan/status", valuePath: "pv.power", valueOp: ">", valueExpected: "10", valueUnit: "W", headerName: "Authorization", headerValue: "Bearer topsecret" };
|
|
const res = await send("POST", "/", good);
|
|
assert.equal(res.status, 201);
|
|
const created = (await res.json()).check;
|
|
assert.deepEqual([created.valuePath, created.valueOp, created.valueExpected, created.headerName, created.hasHeader], ["pv.power", ">", "10", "Authorization", true]);
|
|
assert.equal(JSON.stringify(created).includes("topsecret"), false);
|
|
assert.equal(JSON.stringify(created).includes("headerValue"), false);
|
|
const [stored] = await db.select().from(endpointChecks).where(eq(endpointChecks.id, created.id));
|
|
assert.ok(stored.headerValue && !stored.headerValue.includes("topsecret"), "stored sealed");
|
|
|
|
const list = (await (await send("GET", "/")).json()) as { checks: Record<string, unknown>[] };
|
|
assert.equal(JSON.stringify(list).includes("topsecret"), false);
|
|
assert.ok(list.checks.every((c) => !("headerValue" in c)));
|
|
|
|
for (const bad of [
|
|
{ ...good, valuePath: "a..b" },
|
|
{ ...good, valuePath: null },
|
|
{ ...good, valueOp: "~" },
|
|
{ ...good, valueExpected: "lots" },
|
|
{ ...good, valueExpected: null },
|
|
{ ...good, headerName: "Bad Name" },
|
|
{ ...good, headerName: "Host" },
|
|
{ name: "x", kind: "http", target: "https://a/", headerName: "Authorization" },
|
|
]) assert.equal((await send("POST", "/", bad)).status, 400, JSON.stringify(bad));
|
|
who = "viewer";
|
|
assert.equal((await send("POST", "/", good)).status, 403);
|
|
who = "admin";
|
|
});
|
|
|
|
test("editing keeps the header's value unless a new one is given, and clearing the name removes it; changing what is asked forgets what was read", async () => {
|
|
const [c] = await db.select().from(endpointChecks).where(eq(endpointChecks.name, "Solar"));
|
|
await db.update(endpointChecks).set({ lastValue: "55", lastOk: true }).where(eq(endpointChecks.id, c.id));
|
|
const same = { name: "Solar", kind: "http", target: "https://inverter.lan/status", valuePath: "pv.power", valueOp: ">", valueExpected: "10", valueUnit: "W", headerName: "Authorization" };
|
|
assert.equal((await send("PUT", `/${c.id}`, same)).status, 200);
|
|
let [now] = await db.select().from(endpointChecks).where(eq(endpointChecks.id, c.id));
|
|
assert.equal(now.headerValue, c.headerValue, "kept");
|
|
assert.equal(now.lastValue, "55", "nothing that matters changed, so what was read stands");
|
|
await send("PUT", `/${c.id}`, { ...same, valueExpected: "20" });
|
|
[now] = await db.select().from(endpointChecks).where(eq(endpointChecks.id, c.id));
|
|
assert.deepEqual([now.lastValue, now.lastOk], [null, null]);
|
|
await send("PUT", `/${c.id}`, { ...same, headerValue: "Bearer another" });
|
|
const [replaced] = await db.select().from(endpointChecks).where(eq(endpointChecks.id, c.id));
|
|
assert.notEqual(replaced.headerValue, c.headerValue);
|
|
await send("PUT", `/${c.id}`, { ...same, headerName: null, valuePath: null, valueOp: null, valueExpected: null });
|
|
const [cleared] = await db.select().from(endpointChecks).where(eq(endpointChecks.id, c.id));
|
|
assert.deepEqual([cleared.headerName, cleared.headerValue, cleared.valuePath, cleared.valueOp], [null, null, null, null]);
|
|
});
|
|
});
|