Files
Homelab-manager/server/test/newPorts.test.ts
T
bobbanandClaude Sonnet 5.5 c79b2eda0d Show new ports across every server on the Ports page, and mark them as expected there
A New badge, a notice with Show only new and Mark all as expected, and Mark as expected on each row. Uses the same rule as the alert and the server's Ports card.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-03 23:54:11 +01:00

212 lines
12 KiB
TypeScript

/**
* New ports: what counts as one, that the first report is the baseline, and what the health check, the Alerts page, maintenance, routing and
* the server's Ports card do with 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-newports-"));
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, serverPorts } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const { newListeningPorts, baselineFrom, parseBaseline, newPortMessage } = await import("../src/services/newPorts.js");
const { evaluateHealth, collectSnapshot } = await import("../src/services/healthMonitor.js");
const { syncServerTasks } = await import("../src/services/taskSync.js");
const { getAlerts, invalidateAlertsCache } = await import("../src/services/alerts.js");
const { startOrExtendWindow } = await import("../src/services/maintenance.js");
const { metaOfConditionKey } = await import("../src/services/notifyRouting.js");
const { subjectOfConditionKey } = await import("../src/services/maintenance.js");
const { serverPortsRouter } = await import("../src/routes/serverPorts.js");
const { portsRouter } = await import("../src/routes/ports.js");
const { updateSettings } = await import("../src/services/settingsStore.js");
const { eq } = await import("drizzle-orm");
await runMigrations();
const sock = (port: number, extra: Partial<{ protocol: "tcp" | "udp"; address: string; process: string }> = {}) => ({ protocol: "tcp" as const, port, address: "0.0.0.0", ...extra });
const none = new Set<string>();
describe("what counts as a new port", () => {
const baseline = parseBaseline(baselineFrom([sock(22), sock(443), sock(53, { protocol: "udp" })]));
test("the baseline is everything the first report listened on, in any protocol", () => {
assert.deepEqual([...baseline!].sort(), ["tcp:22", "tcp:443", "udp:53"]);
assert.equal(parseBaseline(null), null);
assert.equal(parseBaseline("not json"), null);
assert.equal(parseBaseline(JSON.stringify({ not: "a list" })), null);
});
test("with no baseline yet, nothing is new", () => {
assert.deepEqual(newListeningPorts([sock(8080)], null, none), []);
assert.deepEqual(newListeningPorts(null, baseline, none), []);
});
test("a TCP port that is listening and was not in the baseline is new, with what is listening on it", () => {
const found = newListeningPorts([sock(22), sock(8080, { process: "node" }), sock(8080, { address: "::", process: "" }), sock(3000)], baseline, none);
assert.deepEqual(found, [{ protocol: "tcp", port: 3000, process: null }, { protocol: "tcp", port: 8080, process: "node" }]);
});
test("not UDP, not the dynamic range, not a port bound to this machine alone", () => {
const found = newListeningPorts([sock(5353, { protocol: "udp" }), sock(49152), sock(60000), sock(9000, { address: "127.0.0.1" }), sock(9001, { address: "::1" }), sock(9002, { address: "[::1]" }), sock(9003, { address: "127.0.0.1" }), sock(9003, { address: "10.0.0.5" })], baseline, none);
assert.deepEqual(found.map((p) => p.port), [9003], "one socket on a real address is enough");
assert.deepEqual(newListeningPorts([sock(49151)], baseline, none).map((p) => p.port), [49151], "the last port before the dynamic range is still a service");
});
test("a port somebody noted as expected is not new", () => {
assert.deepEqual(newListeningPorts([sock(8080), sock(9090)], baseline, new Set(["tcp:8080"])).map((p) => p.port), [9090]);
});
test("the message says what it is and what to do", () => {
assert.equal(newPortMessage("nas", { protocol: "tcp", port: 8080, process: "node" }), "nas: a new port is listening — 8080/tcp (node). If it should be there, note it on the server's Ports card.");
});
});
describe("the health check, the alert and the routing", () => {
const snap = (extra: object) => ({ servers: [{ id: 3, name: "nas", lastSeenAt: new Date().toISOString(), disks: [], ...extra }], proxmox: [], synology: [] });
const limits = { serverOfflineMinutes: 60, diskUsagePercent: 90 };
test("each new port is a warning keyed by server and port; an offline server's are not judged", () => {
const list = evaluateHealth(snap({ newPorts: [{ protocol: "tcp", port: 8080, process: "node" }, { protocol: "tcp", port: 9090, process: null }] }), limits, Date.now());
assert.deepEqual(list.map((c) => [c.key, c.severity, c.source]), [["new-port:server:3:tcp:8080", "warning", "server"], ["new-port:server:3:tcp:9090", "warning", "server"]]);
assert.match(list[0].message, /nas: a new port is listening — 8080\/tcp \(node\)/);
const offline = evaluateHealth(snap({ lastSeenAt: new Date(Date.now() - 5 * 3600_000).toISOString(), newPorts: [{ protocol: "tcp", port: 8080, process: null }] }), limits, Date.now());
assert.equal(offline.some((c) => c.key.startsWith("new-port")), false);
});
test("maintenance on the server holds it back, and routing treats it as monitoring with that server's tags", () => {
assert.equal(subjectOfConditionKey("new-port:server:3:tcp:8080"), "server:3");
assert.deepEqual(metaOfConditionKey("new-port:server:3:tcp:8080", "warning"), { category: "monitoring", severity: "warning", serverId: 3 });
});
});
describe("from a report to the Ports card", () => {
let app: Server;
let base = "";
let origin = "";
let serverId = 0;
let who = "operator";
const report = (ports: ReturnType<typeof sock>[]) => ({ tasks: [], system: { listening_ports: ports } });
before(async () => {
await db.insert(users).values([
{ oidcSub: "operator", name: "Olga", role: "operator" },
{ oidcSub: "viewer", name: "Vic", role: "viewer" },
]);
serverId = (await db.insert(servers).values({ name: "nas", apiTokenHash: "n", apiTokenPrefix: "n", lastSeenAt: new Date().toISOString() }).returning({ id: servers.id }))[0].id;
const a = express();
a.use(express.json());
a.use((req, _res, next) => {
(req as unknown as { session: unknown; currentUser: unknown }).session = { user: { sub: who } };
next();
});
// The real servers router puts a signed-in user on the request before this; here the role is read the same way the middleware does.
const { requireAuth } = await import("../src/auth/middleware.js");
a.use("/api/servers/:id/ports", requireAuth, serverPortsRouter);
a.use("/api/ports", portsRouter);
app = await new Promise<Server>((resolve) => {
const s = a.listen(0, "127.0.0.1", () => resolve(s));
});
origin = `http://127.0.0.1:${(app.address() as AddressInfo).port}`;
base = `${origin}/api/servers/${serverId}/ports`;
});
after(() => {
app.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows keeps the database file locked until the process exits.
}
});
const newKeys = async () => (await collectSnapshot()).snapshot.servers.find((s) => s.id === serverId)!.newPorts!.map((p) => p.port);
test("the first report that carries ports is the baseline: nothing in it is new, and it is never changed by a later one", async () => {
await syncServerTasks(serverId, report([sock(22), sock(443)]));
let [row] = await db.select().from(servers).where(eq(servers.id, serverId));
assert.deepEqual(JSON.parse(row.portBaseline!), ["tcp:22", "tcp:443"]);
assert.deepEqual(await newKeys(), []);
await syncServerTasks(serverId, report([sock(22), sock(443), sock(8080, { process: "node" })]));
[row] = await db.select().from(servers).where(eq(servers.id, serverId));
assert.deepEqual(JSON.parse(row.portBaseline!), ["tcp:22", "tcp:443"], "8080 is not folded into what is normal");
assert.deepEqual(await newKeys(), [8080]);
});
test("a report with no ports at all does not start a baseline", async () => {
const [other] = await db.insert(servers).values({ name: "bare", apiTokenHash: "b", apiTokenPrefix: "b" }).returning({ id: servers.id });
await syncServerTasks(other.id, { tasks: [], system: {} });
const [row] = await db.select().from(servers).where(eq(servers.id, other.id));
assert.equal(row.portBaseline, null);
});
test("it is an alert on the Alerts page, in monitoring, linked to the server — and silenced by maintenance on it", async () => {
invalidateAlertsCache();
const alert = (await getAlerts(true)).alerts.find((a) => a.message.includes("a new port is listening"))!;
assert.ok(alert, "the alert is there");
assert.deepEqual([alert.category, alert.severity, alert.silenced], ["monitoring", "warning", false]);
assert.deepEqual(alert.target && [alert.target.type, alert.target.id], ["server", serverId]);
await startOrExtendWindow("server", serverId, 30, "work", "Ada");
invalidateAlertsCache();
assert.equal((await getAlerts(true)).alerts.find((a) => a.message.includes("a new port is listening"))!.silenced, true);
});
test("the Ports card marks it new, and noting it as expected ends the alert; a scan-only row does not", async () => {
who = "viewer";
let list = (await (await fetch(base)).json()).ports as { port: number; isNew: boolean }[];
assert.deepEqual(list.filter((p) => p.isNew).map((p) => p.port), [8080]);
await db.insert(serverPorts).values({ serverId, port: 8080, protocol: "tcp", open: true });
assert.deepEqual(await newKeys(), [8080], "a row that only records an open scan says nothing");
await db.delete(serverPorts).where(eq(serverPorts.port, 8080));
who = "operator";
const res = await fetch(base, { method: "PUT", headers: { "content-type": "application/json" }, body: JSON.stringify({ port: 8080, protocol: "tcp", label: "Expected" }) });
assert.equal(res.status, 200);
list = (await res.json()).ports;
assert.equal(list.find((p) => p.port === 8080)!.isNew, false);
assert.deepEqual(await newKeys(), []);
});
test("the Ports page, across every server, marks the same ports new — and noting one there is the same note", async () => {
await syncServerTasks(serverId, report([sock(22), sock(443), sock(8080), sock(9999, { process: "python" })]));
const [other] = await db.insert(servers).values({ name: "web", apiTokenHash: "w", apiTokenPrefix: "w" }).returning({ id: servers.id });
await syncServerTasks(other.id, report([sock(80)]));
await syncServerTasks(other.id, report([sock(80), sock(3000), sock(5353, { protocol: "udp" })]));
who = "viewer";
type Row = { serverId: number; port: number; protocol: string; isNew: boolean };
const overview = async () => ((await (await fetch(`${origin}/api/ports/agent`)).json()).ports as Row[]);
const fresh = async () => (await overview()).filter((p) => p.isNew).map((p) => `${p.serverId}:${p.protocol}/${p.port}`).sort();
assert.deepEqual(await fresh(), [`${serverId}:tcp/9999`, `${other.id}:tcp/3000`].sort(), "what the baseline had, UDP and noted ports are not new");
assert.equal((await overview()).filter((p) => p.serverId === serverId).length, 4, "every port is still listed, new or not");
who = "operator";
const res = await fetch(base, { method: "PUT", headers: { "content-type": "application/json" }, body: JSON.stringify({ port: 9999, protocol: "tcp", label: "Expected" }) });
assert.equal(res.status, 200);
assert.deepEqual(await fresh(), [`${other.id}:tcp/3000`]);
assert.deepEqual(await newKeys(), [], "and the alert ends with it");
});
test("it can be switched off, and then nothing is new", async () => {
await syncServerTasks(serverId, report([sock(22), sock(443), sock(8080), sock(9998)]));
assert.deepEqual(await newKeys(), [9998]);
await updateSettings({ healthChecks: { newPortAlerts: false } });
assert.deepEqual(await newKeys(), []);
who = "viewer";
assert.equal(((await (await fetch(base)).json()).ports as { isNew: boolean }[]).some((p) => p.isNew), false);
assert.equal(((await (await fetch(`${origin}/api/ports/agent`)).json()).ports as { isNew: boolean }[]).some((p) => p.isNew), false, "nor on the Ports page");
await updateSettings({ healthChecks: { newPortAlerts: true } });
});
});