Files
Homelab-manager/server/test/endpointSuggestions.test.ts
T
bobbanandClaude Sonnet 5.5 4e0c6927b2 Heartbeats, Coming up and suggested checks; Operations menu tidied
Heartbeats: a cron job or script calls /api/heartbeat/<token> (and /start, /fail); the app
alerts when the call is late or the job says it failed. Coming up: one agenda of everything
dated (expiries, warranties, end of support, planned and recurring maintenance, restore tests,
waiting updates), with a dashboard card and an iCalendar feed behind a share link. Suggested
checks: web ports and certificates the app already knows about, added with a click.

Menu: Incidents become Alerts -> History (old /incidents links redirect); new Monitoring group
(Endpoints, Heartbeats, Uptime Kuma); osTicket under Automation, Admin Links under
Infrastructure, Generator under Administration. Also makes the restore-test metrics test follow
the real clock.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-19 21:42:34 +02:00

177 lines
11 KiB
TypeScript

/**
* Suggested endpoint checks: what is offered from servers' open web ports, DNS names and secrets, what is left out, and the routes that add or dismiss them.
*
* Run with: npm test --workspace server
*/
import { test, describe, before, after } from "node:test";
import assert from "node:assert/strict";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { AddressInfo } from "node:net";
import type { Server } from "node:http";
const dir = mkdtempSync(join(tmpdir(), "hm-suggest-"));
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, servers, secrets, dnsProviders, dnsRecordsCache, endpointChecks } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const { suggestChecks } = await import("../src/services/endpointSuggestions.js");
const { endpointsRouter } = await import("../src/routes/endpoints.js");
const { eq } = await import("drizzle-orm");
await runMigrations();
const nas = { id: 1, name: "nas", hostname: "nas.lan", ips: ["10.0.0.5"], ports: [{ protocol: "tcp", port: 443, address: "0.0.0.0" }, { protocol: "tcp", port: 22, address: "0.0.0.0" }] };
const input = (extra: Partial<Parameters<typeof suggestChecks>[0]> = {}) => ({ servers: [nas], dns: [], secrets: [], existing: [], dismissed: new Set<string>(), ...extra });
describe("what is offered", () => {
test("a web port a server listens on, by the name DNS gives it, linked to the server", () => {
const { suggestions } = suggestChecks(input({ dns: [{ name: "git.example.lan", type: "A", content: "10.0.0.5" }, { name: "other.example.lan", type: "A", content: "10.0.0.9" }] }));
assert.deepEqual(suggestions.map((s) => [s.kind, s.target, s.name, s.serverId, s.serverName]), [["http", "https://git.example.lan/", "git.example.lan", 1, "nas"]]);
assert.match(suggestions[0].reason, /nas is listening on port 443, and git\.example\.lan points at it in DNS/);
});
test("an alias to one of those names, or to the server's own hostname, is offered too; wildcards, reverse names and short names are not", () => {
const { suggestions } = suggestChecks(
input({
dns: [
{ name: "git.example.lan", type: "A", content: "10.0.0.5" },
{ name: "code.example.lan", type: "CNAME", content: "git.example.lan." },
{ name: "files.example.lan", type: "CNAME", content: "nas.lan" },
{ name: "*.example.lan", type: "A", content: "10.0.0.5" },
{ name: "5.0.0.10.in-addr.arpa", type: "A", content: "10.0.0.5" },
{ name: "nas", type: "A", content: "10.0.0.5" },
{ name: "unrelated.example.lan", type: "CNAME", content: "elsewhere.lan" },
],
}),
);
assert.deepEqual(suggestions.map((s) => s.target), ["https://code.example.lan/", "https://files.example.lan/", "https://git.example.lan/"]);
});
test("with no DNS name the server's own hostname or its address is used; with neither, nothing", () => {
assert.deepEqual(suggestChecks(input()).suggestions.map((s) => s.target), ["https://nas.lan/"]);
const bare = { ...nas, hostname: "nas", ips: ["169.254.1.1", "10.0.0.5"] };
assert.deepEqual(suggestChecks(input({ servers: [bare] })).suggestions.map((s) => s.target), ["https://10.0.0.5/"]);
assert.deepEqual(suggestChecks(input({ servers: [{ ...bare, ips: [] }] })).suggestions, []);
});
test("only web ports count, only for TCP, and a port that is open on this machine alone does not", () => {
const odd = { ...nas, ports: [{ protocol: "udp", port: 443, address: "0.0.0.0" }, { protocol: "tcp", port: 22, address: "0.0.0.0" }, { protocol: "tcp", port: 8443, address: "127.0.0.1" }, { protocol: "tcp", port: 3000, address: "0.0.0.0" }] };
assert.deepEqual(suggestChecks(input({ servers: [odd] })).suggestions, []);
const mixed = { ...nas, ports: [{ protocol: "tcp", port: 8080, address: "127.0.0.1" }, { protocol: "tcp", port: 8080, address: "10.0.0.5" }] };
assert.deepEqual(suggestChecks(input({ servers: [mixed] })).suggestions.map((s) => s.target), ["http://nas.lan:8080/"], "one socket on a real address is enough, and a port that is not the default is in the address");
});
test("plain and secure on the same server: the secure one is offered, since it reads the certificate and the plain one is most likely its redirect", () => {
const both = { ...nas, ports: [{ protocol: "tcp", port: 80, address: "::" }, { protocol: "tcp", port: 443, address: "::" }, { protocol: "tcp", port: 8080, address: "::" }] };
assert.deepEqual(suggestChecks(input({ servers: [both] })).suggestions.map((s) => s.target), ["http://nas.lan:8080/", "https://nas.lan/"]);
});
test("a secret that already reads a certificate is offered as a certificate check", () => {
const { suggestions } = suggestChecks(input({ servers: [], secrets: [{ name: "Wildcard cert", checkHost: "Git.Example.lan.", checkPort: 443 }, { name: "Typed in", checkHost: null, checkPort: null }] }));
assert.deepEqual(suggestions.map((s) => [s.kind, s.target, s.port, s.name, s.serverId]), [["tls", "git.example.lan", 443, "Certificate: Wildcard cert", null]]);
});
});
describe("what is left out", () => {
const dns = [{ name: "git.example.lan", type: "A", content: "10.0.0.5" }];
test("what a check already covers, however its address is written", () => {
assert.equal(suggestChecks(input({ dns, existing: [{ kind: "http", target: "https://Git.example.lan:443/login", port: null }] })).suggestions.length, 0);
assert.equal(suggestChecks(input({ dns, existing: [{ kind: "http", target: "https://git.example.lan", port: null }] })).suggestions.length, 0);
assert.equal(suggestChecks(input({ dns, existing: [{ kind: "http", target: "http://git.example.lan/", port: null }] })).suggestions.length, 1, "a plain-http check does not cover the secure port");
assert.equal(suggestChecks(input({ dns, existing: [{ kind: "tcp", target: "git.example.lan", port: 443 }] })).suggestions.length, 1, "nor does a port check, which doesn't speak to the page");
});
test("a secret's certificate is covered by a certificate check, or by a web check on https that reads it anyway", () => {
const sec = [{ name: "Cert", checkHost: "git.example.lan", checkPort: 443 }];
assert.equal(suggestChecks(input({ servers: [], secrets: sec, existing: [{ kind: "tls", target: "git.example.lan", port: 443 }] })).suggestions.length, 0);
assert.equal(suggestChecks(input({ servers: [], secrets: sec, existing: [{ kind: "http", target: "https://git.example.lan/", port: null }] })).suggestions.length, 0);
assert.equal(suggestChecks(input({ servers: [], secrets: sec, existing: [{ kind: "tls", target: "git.example.lan", port: 8443 }] })).suggestions.length, 1);
});
test("what was dismissed is listed apart, not offered", () => {
const r = suggestChecks(input({ dns, dismissed: new Set(["http|https://git.example.lan/"]) }));
assert.deepEqual([r.suggestions.length, r.dismissed.map((d) => d.target)], [0, ["https://git.example.lan/"]]);
});
});
describe("the routes", () => {
let app: Server;
let base = "";
let who = "admin";
before(async () => {
await db.insert(users).values([
{ oidcSub: "admin", name: "Ada", role: "admin" },
{ oidcSub: "operator", name: "Olga", role: "operator" },
]);
const [s] = await db
.insert(servers)
.values({ name: "nas", hostname: "nas.lan", apiTokenHash: "n", apiTokenPrefix: "n", ipAddresses: JSON.stringify(["10.0.0.5"]), listeningPorts: JSON.stringify([{ protocol: "tcp", port: 443, address: "0.0.0.0", process: "nginx" }, { protocol: "tcp", port: 8080, address: "0.0.0.0" }]) })
.returning({ id: servers.id });
const [p] = await db.insert(dnsProviders).values({ providerType: "pihole", name: "Pi-hole" }).returning({ id: dnsProviders.id });
await db.insert(dnsRecordsCache).values({ providerId: p.id, zoneId: "z", recordId: "r1", type: "A", name: "git.example.lan", content: "10.0.0.5" });
await db.insert(secrets).values({ name: "Mail cert", type: "ssl_certificate", checkHost: "mail.example.lan", checkPort: 443 } as never);
void s;
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 x = a.listen(0, "127.0.0.1", () => resolve(x));
});
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/endpoints`;
});
after(() => {
app.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows keeps the database file locked until the process exits.
}
});
const send = (method: string, path: string, body?: unknown) => fetch(`${base}${path}`, { method, headers: { "content-type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
test("administrators see what is offered, and nobody else", async () => {
who = "operator";
assert.equal((await send("GET", "/suggestions")).status, 403);
assert.equal((await send("POST", "/suggestions/add", { keys: ["x"] })).status, 403);
who = "admin";
const body = await (await send("GET", "/suggestions")).json();
assert.deepEqual(body.suggestions.map((s: { target: string }) => s.target), ["http://git.example.lan:8080/", "https://git.example.lan/", "mail.example.lan"]);
});
test("adding makes the checks the server itself offered — a key that was not offered adds nothing — linked to their server, and they stop being offered", async () => {
const res = await send("POST", "/suggestions/add", { keys: ["https://git.example.lan/", "http|https://git.example.lan/", "http|http://evil.example/", "http|https://git.example.lan/"] });
assert.equal(res.status, 201);
assert.equal((await res.json()).added.length, 1);
const [made] = await db.select().from(endpointChecks).where(eq(endpointChecks.target, "https://git.example.lan/"));
assert.deepEqual([made.kind, made.name, made.serverId !== null, made.intervalMinutes, made.enabled], ["http", "git.example.lan", true, 5, true]);
const body = await (await send("GET", "/suggestions")).json();
assert.equal(body.suggestions.some((s: { target: string }) => s.target === "https://git.example.lan/"), false);
assert.equal((await send("POST", "/suggestions/add", { keys: [] })).status, 400);
});
test("dismissing takes one out of the offer, and restoring brings every dismissed one back", async () => {
let body = await (await send("POST", "/suggestions/dismiss", { keys: ["tls|mail.example.lan|443"] })).json();
assert.equal(body.suggestions.some((s: { kind: string }) => s.kind === "tls"), false);
assert.equal(body.dismissed.length, 1);
body = await (await send("POST", "/suggestions/restore")).json();
assert.equal(body.suggestions.some((s: { kind: string }) => s.kind === "tls"), true);
assert.equal(body.dismissed.length, 0);
});
});