Internet as a dependency: a node that can be needed, never judged down

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-30 23:14:24 +01:00
1 parent fca2dc0338
commit 7e625e7f42
11 files changed
+173 -22

No files matched your search

+1 -1
View File
@@ -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.
+1 -1
View File
@@ -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),
+1 -1
View File
@@ -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.
+5 -2
View File
@@ -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);
+15 -3
View File
@@ -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<Graph> {
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<string, number[]>();
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<NodeType, "internet"> };
/** 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<boolean> {
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;
+125
View File
@@ -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<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/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");
});
});
+5 -2
View File
@@ -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<DependencyNodeType, "internet"> };
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 {
+2 -2
View File
@@ -13,7 +13,7 @@ const COL_GAP = 120;
const STATUS_SYMBOL: Record<DependencyGraphNode["status"], string> = { ok: "✓", bad: "✕", warn: "▲", unknown: "·" };
const STATUS_WORD: Record<DependencyGraphNode["status"], string> = { ok: "working", bad: "problem", warn: "check", unknown: "no status" };
const KIND_LABEL: Record<DependencyGraphNode["type"], string> = { server: "Server", integration: "Integration", device: "Network device" };
const KIND_LABEL: Record<DependencyGraphNode["type"], string> = { server: "Server", integration: "Integration", device: "Network device", internet: "Internet" };
interface Placed extends DependencyGraphNode {
x: number;
@@ -151,7 +151,7 @@ export default function DependencyMap() {
<button
key={n.key}
type="button"
className={`map-node map-node-${n.type === "server" ? "server" : n.type === "device" ? "device" : "monitor"} ${state(n.key)}`}
className={`map-node map-node-${n.type === "server" ? "server" : n.type === "device" ? "device" : n.type === "internet" ? "internet" : "monitor"} ${state(n.key)}`}
style={{ left: n.x, top: n.y, width: NODE_W, height: NODE_H, textAlign: "left" }}
aria-pressed={selected === n.key}
aria-label={`${KIND_LABEL[n.type]}: ${n.name}, ${STATUS_WORD[n.status]}. Show what depends on it.`}
+4 -4
View File
@@ -1,6 +1,6 @@
import { useEffect, useState } from "react";
import { Link } from "react-router-dom";
import { api, type DependencyImpactItem } from "../api/client";
import { api, type DependentImpactItem } from "../api/client";
export interface ImpactTarget {
type: string;
@@ -19,10 +19,10 @@ export default function ImpactNote({
}: {
targets: ImpactTarget[];
silence?: { value: boolean; onChange: (on: boolean) => void };
onAdd?: (items: DependencyImpactItem[]) => void;
onAdd?: (items: DependentImpactItem[]) => void;
verb?: string;
}) {
const [items, setItems] = useState<DependencyImpactItem[] | null>(null);
const [items, setItems] = useState<DependentImpactItem[] | null>(null);
const keyOf = targets.map((t) => `${t.type}:${t.id}`).sort().join(",");
useEffect(() => {
@@ -37,7 +37,7 @@ export default function ImpactNote({
.then((all) => {
if (!alive) return;
const selected = new Set(own.map((t) => `${t.type}:${t.id}`));
const seen = new Map<string, DependencyImpactItem>();
const seen = new Map<string, DependentImpactItem>();
for (const impact of all) for (const d of impact?.dependents ?? []) if (!selected.has(d.key) && !seen.has(d.key)) seen.set(d.key, d);
setItems([...seen.values()].sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name)));
})
+4
View File
@@ -1056,6 +1056,10 @@ a.map-node:focus-visible {
border-left-color: #48bb78;
}
.map-node-internet {
border-left-color: #ed64a6;
}
/* The one chart (components/TimeChart.tsx). */
.time-chart {
position: relative;
+10 -6
View File
@@ -8,9 +8,10 @@ import { readableError } from "../utils/errors";
import { toast } from "../utils/toast";
import { EmptyRow } from "../components/EmptyState";
const TYPE_LABELS = { server: "Server", integration: "Integration", device: "Network device" } as const;
const TYPE_LABELS = { server: "Server", integration: "Integration", device: "Network device", internet: "Internet" } as const;
const GROUP_LABELS = { server: "Servers", integration: "Integrations", device: "Network devices", internet: "Internet" } as const;
const linkTo = (type: string, id: number) => (type === "server" ? `/servers/${id}` : type === "device" ? "/network/devices" : "/integrations");
const linkTo = (type: string, id: number) => (type === "server" ? `/servers/${id}` : type === "device" ? "/network/devices" : type === "internet" ? "/map?view=dependencies" : "/integrations");
/** The options of a node picker, grouped by what they are. */
function NodeSelect({ id, label, nodes, value, onChange }: { id: string; label: string; nodes: DependencyNode[]; value: string; onChange: (key: string) => void }) {
@@ -21,10 +22,10 @@ function NodeSelect({ id, label, nodes, value, onChange }: { id: string; label:
</label>
<select id={id} className="form-select" value={value} onChange={(e) => onChange(e.target.value)}>
<option value="">— choose —</option>
{(["server", "integration", "device"] as const).map((type) => {
{(["server", "integration", "device", "internet"] as const).map((type) => {
const group = nodes.filter((n) => n.type === type);
return group.length === 0 ? null : (
<optgroup key={type} label={`${TYPE_LABELS[type]}s`}>
<optgroup key={type} label={GROUP_LABELS[type]}>
{group.map((n) => (
<option key={n.key} value={n.key}>
{n.name}
@@ -96,7 +97,7 @@ export default function DependencyEditor({ user }: { user: CurrentUser }) {
const parse = (key: string) => {
const [type, id] = key.split(":");
return { type: type as "server" | "integration" | "device", id: Number(id) };
return { type: type as DependencyNode["type"], id: Number(id) };
};
async function add(e: React.FormEvent) {
@@ -207,7 +208,7 @@ export default function DependencyEditor({ user }: { user: CurrentUser }) {
</div>
<div className="card-body row g-3 align-items-end">
<div className="col-md-5">
<NodeSelect id="dep-from" label="This…" nodes={data?.nodes ?? []} value={from} onChange={setFrom} />
<NodeSelect id="dep-from" label="This…" nodes={(data?.nodes ?? []).filter((n) => n.type !== "internet")} value={from} onChange={setFrom} />
</div>
<div className="col-md-5">
<NodeSelect id="dep-to" label="…needs this" nodes={(data?.nodes ?? []).filter((n) => n.key !== from)} value={to} onChange={setTo} />
@@ -218,6 +219,9 @@ export default function DependencyEditor({ user }: { user: CurrentUser }) {
</button>
</div>
</div>
<div className="card-footer text-secondary small">
<strong>Internet</strong> can be picked as what something needs — a cloud service, a VPS, the router. Nothing here watches the internet, so it never counts as down and holds no alert back; it is there so the map shows what relies on it, and so &ldquo;what depends on Internet?&rdquo; has an answer.
</div>
</form>
)}