From 7e625e7f42d5c809466b2e4a59911597d5f29261 Mon Sep 17 00:00:00 2001 From: Bobban Rydh Date: Fri, 30 Oct 2026 23:14:24 +0100 Subject: [PATCH] Internet as a dependency: a node that can be needed, never judged down Co-Authored-By: Claude Sonnet 5.5 --- DATABASE.md | 2 +- README.md | 2 +- ROLES.md | 2 +- server/src/routes/dependencies.ts | 7 +- server/src/services/dependencies.ts | 18 +++- server/test/dependencyInternet.test.ts | 125 +++++++++++++++++++++++++ web/src/api/client.ts | 7 +- web/src/components/DependencyMap.tsx | 4 +- web/src/components/ImpactNote.tsx | 8 +- web/src/styles.css | 4 + web/src/views/DependencyEditor.tsx | 16 ++-- 11 files changed, 173 insertions(+), 22 deletions(-) create mode 100644 server/test/dependencyInternet.test.ts diff --git a/DATABASE.md b/DATABASE.md index 1cf9908..aa0a06c 100644 --- a/DATABASE.md +++ b/DATABASE.md @@ -737,7 +737,7 @@ The hardware inventory. |---|---|---| | `id` | integer PK | | | `from_type`, `from_id` | text, integer NOT NULL | The thing that needs: `server`, `integration` or `device`, and its id. | -| `to_type`, `to_id` | text, integer NOT NULL | The thing it needs. Unique together with the pair above. | +| `to_type`, `to_id` | text, integer NOT NULL | The thing it needs: the same kinds, or `internet` (id 1). The internet is not a row anywhere — it is added to the graph in code, always, is never down, and is never the thing that needs. Unique together with the pair above. | | `created_at` | text NOT NULL | ISO. | No foreign keys (like `maintenance_windows`): a row whose server or integration is gone is ignored, not an error. diff --git a/README.md b/README.md index c95650f..8da6594 100644 --- a/README.md +++ b/README.md @@ -454,7 +454,7 @@ each as a sentence. Narrow it by kind of change, by server, by how far back (a d export. A server's Activity card links to its slice of it. Sign-ins and people's own data exports aren't changes and are left out. The raw audit log is the other tab of the same page (Change log → *Raw audit log*). **Dependencies beyond servers** (Reference → Map → *Dependencies*, which draws the graph with the editor under it). Say that Gitea needs the server it is installed on, or that a server -needs Proxmox to answer. When what is needed is down, the alert of what needs it is folded under the first one exactly like a +needs Proxmox to answer. **Internet** is on the list too, as something a server, a service or a network device can need (a VPS, Hetzner, the router): it is drawn on the map and answers "what depends on Internet?", but nothing watches it, so it is never down and holds no alert back. It is only ever needed — it can't be made to need anything. When what is needed is down, the alert of what needs it is folded under the first one exactly like a guest under its host — shown, labelled "caused by …", left out of notifications and tickets — and the root cause says what else it takes down. It follows chains and the "runs on" links of servers; something needing two things is explained by whichever is down; a loop explains nothing and one that would be made is refused. An integration is judged per kind of service (as its health is), diff --git a/ROLES.md b/ROLES.md index 39538ef..94add1a 100644 --- a/ROLES.md +++ b/ROLES.md @@ -144,7 +144,7 @@ even further, to admin only: - **Alert rules** (Monitoring → Alert rules): everyone signed in sees the rules and where each is raised now; making, changing, trying, switching and removing one is administrator-only (a rule decides who is woken up). **Snooze** an alert, wake it, **close** it and open it again need operator, like acknowledging. The storage forecast beside Proxmox storages and Synology volumes is for everyone who can see those pages. - **What changed before this?** (on an incident's page, and `GET /api/v1/incidents/:id/before`): everyone signed in, like the incident record it is made from. -- **Dependencies**: everyone can see what needs what; adding and removing one needs operator. So does adding or hiding a *suggested* one. +- **Dependencies**: everyone can see what needs what (including what needs the Internet); adding and removing one needs operator. So does adding or hiding a *suggested* one. - **To do and Notes** (Operations → To do, the *To do* and *Notes* cards on a server's page, a device's *Notes* drawer): everyone signed in reads them; adding, editing, ticking off and removing a job, and writing a note, and adding, captioning and removing a photo on one, need operator. - **Racks** (Inventory → Racks) and the **network diagram**: everyone signed in. A rack is made from the hardware's *where* and *rack unit*, which operators edit on the inventory page. - **Proxy hosts** (Network → Proxy hosts): everyone signed in sees what Nginx Proxy Manager serves; **Read now** needs operator; adding the integration (its login) is an administrator's job. diff --git a/server/src/routes/dependencies.ts b/server/src/routes/dependencies.ts index 87d61f3..997eadf 100644 --- a/server/src/routes/dependencies.ts +++ b/server/src/routes/dependencies.ts @@ -6,7 +6,7 @@ import { dependencies, networkDevices, servers } from "../db/schema.js"; import { requireAuth, requireRole } from "../auth/middleware.js"; import { recordAudit } from "../services/audit.js"; import { invalidateAlertsCache } from "../services/alerts.js"; -import { dependentsOf, impactOf, loadGraph, nodeKey, nodeTypes, wouldLoop } from "../services/dependencies.js"; +import { dependentsOf, impactOf, INTERNET_ID, loadGraph, nodeKey, nodeTypes, wouldLoop } from "../services/dependencies.js"; import { getSettings } from "../services/settingsStore.js"; import { loadDependencySuggestions, loadDismissedDependencies, saveDismissedDependencies } from "../services/dependencySuggestions.js"; import { getSourceStatus } from "../services/integrationHealthMonitor.js"; @@ -121,6 +121,8 @@ dependenciesRouter.get("/graph", asyncHandler(async (_req, res) => { if (type === "server") { const s = serverById.get(id); if (s) status = serverStatus(s, healthChecks.serverOfflineMinutes, now); + } else if (type === "internet") { + status = "unknown"; // not watched: nothing here judges the internet down } else if (type === "device") { const d = deviceById.get(id); if (d) status = d.state === "online" ? "ok" : d.state === "offline" ? "bad" : d.state === "updating" ? "warn" : "unknown"; @@ -131,7 +133,7 @@ dependenciesRouter.get("/graph", asyncHandler(async (_req, res) => { status = st === "failing" ? "bad" : st === "ok" ? "ok" : "unknown"; } } - return { key, type: type as "server" | "integration" | "device", id, name: graph.names.get(key) ?? key, status, href: type === "server" ? `/servers/${id}` : type === "device" ? "/network/devices" : "/integrations" }; + return { key, type: type as "server" | "integration" | "device" | "internet", id, name: graph.names.get(key) ?? key, status, href: type === "server" ? `/servers/${id}` : type === "device" ? "/network/devices" : type === "internet" ? "/map?view=dependencies" : "/integrations" }; }) .sort((a, b) => a.name.localeCompare(b.name)); res.json({ nodes, edges }); @@ -141,6 +143,7 @@ dependenciesRouter.post("/", requireRole("operator"), asyncHandler(async (req, r const parsed = edgeSchema.safeParse(req.body); if (!parsed.success) return res.status(400).json({ error: "invalid_body", message: "Say what needs what: a server or an integration each.", details: parsed.error.flatten() }); const d = parsed.data; + if (d.fromType === "internet") return res.status(400).json({ error: "internet_needs_nothing", message: "The internet can't be made to need something; pick it as what a server, service or device needs." }); const graph = await loadGraph(); const from = nodeKey(d.fromType, d.fromId); const to = nodeKey(d.toType, d.toId); diff --git a/server/src/services/dependencies.ts b/server/src/services/dependencies.ts index 446d321..6524268 100644 --- a/server/src/services/dependencies.ts +++ b/server/src/services/dependencies.ts @@ -8,6 +8,9 @@ * that can be down and be needed. (DNS providers raise no alerts of their own, so there is * nothing to fold.) An integration is judged per kind of service, as its health is: it is folded only if every enabled instance of that * kind is explained. A UPS is down while it runs on battery (services/upsSync.ts). + * + * "The internet" is a node too, so that what needs it (a cloud service, a VPS monitor, the router) can be drawn and found with "what depends on …?". + * Nothing here judges it down — it is the one node that is never down — so it explains no alert; it is a thing to point at, not a thing that is watched. */ import { eq } from "drizzle-orm"; import { db } from "../db/client.js"; @@ -20,9 +23,13 @@ import { upsOnBatteryIds } from "./upsSync.js"; /** Where the health monitor keeps the problems it is announcing; read here so a service's alert can tell a server it needs is down. */ export const HEALTH_STATE_FLAG = "healthActiveConditions"; -export const nodeTypes = ["server", "integration", "device"] as const; +export const nodeTypes = ["server", "integration", "device", "internet"] as const; export type NodeType = (typeof nodeTypes)[number]; +/** There is one internet; its node is `internet:1`. */ +export const INTERNET_ID = 1; +export const INTERNET_NAME = "Internet"; + export const nodeKey = (type: NodeType, id: number) => `${type}:${id}`; export interface DependencyEdge { @@ -142,6 +149,7 @@ export async function loadGraph(): Promise { for (const s of serverRows) names.set(nodeKey("server", s.id), s.name); for (const i of intRows) names.set(nodeKey("integration", i.id), i.name); for (const d of deviceRows) names.set(nodeKey("device", d.id), d.name); + names.set(nodeKey("internet", INTERNET_ID), INTERNET_NAME); const rows = depRows.map((r) => ({ id: r.id, fromType: r.fromType as NodeType, fromId: r.fromId, toType: r.toType as NodeType, toId: r.toId, createdAt: r.createdAt })); const instances = new Map(); for (const i of intRows) if (i.enabled) instances.set(i.type, [...(instances.get(i.type) ?? []), i.id]); @@ -197,8 +205,11 @@ export interface ImpactItem { silenced: boolean; } +/** What needs something is never the internet (it is only ever needed), so what is affected is one of the three that can be put in maintenance. */ +export type DependentItem = ImpactItem & { type: Exclude }; + /** What would be affected if `type`/`id` went down (everything that needs it) and what it needs itself. Null if it doesn't exist. */ -export async function impactOf(type: NodeType, id: number, now: Date = new Date()): Promise<{ target: { key: string; type: NodeType; id: number; name: string }; dependents: ImpactItem[]; needs: ImpactItem[] } | null> { +export async function impactOf(type: NodeType, id: number, now: Date = new Date()): Promise<{ target: { key: string; type: NodeType; id: number; name: string }; dependents: DependentItem[]; needs: ImpactItem[] } | null> { const graph = await loadGraph(); const key = nodeKey(type, id); const name = graph.names.get(key); @@ -211,7 +222,7 @@ export async function impactOf(type: NodeType, id: number, now: Date = new Date( }; return { target: { key, type, id, name }, - dependents: dependentsOf(graph.edges, key).map((d) => item(d.key, d.distance)), + dependents: dependentsOf(graph.edges, key).map((d) => item(d.key, d.distance) as DependentItem), needs: needsOfNode(graph.edges, key).map((k, i) => item(k, i + 1)), }; } @@ -294,6 +305,7 @@ export async function integrationCausedBy(type: string, failingTypes: string[]): } export async function nodeExists(type: NodeType, id: number): Promise { + if (type === "internet") return id === INTERNET_ID; if (type === "device") return (await db.select({ id: networkDevices.id }).from(networkDevices).where(eq(networkDevices.id, id)).limit(1)).length > 0; if (type === "server") return (await db.select({ id: servers.id }).from(servers).where(eq(servers.id, id)).limit(1)).length > 0; return (await db.select({ id: integrations.id }).from(integrations).where(eq(integrations.id, id)).limit(1)).length > 0; diff --git a/server/test/dependencyInternet.test.ts b/server/test/dependencyInternet.test.ts new file mode 100644 index 0000000..bc98733 --- /dev/null +++ b/server/test/dependencyInternet.test.ts @@ -0,0 +1,125 @@ +/** + * "The internet" as something a server, a service or a network device can need: it is a node of the dependency graph that is always there, can only be needed, and is never + * judged down — so it can be drawn and asked "what depends on it?", and it folds no alert. + * + * 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-deps-net-")); +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, integrations, networkDevices } = await import("../src/db/schema.js"); +const { runMigrations } = await import("../src/db/migrate.js"); +const { dependenciesRouter } = await import("../src/routes/dependencies.js"); +const { nodeExists, INTERNET_ID } = await import("../src/services/dependencies.js"); + +await runMigrations(); + +describe("the internet as a dependency", () => { + let app: Server; + let base = ""; + let who = "operator"; + let box = 0; + let hetzner = 0; + let gateway = 0; + + before(async () => { + await db.insert(users).values([ + { oidcSub: "operator", name: "Olga", role: "operator" }, + { oidcSub: "viewer", name: "Vic", role: "viewer" }, + ]); + box = (await db.insert(servers).values({ name: "vps", apiTokenHash: "v", apiTokenPrefix: "v", lastSeenAt: new Date().toISOString() }).returning({ id: servers.id }))[0].id; + const ints = await db.insert(integrations).values([{ type: "hetzner", name: "Hetzner", baseUrl: "https://api.hetzner.cloud", config: "{}" }, { type: "unifi", name: "UniFi", baseUrl: "https://unifi.lab", config: "{}" }]).returning({ id: integrations.id }); + hetzner = ints[0].id; + gateway = (await db.insert(networkDevices).values({ integrationId: ints[1].id, externalId: "aa:bb:cc:dd:ee:ff", name: "Gateway", kind: "gateway", state: "online", firstSeenAt: new Date().toISOString(), updatedAt: new Date().toISOString() }).returning({ id: networkDevices.id }))[0].id; + + 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/dependencies", dependenciesRouter); + app = await new Promise((resolve) => { + const s = a.listen(0, "127.0.0.1", () => resolve(s)); + }); + base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/dependencies`; + }); + + 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) }); + const need = (fromType: string, fromId: number) => ({ fromType, fromId, toType: "internet", toId: INTERNET_ID }); + + test("the internet is always there to be picked, whatever else exists", async () => { + const list = await (await send("GET", "/")).json(); + assert.ok(list.nodes.some((n: { key: string; name: string; type: string }) => n.key === "internet:1" && n.name === "Internet" && n.type === "internet")); + assert.equal(await nodeExists("internet", 1), true); + assert.equal(await nodeExists("internet", 2), false); + }); + + test("a server, a service and a network device can each need it", async () => { + assert.equal((await send("POST", "/", need("server", box))).status, 201); + assert.equal((await send("POST", "/", need("integration", hetzner))).status, 201); + assert.equal((await send("POST", "/", need("device", gateway))).status, 201); + const list = await (await send("GET", "/")).json(); + assert.deepEqual(list.dependencies.map((d: { from: { name: string }; to: { name: string } }) => `${d.from.name} > ${d.to.name}`).sort(), ["Gateway > Internet", "Hetzner > Internet", "vps > Internet"]); + }); + + test("it can't be made to need anything, there is only the one, and it isn't added twice", async () => { + const reverse = await send("POST", "/", { fromType: "internet", fromId: 1, toType: "server", toId: box }); + assert.equal(reverse.status, 400); + assert.match((await reverse.json()).message, /can't be made to need/); + assert.equal((await send("POST", "/", { fromType: "server", fromId: box, toType: "internet", toId: 2 })).status, 400, "there is no second internet"); + assert.equal((await send("POST", "/", need("server", box))).status, 409, "twice"); + who = "viewer"; + assert.equal((await send("POST", "/", need("integration", hetzner))).status, 403); + who = "operator"; + }); + + test("asking what depends on it lists all three; it relies on nothing", async () => { + const impact = await (await send("GET", "/impact?type=internet&id=1")).json(); + assert.equal(impact.target.name, "Internet"); + assert.deepEqual(impact.dependents.map((d: { name: string }) => d.name).sort(), ["Gateway", "Hetzner", "vps"]); + assert.deepEqual(impact.needs, []); + const server = await (await send("GET", `/impact?type=server&id=${box}`)).json(); + assert.deepEqual(server.needs.map((n: { name: string; type: string }) => [n.name, n.type]), [["Internet", "internet"]]); + }); + + test("on the map it is a box that is not watched; it is never down", async () => { + const graph = await (await send("GET", "/graph")).json(); + const node = graph.nodes.find((n: { key: string }) => n.key === "internet:1"); + assert.equal(node.name, "Internet"); + assert.equal(node.status, "unknown"); + assert.equal(node.type, "internet"); + assert.equal(graph.edges.filter((e: { from: string }) => e.from === "internet:1").length, 3, "from what is needed to what needs it"); + }); + + test("removing one works, and the internet stays", async () => { + const list = await (await send("GET", "/")).json(); + const one = list.dependencies.find((d: { from: { name: string } }) => d.from.name === "Hetzner"); + assert.equal((await send("DELETE", `/${one.id}`)).status, 204); + const after = await (await send("GET", "/impact?type=internet&id=1")).json(); + assert.deepEqual(after.dependents.map((d: { name: string }) => d.name).sort(), ["Gateway", "vps"]); + assert.equal(after.target.name, "Internet"); + }); +}); diff --git a/web/src/api/client.ts b/web/src/api/client.ts index 88f568b..b86547a 100644 --- a/web/src/api/client.ts +++ b/web/src/api/client.ts @@ -1952,7 +1952,8 @@ export interface LifecycleReport { export type AssetKind = "server" | "storage" | "network" | "power" | "client" | "other"; -export type DependencyNodeType = "server" | "integration" | "device"; +/** "internet" is the one node that is only ever needed and never judged down (there is just one, id 1). */ +export type DependencyNodeType = "server" | "integration" | "device" | "internet"; /** Something that would be affected if another went down (or that it needs): `distance` 1 is directly, 2 through one other, and so on. */ export interface DependencyImpactItem { @@ -1963,9 +1964,11 @@ export interface DependencyImpactItem { distance: number; silenced: boolean; } +export type DependentImpactItem = DependencyImpactItem & { type: Exclude }; export interface DependencyImpact { target: { key: string; type: DependencyNodeType; id: number; name: string }; - dependents: DependencyImpactItem[]; + /** Never the internet, which is only ever needed. */ + dependents: DependentImpactItem[]; needs: DependencyImpactItem[]; } export interface DependencyGraphNode { diff --git a/web/src/components/DependencyMap.tsx b/web/src/components/DependencyMap.tsx index 61057b3..0702d1a 100644 --- a/web/src/components/DependencyMap.tsx +++ b/web/src/components/DependencyMap.tsx @@ -13,7 +13,7 @@ const COL_GAP = 120; const STATUS_SYMBOL: Record = { ok: "✓", bad: "✕", warn: "▲", unknown: "·" }; const STATUS_WORD: Record = { ok: "working", bad: "problem", warn: "check", unknown: "no status" }; -const KIND_LABEL: Record = { server: "Server", integration: "Integration", device: "Network device" }; +const KIND_LABEL: Record = { server: "Server", integration: "Integration", device: "Network device", internet: "Internet" }; interface Placed extends DependencyGraphNode { x: number; @@ -151,7 +151,7 @@ export default function DependencyMap() {