UniFi integration: network devices, Wi-Fi and networks, as part of the dependency map

A UniFi controller (API key on Network 9+, or a read-only local login on any
version) is read every five minutes. Its switches, access points and gateways
are kept with state, IP, uptime, firmware and uplink; its networks and Wi-Fi
names beside them (passphrases are never read). Nothing is written to the
controller.

Network > Network devices lists them. Devices are a new node type in the
dependency map: uplinks become dependencies by themselves, others can be
written by hand. A device offline past a limit is an offline alert, folds what
depends on it, can be silenced with maintenance and have runbooks.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-20 00:35:48 +02:00
1 parent 73a06ebe63
commit 396e074108
48 files changed
+6893 -102

No files matched your search

+41
View File
@@ -0,0 +1,41 @@
CREATE TABLE `network_devices` (
`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
`integration_id` integer NOT NULL,
`external_id` text NOT NULL,
`site_name` text,
`name` text NOT NULL,
`model` text,
`kind` text DEFAULT 'other' NOT NULL,
`ip` text,
`mac` text,
`state` text DEFAULT 'other' NOT NULL,
`uptime_seconds` integer,
`firmware` text,
`firmware_updatable` integer DEFAULT false NOT NULL,
`uplink_external_id` text,
`offline_since` text,
`last_online_at` text,
`first_seen_at` text NOT NULL,
`updated_at` text NOT NULL,
FOREIGN KEY (`integration_id`) REFERENCES `integrations`(`id`) ON UPDATE no action ON DELETE cascade
);
--> statement-breakpoint
CREATE UNIQUE INDEX `network_devices_unique` ON `network_devices` (`integration_id`,`external_id`);--> statement-breakpoint
CREATE TABLE `network_segments` (
`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
`integration_id` integer NOT NULL,
`kind` text NOT NULL,
`external_id` text NOT NULL,
`site_name` text,
`name` text NOT NULL,
`enabled` integer DEFAULT true NOT NULL,
`vlan_id` integer,
`subnet` text,
`purpose` text,
`security` text,
`network_name` text,
`updated_at` text NOT NULL,
FOREIGN KEY (`integration_id`) REFERENCES `integrations`(`id`) ON UPDATE no action ON DELETE cascade
);
--> statement-breakpoint
CREATE UNIQUE INDEX `network_segments_unique` ON `network_segments` (`integration_id`,`kind`,`external_id`);
File diff suppressed because it is too large. Load diff
+7
View File
@@ -309,6 +309,13 @@
"when": 1792443011097,
"tag": "0043_puzzling_prism",
"breakpoints": true
},
{
"idx": 44,
"version": "6",
"when": 1792447584218,
"tag": "0044_sparkling_scourge",
"breakpoints": true
}
]
}
+2
View File
@@ -45,6 +45,7 @@ import { tagsRouter } from "./routes/tags.js";
import { portsRouter } from "./routes/ports.js";
import { alertsRouter } from "./routes/alerts.js";
import { mapRouter } from "./routes/map.js";
import { networkRouter } from "./routes/network.js";
import { generatorRouter } from "./routes/generator.js";
import { alertTicketsRouter } from "./routes/alertTickets.js";
import { avatarsRouter } from "./routes/avatars.js";
@@ -161,6 +162,7 @@ export function createApp() {
app.use("/api/alerts/bulk", alertsBulkRouter);
app.use("/api/alerts", alertsRouter);
app.use("/api/map", mapRouter);
app.use("/api/network", networkRouter);
app.use("/api/generator", generatorRouter);
app.use("/api/alert-tickets", alertTicketsRouter);
+55 -1
View File
@@ -76,7 +76,7 @@ export const notificationQueue = sqliteTable("notification_queue", {
// ─── Maintenance windows — alerts about a target are silenced until endsAt ──
export const maintenanceTargetTypes = ["server", "integration", "dns_provider"] as const;
export const maintenanceTargetTypes = ["server", "integration", "dns_provider", "device"] as const;
export type MaintenanceTargetType = (typeof maintenanceTargetTypes)[number];
export const maintenanceWindows = sqliteTable("maintenance_windows", {
@@ -515,6 +515,7 @@ export const integrationTypes = [
"phpipam",
"pbs",
"osticket",
"unifi",
] as const;
export type IntegrationType = (typeof integrationTypes)[number];
@@ -533,6 +534,59 @@ export const integrations = sqliteTable("integrations", {
.default(sql`(current_timestamp)`),
});
// Network equipment read from a UniFi controller (switches, access points, gateways), refreshed every few minutes by services/unifiSync.ts. A device is a node
// in the dependency map ("device:<id>"), like a server, and raises an "offline" alert when the controller has not seen it online for a while.
export const networkDevices = sqliteTable(
"network_devices",
{
id: integer("id").primaryKey({ autoIncrement: true }),
integrationId: integer("integration_id")
.notNull()
.references(() => integrations.id, { onDelete: "cascade" }),
externalId: text("external_id").notNull(), // the MAC address, lower case: the one thing both of UniFi's APIs give for every device
siteName: text("site_name"),
name: text("name").notNull(),
model: text("model"),
kind: text("kind").$type<"gateway" | "switch" | "access_point" | "other">().notNull().default("other"),
ip: text("ip"),
mac: text("mac"),
state: text("state").$type<"online" | "offline" | "updating" | "pending" | "other">().notNull().default("other"),
uptimeSeconds: integer("uptime_seconds"),
firmware: text("firmware"),
firmwareUpdatable: integer("firmware_updatable", { mode: "boolean" }).notNull().default(false),
uplinkExternalId: text("uplink_external_id"), // the MAC of the device this one is connected through, when the controller says
// When the controller first stopped seeing it online, kept until it is online again; the offline alert counts from here.
offlineSince: text("offline_since"),
lastOnlineAt: text("last_online_at"),
firstSeenAt: text("first_seen_at").notNull(),
updatedAt: text("updated_at").notNull(),
},
(t) => [uniqueIndex("network_devices_unique").on(t.integrationId, t.externalId)],
);
// The networks (VLANs) and Wi-Fi names (SSIDs) a UniFi controller has set up, kept beside the devices. Passphrases are never read.
export const networkSegments = sqliteTable(
"network_segments",
{
id: integer("id").primaryKey({ autoIncrement: true }),
integrationId: integer("integration_id")
.notNull()
.references(() => integrations.id, { onDelete: "cascade" }),
kind: text("kind").$type<"network" | "ssid">().notNull(),
externalId: text("external_id").notNull(),
siteName: text("site_name"),
name: text("name").notNull(),
enabled: integer("enabled", { mode: "boolean" }).notNull().default(true),
vlanId: integer("vlan_id"),
subnet: text("subnet"), // a network's address range, e.g. 192.168.10.1/24
purpose: text("purpose"), // a network: corporate, guest, …
security: text("security"), // an SSID: wpa2, wpa3, open, …
networkName: text("network_name"), // an SSID: the network its clients land on
updatedAt: text("updated_at").notNull(),
},
(t) => [uniqueIndex("network_segments_unique").on(t.integrationId, t.kind, t.externalId)],
);
// A port on a server that's either been seen open (by a scan or the agent) or that someone wrote a note about.
// Rows exist only while they carry information: an open port, or one with a label/comment ("reserved").
export const serverPorts = sqliteTable(
+2
View File
@@ -24,6 +24,7 @@ import { initEscalation } from "./services/escalation.js";
import { initEndpointMonitor } from "./services/endpointMonitor.js";
import { initPatchPlans } from "./services/patchPlans.js";
import { initFlapMonitor } from "./services/flapMonitor.js";
import { initUnifiSync } from "./services/unifiSync.js";
import { initSelfBackupScheduler } from "./services/selfBackupScheduler.js";
import { initIncidentRecorder } from "./services/incidents.js";
import { getAlerts } from "./services/alerts.js";
@@ -67,6 +68,7 @@ initEscalation();
initEndpointMonitor();
initPatchPlans();
initFlapMonitor();
initUnifiSync();
createApp().listen(env.port, () => {
console.log(`homelab-manager listening on port ${env.port}`);
+23 -1
View File
@@ -72,6 +72,22 @@ export const INTEGRATION_FIELDS: Partial<Record<IntegrationType, IntegrationFiel
{ key: "tokenSecret", label: "API token secret", secret: true, type: "password" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
unifi: [
{ key: "url", label: "UniFi controller URL", secret: false, placeholder: "https://unifi.example.lan (or https://host:8443 for a self-hosted controller)" },
{
key: "apiKey",
label: "API key (Network 9 or later)",
secret: true,
optional: true,
type: "password",
placeholder: "made under Settings → Control Plane → Integrations; leave blank to log in instead",
},
{ key: "username", label: "Username (instead of an API key)", secret: false, optional: true, placeholder: "a local, read-only account — not a Ubiquiti cloud account" },
{ key: "password", label: "Password (instead of an API key)", secret: true, optional: true, type: "password" },
{ key: "site", label: "Only this site (optional)", secret: false, optional: true, placeholder: "the site's name as shown in UniFi; blank reads every site" },
{ key: "selfHosted", label: "A self-hosted Network application, not a UniFi OS console (UDM, Cloud Gateway, Cloud Key)", secret: false, type: "checkbox" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
osticket: [
{ key: "host", label: "Database host", secret: false, placeholder: "osticket-db.example.lan" },
{ key: "port", label: "Database port", secret: false, optional: true, placeholder: "3306" },
@@ -137,8 +153,14 @@ export function validateIntegrationConfig(
merged: Record<string, string | boolean | undefined>,
): string[] {
const fields = INTEGRATION_FIELDS[type] ?? [];
return fields
const missing = fields
.filter((f) => f.type !== "checkbox" && !f.optional)
.filter((f) => merged[f.key] === undefined || merged[f.key] === "")
.map((f) => f.key);
// UniFi takes an API key, or a username with its password: one way in is required, which no single field says.
if (type === "unifi") {
const has = (k: string) => typeof merged[k] === "string" && (merged[k] as string).trim() !== "";
if (!has("apiKey") && !(has("username") && has("password"))) missing.push(has("username") ? "password" : "apiKey");
}
return missing;
}
+3
View File
@@ -10,6 +10,7 @@ import { createUptimeKumaAdapter } from "./uptimekuma/adapter.js";
import { createPhpIpamAdapter } from "./phpipam/adapter.js";
import { createPbsAdapter } from "./pbs/adapter.js";
import { createOsTicketAdapter } from "./osticket/adapter.js";
import { createUnifiAdapter } from "./unifi/adapter.js";
export interface PingableAdapter {
ping(): Promise<{ ok: boolean; latencyMs?: number; error?: string }>;
@@ -44,6 +45,8 @@ export function createIntegrationAdapter(type: IntegrationType, config: Integrat
return createPbsAdapter(config as any);
case "osticket":
return createOsTicketAdapter(config as any);
case "unifi":
return createUnifiAdapter(config as any);
default:
throw new Error(`Integration type "${type}" is not implemented yet`);
}
+556
View File
@@ -0,0 +1,556 @@
/**
* UniFi (Network application) adapter.
* Requires config: url, and either apiKey, or username + password; optional: site, selfHosted, insecure.
*
* Two ways in, because controllers differ:
*
* - **API key** (UniFi Network 9 and later; the key is made under Settings → Control Plane → Integrations and sent as `X-API-KEY`). This uses the
* official Integration API, `<console>/proxy/network/integration/v1/…` on a UniFi OS console (UDM, UCG, Cloud Key Gen2+) or `<host>:8443/integration/v1/…`
* on a self-hosted Network application. Sites, devices (state, IP, firmware), each device's uplink and uptime, networks and Wi-Fi broadcasts. The prefix is
* found by asking: a 404 on the first form tries the second, and a 401/403 means the key is not accepted.
* - **Login** (any version, including ones from before API keys): a local account's username and password, with the classic endpoints
* `<console>/proxy/network/api/s/<site>/…` (UniFi OS) or `<host>:8443/api/s/<site>/…` (self-hosted). A read-only local account is enough; a Ubiquiti
* cloud (SSO) account with two-factor is not.
*
* It only ever reads. Wi-Fi passphrases are in the controller's answers on the login path; they are never copied out of this file's normalising functions, which
* list the fields they keep.
*
* The endpoints and field names are from Ubiquiti's published Integration API and the long-documented classic API, but have not been checked against a live
* controller here. Every field is read defensively (a missing or renamed one leaves that value blank rather than breaking the sync), and a device whose own detail
* cannot be read is still listed. If your controller answers differently, the Diagnostic Log has what it said.
*/
import * as http from "node:http";
import * as https from "node:https";
import { withDiagLogging } from "../../services/diagLog.js";
export interface UnifiConfig {
url: string;
apiKey?: string;
username?: string;
password?: string;
/** Only this site (its name as shown in the controller); blank reads them all. */
site?: string;
/** A self-hosted Network application rather than a UniFi OS console (no /proxy/network in front of the paths). */
selfHosted?: boolean;
insecure?: boolean;
}
export type UnifiDeviceKind = "gateway" | "switch" | "access_point" | "other";
export type UnifiDeviceState = "online" | "offline" | "updating" | "pending" | "other";
export interface UnifiDevice {
/** The MAC address, lower case, with colons. */
externalId: string;
mac: string;
name: string;
model: string | null;
kind: UnifiDeviceKind;
ip: string | null;
state: UnifiDeviceState;
uptimeSeconds: number | null;
firmware: string | null;
firmwareUpdatable: boolean;
/** The MAC of the device this one is connected through. */
uplinkExternalId: string | null;
siteName: string;
}
export interface UnifiNetwork {
externalId: string;
name: string;
enabled: boolean;
vlanId: number | null;
subnet: string | null;
purpose: string | null;
siteName: string;
}
export interface UnifiSsid {
externalId: string;
name: string;
enabled: boolean;
security: string | null;
networkName: string | null;
vlanId: number | null;
siteName: string;
}
export interface UnifiInventory {
mode: "api_key" | "login";
sites: string[];
devices: UnifiDevice[];
networks: UnifiNetwork[];
ssids: UnifiSsid[];
}
export interface UnifiAdapter {
ping(): Promise<{ ok: boolean; latencyMs?: number; error?: string }>;
fetchInventory(): Promise<UnifiInventory>;
}
// ─── Normalising (pure, exported for tests) ─────────────────────────────────
const str = (v: unknown): string | null => (typeof v === "string" && v.trim() !== "" ? v.trim() : null);
const num = (v: unknown): number | null => {
const n = typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : NaN;
return Number.isFinite(n) ? n : null;
};
const obj = (v: unknown): Record<string, unknown> => (v !== null && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {});
const list = (v: unknown): unknown[] => (Array.isArray(v) ? v : []);
/** "AA-BB-CC-DD-EE-FF" / "aabbccddeeff" / "AA:BB:…" → "aa:bb:cc:dd:ee:ff"; null if it isn't a MAC address. */
export function normaliseMac(value: unknown): string | null {
const hex = (str(value) ?? "").replace(/[^0-9a-fA-F]/g, "").toLowerCase();
return hex.length === 12 ? hex.match(/../g)!.join(":") : null;
}
const GATEWAY_MODEL = /^(udm|udr|uxg|ucg|usg|udw|dream\s*(machine|router)|cloud\s*gateway|gateway)/i;
export function deviceKind(model: string | null, features: string[], legacyType: string | null): UnifiDeviceKind {
const type = (legacyType ?? "").toLowerCase();
if (type === "ugw" || type === "udm" || type === "uxg" || type === "ucg" || (model && GATEWAY_MODEL.test(model))) return "gateway";
if (type === "uap" || features.includes("accessPoint")) return "access_point";
if (type === "usw" || features.includes("switching")) return "switch";
if (model && /^(uap|u6|u7|ap\b)/i.test(model)) return "access_point";
if (model && /^(usw|us-|flex|ultra)/i.test(model)) return "switch";
return "other";
}
/** The Integration API's device states. Only "offline" is a problem worth an alert; a device being adopted or updating is not. */
export function stateFromApi(state: unknown): UnifiDeviceState {
switch (String(state ?? "").toUpperCase()) {
case "ONLINE":
return "online";
case "OFFLINE":
case "CONNECTION_INTERRUPTED":
case "ISOLATED":
return "offline";
case "UPDATING":
return "updating";
case "PENDING_ADOPTION":
case "ADOPTING":
case "GETTING_READY":
return "pending";
default:
return "other";
}
}
/** The classic API's numeric states (1 connected, 0 disconnected, 4 upgrading, 5 provisioning, 6 heartbeat missed, 7 adopting, 11 isolated). */
export function stateFromLegacy(state: unknown): UnifiDeviceState {
switch (num(state)) {
case 1:
return "online";
case 0:
case 6:
case 11:
return "offline";
case 4:
return "updating";
case 5:
case 7:
return "pending";
default:
return "other";
}
}
/** One device from the Integration API: its list entry, its detail (for the uplink), and its latest statistics (for the uptime) — the last two may be missing. */
export function deviceFromApi(entry: unknown, detail: unknown, stats: unknown, siteName: string, macById: Map<string, string>): UnifiDevice | null {
const e = obj(entry);
const d = { ...e, ...obj(detail) };
const mac = normaliseMac(d.macAddress);
if (!mac) return null;
const model = str(d.model);
const uplinkId = str(obj(d.uplink).deviceId);
return {
externalId: mac,
mac,
name: str(d.name) ?? model ?? mac,
model,
kind: deviceKind(model, list(d.features).filter((f): f is string => typeof f === "string"), null),
ip: str(d.ipAddress),
state: stateFromApi(d.state),
uptimeSeconds: num(obj(stats).uptimeSec),
firmware: str(d.firmwareVersion),
firmwareUpdatable: d.firmwareUpdatable === true,
uplinkExternalId: uplinkId ? (macById.get(uplinkId) ?? null) : null,
siteName,
};
}
export function deviceFromLegacy(raw: unknown, siteName: string): UnifiDevice | null {
const d = obj(raw);
const mac = normaliseMac(d.mac);
if (!mac) return null;
const model = str(d.model) ?? str(d.shortname);
const up = obj(d.uplink);
return {
externalId: mac,
mac,
name: str(d.name) ?? model ?? mac,
model,
kind: deviceKind(model, [], str(d.type)),
ip: str(d.ip),
state: stateFromLegacy(d.state),
uptimeSeconds: num(d.uptime),
firmware: str(d.version),
firmwareUpdatable: d.upgradable === true,
uplinkExternalId: normaliseMac(up.uplink_mac) ?? normaliseMac(d.uplink_mac),
siteName,
};
}
export function networkFromApi(entry: unknown, detail: unknown, siteName: string): UnifiNetwork | null {
const d = { ...obj(entry), ...obj(detail) };
const id = str(d.id);
const name = str(d.name);
if (!id || !name) return null;
const v4 = obj(d.ipv4Configuration);
const host = str(v4.hostIpAddress);
const prefix = num(v4.prefixLength);
return {
externalId: id,
name,
enabled: d.enabled !== false,
vlanId: num(d.vlanId),
subnet: host && prefix !== null ? `${host}/${prefix}` : null,
purpose: str(d.management)?.toLowerCase() ?? null,
siteName,
};
}
export function networkFromLegacy(raw: unknown, siteName: string): UnifiNetwork | null {
const d = obj(raw);
const id = str(d._id);
const name = str(d.name);
if (!id || !name) return null;
return {
externalId: id,
name,
enabled: d.enabled !== false,
vlanId: d.vlan_enabled === false ? null : num(d.vlan),
subnet: str(d.ip_subnet),
purpose: str(d.purpose),
siteName,
};
}
const API_SECURITY: Record<string, string> = { OPEN: "Open", WPA2_PERSONAL: "WPA2", WPA3_PERSONAL: "WPA3", WPA2_WPA3_PERSONAL: "WPA2/WPA3", WPA2_ENTERPRISE: "WPA2 Enterprise", WPA3_ENTERPRISE: "WPA3 Enterprise" };
export function ssidFromApi(raw: unknown, networkNames: Map<string, string>, siteName: string): UnifiSsid | null {
const d = obj(raw);
const id = str(d.id);
const name = str(d.name);
if (!id || !name) return null;
const sec = str(obj(d.securityConfiguration).type);
const net = obj(d.network);
const networkId = str(net.networkId);
return {
externalId: id,
name,
enabled: d.enabled !== false,
security: sec ? (API_SECURITY[sec.toUpperCase()] ?? sec) : null,
networkName: networkId ? (networkNames.get(networkId) ?? null) : str(net.type)?.toUpperCase() === "NATIVE" ? "Default" : null,
vlanId: null,
siteName,
};
}
const LEGACY_SECURITY: Record<string, string> = { open: "Open", wpapsk: "WPA personal", wpaeap: "WPA enterprise" };
export function ssidFromLegacy(raw: unknown, networkNames: Map<string, string>, siteName: string): UnifiSsid | null {
const d = obj(raw);
const id = str(d._id);
const name = str(d.name);
if (!id || !name) return null;
const sec = str(d.security);
const networkId = str(d.networkconf_id);
const vlan = d.vlan_enabled === true ? num(d.vlan) : null;
return {
externalId: id,
name,
enabled: d.enabled !== false,
security: sec ? (LEGACY_SECURITY[sec.toLowerCase()] ?? sec) : null,
networkName: networkId ? (networkNames.get(networkId) ?? null) : null,
vlanId: vlan,
siteName,
};
}
// ─── HTTP ───────────────────────────────────────────────────────────────────
const REQUEST_TIMEOUT_MS = 15_000;
/** How many per-device / per-network requests are in flight at once: a controller is a small box. */
const CONCURRENCY = 4;
const PAGE = 200;
interface RawResponse {
status: number;
headers: http.IncomingHttpHeaders;
text: string;
}
function request(url: string, opts: { method?: "GET" | "POST"; headers?: Record<string, string>; body?: unknown; insecure: boolean }): Promise<RawResponse> {
return new Promise((resolve, reject) => {
const parsed = new URL(url);
const isHttps = parsed.protocol === "https:";
const lib = isHttps ? https : http;
const payload = opts.body === undefined ? null : JSON.stringify(opts.body);
const req = lib.request(
{
hostname: parsed.hostname,
port: parsed.port || (isHttps ? 443 : 80),
path: parsed.pathname + parsed.search,
method: opts.method ?? "GET",
headers: { Accept: "application/json", ...(payload ? { "Content-Type": "application/json", "Content-Length": String(Buffer.byteLength(payload)) } : {}), ...opts.headers },
timeout: REQUEST_TIMEOUT_MS,
...(isHttps ? { rejectUnauthorized: !opts.insecure } : {}),
},
(res) => {
let body = "";
res.setEncoding("utf8");
res.on("data", (chunk) => {
body += chunk;
});
res.on("end", () => resolve({ status: res.statusCode ?? 0, headers: res.headers, text: body }));
},
);
req.on("timeout", () => req.destroy(new Error(`timed out after ${REQUEST_TIMEOUT_MS / 1000}s`)));
req.on("error", reject);
if (payload) req.write(payload);
req.end();
});
}
function parseJson(res: RawResponse): any {
try {
return res.text ? JSON.parse(res.text) : null;
} catch {
return null;
}
}
/** Runs `work` over `items` a few at a time, keeping the order of the results. */
async function pooled<T, R>(items: T[], work: (item: T) => Promise<R>): Promise<R[]> {
const out: R[] = new Array(items.length);
let next = 0;
await Promise.all(
Array.from({ length: Math.min(CONCURRENCY, items.length) }, async () => {
while (next < items.length) {
const i = next++;
out[i] = await work(items[i]);
}
}),
);
return out;
}
const messageOf = (err: unknown) => (err instanceof Error ? err.message : String(err));
export function createUnifiAdapter(config: UnifiConfig): UnifiAdapter {
const insecure = config.insecure === true;
const root = config.url.replace(/\/+$/, "");
const wantSite = (config.site ?? "").trim().toLowerCase();
const useKey = typeof config.apiKey === "string" && config.apiKey.trim() !== "";
if (!useKey && !(config.username && config.password)) throw new Error("UniFi needs an API key, or a username and password");
// ── API key ──
async function apiGet(prefix: string, path: string): Promise<any> {
const res = await request(`${root}${prefix}${path}`, { headers: { "X-API-KEY": config.apiKey!.trim() }, insecure });
if (res.status === 401 || res.status === 403) throw new Error("UniFi did not accept the API key (HTTP " + res.status + ")");
if (res.status < 200 || res.status >= 300) throw new Error(`UniFi API error: HTTP ${res.status}${parseJson(res)?.message ? ` — ${parseJson(res).message}` : ""}`);
const body = parseJson(res);
if (body === null) throw new Error("UniFi answered with something that isn't JSON — is the address the controller's?");
return body;
}
/** Every page of a list endpoint ({offset, limit, count, totalCount, data}). */
async function apiPaged(prefix: string, path: string): Promise<unknown[]> {
const out: unknown[] = [];
for (let offset = 0; offset < 10_000; ) {
const body = await apiGet(prefix, `${path}${path.includes("?") ? "&" : "?"}offset=${offset}&limit=${PAGE}`);
const data = list(body?.data);
out.push(...data);
const total = num(body?.totalCount);
offset += data.length;
if (data.length === 0 || total === null || offset >= total) break;
}
return out;
}
let cachedPrefix: string | null = null;
async function apiPrefix(): Promise<string> {
if (cachedPrefix !== null) return cachedPrefix;
const candidates = config.selfHosted ? ["/integration/v1"] : ["/proxy/network/integration/v1", "/integration/v1"];
let last: unknown = null;
for (const prefix of candidates) {
try {
await apiGet(prefix, "/sites?limit=1");
cachedPrefix = prefix;
return prefix;
} catch (err) {
last = err;
// Only "not found" means this form of the address is the wrong one; a rejected key or a dead host will not be any better on the other.
if (!/HTTP 404/.test(messageOf(err))) throw err;
}
}
throw new Error(`UniFi has no Integration API at this address${messageOf(last) ? ` (${messageOf(last)})` : ""} — it needs Network 9 or later; for an older controller use a username and password`);
}
async function inventoryViaKey(): Promise<UnifiInventory> {
const prefix = await apiPrefix();
let sites = list(await apiPaged(prefix, "/sites")).map((s) => ({ id: str(obj(s).id), name: str(obj(s).name) ?? str(obj(s).internalReference) ?? "Default" }));
sites = sites.filter((s) => s.id);
if (wantSite) {
sites = sites.filter((s) => s.name.toLowerCase() === wantSite);
if (sites.length === 0) throw new Error(`UniFi has no site called “${config.site}”`);
}
const inventory: UnifiInventory = { mode: "api_key", sites: sites.map((s) => s.name), devices: [], networks: [], ssids: [] };
for (const site of sites) {
const base = `/sites/${site.id}`;
const entries = await apiPaged(prefix, `${base}/devices`);
const macById = new Map<string, string>();
for (const e of entries) {
const id = str(obj(e).id);
const mac = normaliseMac(obj(e).macAddress);
if (id && mac) macById.set(id, mac);
}
const details = await pooled(entries, async (e) => {
const id = str(obj(e).id);
if (!id) return { detail: null, stats: null };
// A device whose detail or statistics cannot be read is still listed, just without its uplink or uptime.
const [detail, stats] = await Promise.all([apiGet(prefix, `${base}/devices/${id}`).catch(() => null), apiGet(prefix, `${base}/devices/${id}/statistics/latest`).catch(() => null)]);
return { detail, stats };
});
entries.forEach((e, i) => {
const d = deviceFromApi(e, details[i].detail, details[i].stats, site.name, macById);
if (d) inventory.devices.push(d);
});
const netEntries = await apiPaged(prefix, `${base}/networks`).catch(() => []);
const netDetails = await pooled(netEntries, async (e) => {
const id = str(obj(e).id);
return id ? apiGet(prefix, `${base}/networks/${id}`).catch(() => null) : null;
});
const networkNames = new Map<string, string>();
netEntries.forEach((e, i) => {
const n = networkFromApi(e, netDetails[i], site.name);
if (n) {
inventory.networks.push(n);
networkNames.set(n.externalId, n.name);
}
});
for (const raw of await apiPaged(prefix, `${base}/wifi/broadcasts`).catch(() => [])) {
const s = ssidFromApi(raw, networkNames, site.name);
if (s) inventory.ssids.push(s);
}
}
return inventory;
}
// ── Login ──
interface Session {
prefix: string;
headers: Record<string, string>;
logout: () => Promise<void>;
}
async function login(): Promise<Session> {
const body = { username: config.username, password: config.password, remember: false };
// A UniFi OS console logs in at /api/auth/login and serves the Network application under /proxy/network; a self-hosted one at /api/login.
const attempts = config.selfHosted ? [{ path: "/api/login", prefix: "", os: false }] : [{ path: "/api/auth/login", prefix: "/proxy/network", os: true }, { path: "/api/login", prefix: "", os: false }];
let last: RawResponse | null = null;
for (const a of attempts) {
const res = await request(`${root}${a.path}`, { method: "POST", body, insecure });
last = res;
if (res.status === 404) continue;
if (res.status === 400 || res.status === 401 || res.status === 403) throw new Error("UniFi did not accept the username and password");
if (res.status < 200 || res.status >= 300) throw new Error(`UniFi login failed: HTTP ${res.status}`);
const cookies = list(res.headers["set-cookie"])
.map((c) => String(c).split(";")[0])
.filter(Boolean)
.join("; ");
if (!cookies) throw new Error("UniFi accepted the login but sent no session");
const headers: Record<string, string> = { Cookie: cookies };
const csrf = res.headers["x-csrf-token"] ?? res.headers["x-updated-csrf-token"];
if (typeof csrf === "string") headers["X-CSRF-Token"] = csrf;
return {
prefix: a.prefix,
headers,
// Best effort: give the session back rather than leave one open per sync.
logout: async () => {
try {
await request(`${root}${a.os ? "/api/auth/logout" : "/api/logout"}`, { method: "POST", headers, body: {}, insecure });
} catch {
// nothing to do about it
}
},
};
}
throw new Error(`UniFi has no login at this address${last ? ` (HTTP ${last.status})` : ""} — check the address, and the “self-hosted” box`);
}
async function legacyGet(session: Session, path: string): Promise<unknown[]> {
const res = await request(`${root}${session.prefix}${path}`, { headers: session.headers, insecure });
if (res.status === 401 || res.status === 403) throw new Error("UniFi did not allow this account to read that (HTTP " + res.status + ")");
if (res.status < 200 || res.status >= 300) throw new Error(`UniFi API error: HTTP ${res.status}`);
const body = parseJson(res);
if (body === null) throw new Error("UniFi answered with something that isn't JSON — is the address the controller's?");
return list(body.data);
}
async function inventoryViaLogin(): Promise<UnifiInventory> {
const session = await login();
try {
let sites = (await legacyGet(session, "/api/self/sites")).map((s) => ({ key: str(obj(s).name), name: str(obj(s).desc) ?? str(obj(s).name) ?? "Default" })).filter((s): s is { key: string; name: string } => !!s.key);
if (wantSite) {
sites = sites.filter((s) => s.name.toLowerCase() === wantSite || s.key.toLowerCase() === wantSite);
if (sites.length === 0) throw new Error(`UniFi has no site called “${config.site}”`);
}
const inventory: UnifiInventory = { mode: "login", sites: sites.map((s) => s.name), devices: [], networks: [], ssids: [] };
for (const site of sites) {
for (const raw of await legacyGet(session, `/api/s/${site.key}/stat/device`)) {
const d = deviceFromLegacy(raw, site.name);
if (d) inventory.devices.push(d);
}
const networkNames = new Map<string, string>();
for (const raw of await legacyGet(session, `/api/s/${site.key}/rest/networkconf`).catch(() => [])) {
const n = networkFromLegacy(raw, site.name);
if (n) {
inventory.networks.push(n);
networkNames.set(n.externalId, n.name);
}
}
for (const raw of await legacyGet(session, `/api/s/${site.key}/rest/wlanconf`).catch(() => [])) {
const s = ssidFromLegacy(raw, networkNames, site.name);
if (s) inventory.ssids.push(s);
}
}
return inventory;
} finally {
await session.logout();
}
}
async function fetchInventory(): Promise<UnifiInventory> {
return useKey ? inventoryViaKey() : inventoryViaLogin();
}
async function ping(): Promise<{ ok: boolean; latencyMs?: number; error?: string }> {
const start = Date.now();
try {
if (useKey) {
await apiPrefix();
} else {
const session = await login();
await session.logout();
}
return { ok: true, latencyMs: Date.now() - start };
} catch (err) {
return { ok: false, error: messageOf(err) };
}
}
return withDiagLogging("unifi", { ping, fetchInventory });
}
+9 -4
View File
@@ -2,7 +2,7 @@ import { Router } from "express";
import { eq } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { dependencies, servers } from "../db/schema.js";
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";
@@ -59,11 +59,12 @@ dependenciesRouter.get("/impact", asyncHandler(async (req, res) => {
dependenciesRouter.get("/graph", asyncHandler(async (_req, res) => {
const graph = await loadGraph();
const written = new Set(graph.rows.map((r) => `${nodeKey(r.fromType, r.fromId)}>${nodeKey(r.toType, r.toId)}`));
const edges: { from: string; to: string; kind: "written" | "runs-on" }[] = [];
const edges: { from: string; to: string; kind: "written" | "runs-on" | "uplink" }[] = [];
const taking = new Set<string>();
for (const [needing, needed] of graph.edges) {
for (const n of needed) {
edges.push({ from: n, to: needing, kind: written.has(`${needing}>${n}`) ? "written" : "runs-on" });
// A device connected through another is an uplink (the controller says so); a server's "runs on" is the other kind of link nobody wrote.
edges.push({ from: n, to: needing, kind: written.has(`${needing}>${n}`) ? "written" : needing.startsWith("device:") && n.startsWith("device:") ? "uplink" : "runs-on" });
taking.add(needing);
taking.add(n);
}
@@ -73,6 +74,7 @@ dependenciesRouter.get("/graph", asyncHandler(async (_req, res) => {
const serverRows = await db.select({ id: servers.id, lastSeenAt: servers.lastSeenAt, thresholds: servers.thresholds }).from(servers);
const serverById = new Map(serverRows.map((s) => [s.id, s]));
const intById = new Map(graph.intRows.map((i) => [i.id, i]));
const deviceById = new Map((await db.select({ id: networkDevices.id, state: networkDevices.state }).from(networkDevices)).map((d) => [d.id, d]));
const nodes = [...taking]
.map((key) => {
const [type, rawId] = key.split(":");
@@ -81,6 +83,9 @@ 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 === "device") {
const d = deviceById.get(id);
if (d) status = d.state === "online" ? "ok" : d.state === "offline" ? "bad" : d.state === "updating" ? "warn" : "unknown";
} else {
const i = intById.get(id);
if (i?.enabled) {
@@ -88,7 +93,7 @@ dependenciesRouter.get("/graph", asyncHandler(async (_req, res) => {
status = st === "failing" ? "bad" : st === "ok" ? "ok" : "unknown";
}
}
return { key, type: type as "server" | "integration", id, name: graph.names.get(key) ?? key, status, href: type === "server" ? `/servers/${id}` : "/integrations" };
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" };
})
.sort((a, b) => a.name.localeCompare(b.name));
res.json({ nodes, edges });
+17 -2
View File
@@ -2,7 +2,7 @@ import { Router, type Request, type Response } from "express";
import { eq } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { integrations, integrationCredentials, integrationTypes, servers } from "../db/schema.js";
import { integrations, integrationCredentials, integrationTypes, servers, type IntegrationType } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { encryptSecret } from "../crypto.js";
@@ -25,6 +25,8 @@ import { createPbsAdapter } from "../integrations/pbs/adapter.js";
import { createOsTicketAdapter } from "../integrations/osticket/adapter.js";
import { attachMatchedServers, summarizeMonitors, toMatchableServers } from "../services/uptimeKumaMatch.js";
import { getSourceStatus } from "../services/integrationHealthMonitor.js";
import { removeIntegrationData, syncUnifiIntegration } from "../services/unifiSync.js";
import { invalidateAlertsCache } from "../services/alerts.js";
import { asyncHandler } from "../utils/asyncHandler.js";
import { ID_PATTERNS, isValidId } from "../utils/pathSegment.js";
@@ -60,6 +62,13 @@ integrationsRouter.get("/", asyncHandler(async (_req, res) => {
const configValueSchema = z.union([z.string(), z.boolean()]);
/** What to tell the person when a form was submitted without something it needs. */
function missingMessage(type: IntegrationType, missing: string[]): string {
if (type === "unifi") return "UniFi needs an API key, or a username together with its password.";
const labels = (INTEGRATION_FIELDS[type] ?? []).filter((f) => missing.includes(f.key)).map((f) => f.label);
return `Fill in: ${labels.length > 0 ? labels.join(", ") : missing.join(", ")}.`;
}
const createIntegrationSchema = z.object({
type: z.enum(integrationTypes),
name: z.string().min(1).max(200),
@@ -79,7 +88,7 @@ integrationsRouter.post("/", requireRole("admin"), asyncHandler(async (req, res)
const missing = validateIntegrationConfig(type, config);
if (missing.length > 0) {
return res.status(400).json({ error: "missing_fields", fields: missing });
return res.status(400).json({ error: "missing_fields", fields: missing, message: missingMessage(type, missing) });
}
const { secretFields, nonSecretFields } = splitIntegrationConfig(type, config);
@@ -114,6 +123,9 @@ integrationsRouter.post("/", requireRole("admin"), asyncHandler(async (req, res)
detail: { type, name },
});
// A new UniFi controller is read at once, so its equipment is there when the person opens the page (not waited for: a slow controller must not slow this).
if (type === "unifi") void syncUnifiIntegration(created.id).then(() => invalidateAlertsCache());
res.status(201).json({
integration: {
id: created.id,
@@ -213,6 +225,8 @@ integrationsRouter.patch("/:id", requireRole("admin"), asyncHandler(async (req,
},
});
if (updated.type === "unifi" && updated.enabled && (parsed.data.config || parsed.data.enabled === true)) void syncUnifiIntegration(updated.id).then(() => invalidateAlertsCache());
res.json({
integration: {
id: updated.id,
@@ -288,6 +302,7 @@ integrationsRouter.delete("/:id", requireRole("admin"), asyncHandler(async (req,
.where(eq(servers.proxmoxIntegrationId, id))
.returning({ id: servers.id });
if (existing.type === "unifi") await removeIntegrationData(id);
await db.delete(integrations).where(eq(integrations.id, id));
if (existing.credentialId) {
await db.delete(integrationCredentials).where(eq(integrationCredentials.id, existing.credentialId));
+11 -7
View File
@@ -2,7 +2,7 @@ import { Router } from "express";
import { and, eq, inArray } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { dnsProviders, integrations, maintenanceAliases, maintenanceSchedules, maintenanceTargetTypes, maintenanceWindows, servers } from "../db/schema.js";
import { dnsProviders, integrations, maintenanceAliases, maintenanceSchedules, maintenanceTargetTypes, maintenanceWindows, networkDevices, servers } from "../db/schema.js";
import { deleteSchedule, isValidTimeZone, materializeSchedules, occurrencesBetween, removeFutureWindows, targetsOf } from "../services/maintenanceSchedules.js";
import { hostOfAddress } from "../services/kumaTargets.js";
import { invalidateAlertsCache } from "../services/alerts.js";
@@ -37,10 +37,11 @@ maintenanceRouter.get("/", asyncHandler(async (_req, res) => {
const upcoming = await describe(await listUpcomingWindows());
upcoming.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
const [serverRows, integrationRows, providerRows] = await Promise.all([
const [serverRows, integrationRows, providerRows, deviceRows] = await Promise.all([
db.select({ id: servers.id, name: servers.name }).from(servers).orderBy(servers.name),
db.select({ id: integrations.id, name: integrations.name, type: integrations.type }).from(integrations).orderBy(integrations.name),
db.select({ id: dnsProviders.id, name: dnsProviders.name, providerType: dnsProviders.providerType }).from(dnsProviders).orderBy(dnsProviders.name),
db.select({ id: networkDevices.id, name: networkDevices.name, kind: networkDevices.kind }).from(networkDevices).orderBy(networkDevices.name),
]);
const aliases = [];
for (const a of await db.select().from(maintenanceAliases).orderBy(maintenanceAliases.address)) {
@@ -48,7 +49,7 @@ maintenanceRouter.get("/", asyncHandler(async (_req, res) => {
if (!target) continue; // target was deleted — the alias has nothing left to point at
aliases.push({ id: a.id, address: a.address, targetType: a.targetType, targetId: a.targetId, targetName: target.name, targetKind: target.kind });
}
res.json({ windows, upcoming, aliases, targets: { servers: serverRows, integrations: integrationRows, dnsProviders: providerRows } });
res.json({ windows, upcoming, aliases, targets: { servers: serverRows, integrations: integrationRows, dnsProviders: providerRows, devices: deviceRows } });
}));
const startSchema = z.object({
@@ -77,8 +78,8 @@ maintenanceRouter.post("/", requireRole("operator"), asyncHandler(async (req, re
}
// What depends on it goes down with it, so it is silenced for the same time (and says why).
const alsoSilenced: { type: "server" | "integration"; id: number; name: string }[] = [];
if (withDependents && (targetType === "server" || targetType === "integration")) {
const alsoSilenced: { type: "server" | "integration" | "device"; id: number; name: string }[] = [];
if (withDependents && (targetType === "server" || targetType === "integration" || targetType === "device")) {
const impact = await impactOf(targetType, targetId);
for (const d of impact?.dependents ?? []) {
const also = await startOrExtendWindow(d.type, d.id, minutes, `Depends on ${result.target.name}${reason ? ` — ${reason}` : ""}`.slice(0, 200), createdBy);
@@ -226,7 +227,7 @@ maintenanceRouter.delete("/aliases/:id", requireRole("operator"), asyncHandler(a
}));
const bulkSchema = z.object({
scope: z.enum(["everything", "servers", "integrations", "dns_providers"]),
scope: z.enum(["everything", "servers", "integrations", "dns_providers", "devices"]),
minutes: z.number().int().min(5).max(7 * 24 * 60),
reason: z.string().max(200).optional(),
});
@@ -243,13 +244,16 @@ maintenanceRouter.post("/bulk", requireRole("operator"), asyncHandler(async (req
}
const { scope, minutes, reason } = parsed.data;
const targets: { type: "server" | "integration" | "dns_provider"; id: number }[] = [];
const targets: { type: "server" | "integration" | "dns_provider" | "device"; id: number }[] = [];
if (scope === "everything" || scope === "servers") {
for (const s of await db.select({ id: servers.id }).from(servers)) targets.push({ type: "server", id: s.id });
}
if (scope === "everything" || scope === "integrations") {
for (const i of await db.select({ id: integrations.id }).from(integrations).where(eq(integrations.enabled, true))) targets.push({ type: "integration", id: i.id });
}
if (scope === "everything" || scope === "devices") {
for (const d of await db.select({ id: networkDevices.id }).from(networkDevices)) targets.push({ type: "device", id: d.id });
}
if (scope === "everything" || scope === "dns_providers") {
for (const p of await db.select({ id: dnsProviders.id }).from(dnsProviders).where(eq(dnsProviders.enabled, true))) targets.push({ type: "dns_provider", id: p.id });
}
+84
View File
@@ -0,0 +1,84 @@
import { Router } from "express";
import { eq } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { integrations, networkDevices, networkSegments } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { invalidateAlertsCache } from "../services/alerts.js";
import { dependentsOf, loadGraph, needsOfNode, nodeKey } from "../services/dependencies.js";
import { activeSubjects } from "../services/maintenance.js";
import { syncAllUnifi, syncStatuses, syncUnifiIntegration } from "../services/unifiSync.js";
import { asyncHandler } from "../utils/asyncHandler.js";
export const networkRouter = Router();
networkRouter.use(requireAuth);
/**
* The network equipment read from UniFi controllers: devices with their state, address, uptime and what they are connected through, the networks and the Wi-Fi
* names. Everyone signed in can see it (it is the same picture the dependency map and the alerts draw on); only starting a fresh read needs more.
*/
networkRouter.get("/", asyncHandler(async (_req, res) => {
const [intRows, devices, segments, statuses, graph, silenced] = await Promise.all([
db.select({ id: integrations.id, name: integrations.name, enabled: integrations.enabled }).from(integrations).where(eq(integrations.type, "unifi")),
db.select().from(networkDevices),
db.select().from(networkSegments),
syncStatuses(),
loadGraph(),
activeSubjects(),
]);
const intName = new Map(intRows.map((i) => [i.id, i.name]));
const byExternal = new Map(devices.map((d) => [`${d.integrationId}:${d.externalId}`, d]));
res.json({
integrations: intRows.map((i) => ({ id: i.id, name: i.name, enabled: i.enabled, status: statuses[i.id] ?? null })),
devices: devices
.map((d) => {
const key = nodeKey("device", d.id);
const uplink = d.uplinkExternalId ? byExternal.get(`${d.integrationId}:${d.uplinkExternalId}`) : undefined;
return {
id: d.id,
integrationId: d.integrationId,
integrationName: intName.get(d.integrationId) ?? "UniFi",
siteName: d.siteName,
name: d.name,
model: d.model,
kind: d.kind,
ip: d.ip,
mac: d.mac,
state: d.state,
uptimeSeconds: d.uptimeSeconds,
firmware: d.firmware,
firmwareUpdatable: d.firmwareUpdatable,
uplink: uplink ? { id: uplink.id, name: uplink.name } : null,
offlineSince: d.offlineSince,
lastOnlineAt: d.lastOnlineAt,
updatedAt: d.updatedAt,
// How many things depend on it (directly or through others), and how many it needs: what the dependency map says about it.
dependents: dependentsOf(graph.edges, key).length,
needs: needsOfNode(graph.edges, key).length,
inMaintenance: silenced.has(key),
};
})
.sort((a, b) => a.name.localeCompare(b.name)),
networks: segments.filter((s) => s.kind === "network").map(({ kind: _k, ...s }) => ({ ...s, integrationName: intName.get(s.integrationId) ?? "UniFi" })).sort((a, b) => (a.vlanId ?? 0) - (b.vlanId ?? 0) || a.name.localeCompare(b.name)),
ssids: segments.filter((s) => s.kind === "ssid").map(({ kind: _k, ...s }) => ({ ...s, integrationName: intName.get(s.integrationId) ?? "UniFi" })).sort((a, b) => a.name.localeCompare(b.name)),
});
}));
const syncSchema = z.object({ integrationId: z.number().int().positive().optional() });
// Reads the controller(s) now instead of waiting for the next pass.
networkRouter.post("/sync", requireRole("operator"), asyncHandler(async (req, res) => {
const parsed = syncSchema.safeParse(req.body ?? {});
if (!parsed.success) return res.status(400).json({ error: "invalid_body" });
if (parsed.data.integrationId !== undefined) {
const [row] = await db.select({ id: integrations.id, type: integrations.type }).from(integrations).where(eq(integrations.id, parsed.data.integrationId)).limit(1);
if (!row || row.type !== "unifi") return res.status(404).json({ error: "not_found", message: "That isn't a UniFi integration." });
const status = await syncUnifiIntegration(row.id);
invalidateAlertsCache();
return res.json({ statuses: { [row.id]: status } });
}
const statuses = await syncAllUnifi();
invalidateAlertsCache();
res.json({ statuses });
}));
+4 -2
View File
@@ -2,7 +2,7 @@ import { Router } from "express";
import { and, eq } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { dnsProviders, integrations, maintenanceTargetTypes, runbooks, servers } from "../db/schema.js";
import { dnsProviders, integrations, maintenanceTargetTypes, networkDevices, runbooks, servers } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { describeTarget } from "../services/maintenance.js";
@@ -39,16 +39,18 @@ runbooksRouter.get("/", asyncHandler(async (req, res) => {
// What there is, everywhere, by title only — so a page can show a "runbook" button exactly where one exists, without fetching the texts.
// Notes for something that has since been removed are left out.
runbooksRouter.get("/summary", asyncHandler(async (_req, res) => {
const [rows, serverIds, integrationIds, providerIds] = await Promise.all([
const [rows, serverIds, integrationIds, providerIds, deviceIds] = await Promise.all([
db.select({ id: runbooks.id, targetType: runbooks.targetType, targetId: runbooks.targetId, category: runbooks.category, title: runbooks.title }).from(runbooks),
db.select({ id: servers.id }).from(servers),
db.select({ id: integrations.id }).from(integrations),
db.select({ id: dnsProviders.id }).from(dnsProviders),
db.select({ id: networkDevices.id }).from(networkDevices),
]);
const exists = {
server: new Set(serverIds.map((r) => r.id)),
integration: new Set(integrationIds.map((r) => r.id)),
dns_provider: new Set(providerIds.map((r) => r.id)),
device: new Set(deviceIds.map((r) => r.id)),
};
res.json({ runbooks: rows.filter((r) => exists[r.targetType].has(r.targetId)) });
}));
+1 -1
View File
@@ -144,7 +144,7 @@ const updateSchema = z.object({
.partial()
.optional(),
healthChecks: z
.object({ serverOfflineMinutes: z.number().int().min(15).max(10080), diskUsagePercent: z.number().int().min(50).max(99), domainWarnDays: z.number().int().min(1).max(365), diskForecastDays: z.number().int().min(0).max(90), backupStaleHours: z.number().int().min(0).max(2160), restoreTestDays: z.number().int().min(0).max(730), newPortAlerts: z.boolean(), flapRaises: z.number().int().min(0).max(20) })
.object({ serverOfflineMinutes: z.number().int().min(15).max(10080), diskUsagePercent: z.number().int().min(50).max(99), domainWarnDays: z.number().int().min(1).max(365), diskForecastDays: z.number().int().min(0).max(90), backupStaleHours: z.number().int().min(0).max(2160), restoreTestDays: z.number().int().min(0).max(730), newPortAlerts: z.boolean(), flapRaises: z.number().int().min(0).max(20), deviceOfflineMinutes: z.number().int().min(5).max(1440) })
.partial()
.optional(),
quietHours: z
+1 -1
View File
@@ -26,7 +26,7 @@ export interface Alert {
/** Raised and cleared over and over: its raised and cleared messages are being held back (services/flapGuard.ts). */
flapping?: boolean;
/** What a maintenance window would have to be on to silence it, when there is such a thing — which is what "Silence" acts on. */
target: { type: "server" | "integration" | "dns_provider"; id: number; name: string } | null;
target: { type: "server" | "integration" | "dns_provider" | "device"; id: number; name: string } | null;
}
/** One integration that couldn't be read while collecting — so the page never mistakes "couldn't check" for "all clear". */
+28 -15
View File
@@ -11,7 +11,7 @@
*/
import { eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { endpointChecks, heartbeats, integrations, secrets, servers } from "../db/schema.js";
import { endpointChecks, heartbeats, integrations, networkDevices, secrets, servers } from "../db/schema.js";
import { disksFillingSoon, getServerMetrics } from "./serverMetrics.js";
import { diskLimit, effectiveThresholds, parseThresholds } from "./serverThresholds.js";
import { getBackupCoverage, staleBackups } from "./backupCoverage.js";
@@ -64,6 +64,7 @@ const SOURCES: Record<string, { label: string; link: string }> = {
pbs: { label: "Proxmox Backup", link: "/pbs" },
uptimekuma: { label: "Uptime Kuma", link: "/uptime-kuma" },
osticket: { label: "osTicket", link: "/osticket" },
unifi: { label: "UniFi", link: "/network/devices" },
secrets: { label: "Secrets", link: "/secrets" },
domains: { label: "Domains", link: "/dns?view=domains" },
endpoint: { label: "Endpoint", link: "/endpoints" },
@@ -80,6 +81,8 @@ const SEVERITY_ORDER: Record<AlertSeverity, number> = { critical: 0, warning: 1,
/** Which kind of source, and which one, a health/automation condition key belongs to. */
function originOfConditionKey(key: string): { type: string; id: number | null; category: AlertCategory } {
const device = /^offline:device:(\d+)$/.exec(key);
if (device) return { type: "unifi", id: Number(device[1]), category: "offline" };
let m = /^(?:offline|disk|failed-units|smart|zfs|new-port):server:(\d+)/.exec(key);
if (m) return { type: "server", id: Number(m[1]), category: key.startsWith("offline") ? "offline" : key.startsWith("failed-units") ? "services" : key.startsWith("new-port") ? "monitoring" : "disk" };
m = /^disk:proxmox:(\d+):/.exec(key);
@@ -110,16 +113,17 @@ export async function collectAlerts(): Promise<AlertsReport> {
const intRows = await db.select({ id: integrations.id, name: integrations.name, type: integrations.type, enabled: integrations.enabled }).from(integrations);
const intById = new Map(intRows.map((r) => [r.id, r]));
const serverNames = new Map((await db.select({ id: servers.id, name: servers.name }).from(servers)).map((r) => [r.id, r.name]));
const deviceNames = new Map((await db.select({ id: networkDevices.id, name: networkDevices.name }).from(networkDevices)).map((r) => [r.id, r.name]));
/** The thing a maintenance window would go on to silence an alert about `subject` ("server:3", "integration:1"). */
const targetOf = (type: "server" | "integration" | "dns_provider", id: number): Alert["target"] => ({
const targetOf = (type: "server" | "integration" | "dns_provider" | "device", id: number): Alert["target"] => ({
type,
id,
name: (type === "server" ? serverNames.get(id) : type === "integration" ? intById.get(id)?.name : undefined) ?? `${type} #${id}`,
name: (type === "server" ? serverNames.get(id) : type === "device" ? deviceNames.get(id) : type === "integration" ? intById.get(id)?.name : undefined) ?? `${type} #${id}`,
});
const targetOfSubject = (subject: string | null): Alert["target"] => {
const m = /^(server|integration|dns_provider):(\d+)$/.exec(subject ?? "");
return m ? targetOf(m[1] as "server" | "integration" | "dns_provider", Number(m[2])) : null;
const m = /^(server|integration|dns_provider|device):(\d+)$/.exec(subject ?? "");
return m ? targetOf(m[1] as "server" | "integration" | "dns_provider" | "device", Number(m[2])) : null;
};
const integrationTarget = (id: number): Alert["target"] => targetOf("integration", id);
/** Integration-down alerts are per kind of service; a window on any integration of that kind silences them, so offer the first. */
@@ -167,6 +171,9 @@ export async function collectAlerts(): Promise<AlertsReport> {
// The servers found to be offline, for the integration failures that one may explain: the server check fills it in (and it is empty if that check fails).
let offlineKnown!: (ids: Set<number>) => void;
const offlineServers = new Promise<Set<number>>((resolve) => (offlineKnown = resolve));
// The same for network devices, which can explain a service that has stopped answering.
let devicesKnown!: (ids: Set<number>) => void;
const offlineDeviceIds = new Promise<Set<number>>((resolve) => (devicesKnown = resolve));
await Promise.all([
check("Server and storage health", async () => {
@@ -182,38 +189,44 @@ export async function collectAlerts(): Promise<AlertsReport> {
const conditions = evaluateHealth(snapshot, healthChecks, now, { skipServers: grace > 0 });
// A server that is down because the one it runs on is down is folded under that one.
const offlineIds = new Set<number>();
const offlineDevices = new Set<number>();
for (const c of conditions) {
const m = /^offline:server:(\d+)$/.exec(c.key);
if (m) offlineIds.add(Number(m[1]));
const m = /^offline:(server|device):(\d+)$/.exec(c.key);
if (m) (m[1] === "server" ? offlineIds : offlineDevices).add(Number(m[2]));
}
// (Or because of a service it needs that is failing, or a server it needs that needs one.)
offlineKnown(offlineIds);
const cover = await dependencyCover(offlineIds, getFailingSources().map((f) => f.source));
devicesKnown(offlineDevices);
const cover = await dependencyCover(offlineIds, getFailingSources().map((f) => f.source), offlineDevices);
for (const c of conditions) {
const origin = originOfConditionKey(c.key);
const subject = subjectOfConditionKey(c.key);
const offlineId = /^offline:server:(\d+)$/.exec(c.key)?.[1];
const parentOf = offlineId ? cover.cause.get(`server:${offlineId}`) : undefined;
const offlineMatch = /^offline:(server|device):(\d+)$/.exec(c.key);
const offlineNode = offlineMatch ? `${offlineMatch[1]}:${offlineMatch[2]}` : undefined;
const parentOf = offlineNode ? cover.cause.get(offlineNode) : undefined;
push({
causedBy: parentOf !== undefined ? { name: cover.graph.names.get(parentOf) ?? parentOf, alertId: alertIdOfNode(parentOf, cover.graph) ?? undefined } : undefined,
affects: offlineId ? cover.taken.get(`server:${offlineId}`)?.sort((a, b) => a.localeCompare(b)) : undefined,
affects: offlineNode ? cover.taken.get(offlineNode)?.sort((a, b) => a.localeCompare(b)) : undefined,
category: origin.category,
severity: c.severity ?? "warning",
type: origin.type,
message: c.message,
key: c.key,
link: origin.type === "server" && origin.id !== null ? `/servers/${origin.id}` : undefined,
link: origin.type === "server" && origin.id !== null ? `/servers/${origin.id}` : origin.type === "unifi" ? "/network/devices" : undefined,
silenced: subject !== null && subjects.has(subject), target: targetOfSubject(subject),
});
}
// Integrations the check couldn't read this time. (A whole-integration entry covers its nodes, so skip those.)
for (const h of held) {
const m = /^(proxmox|synology):(\d+)(?::(.+))?$/.exec(h);
const m = /^(proxmox|synology|unifi):(\d+)(?::(.+))?$/.exec(h);
if (!m || (m[3] && held.has(`${m[1]}:${m[2]}`))) continue;
const row = intById.get(Number(m[2]));
cannotCheck(`${SOURCES[m[1]].label} “${row?.name ?? `#${m[2]}`}”${m[3] ? ` (node ${m[3]})` : ""}`, "couldn't be read — see the Diagnostic Log", "Server and storage health");
}
}).finally(() => offlineKnown(new Set())),
}).finally(() => {
offlineKnown(new Set());
devicesKnown(new Set());
}),
check("Automation runs", async () => {
const { items, held } = await collectAutomation();
@@ -506,7 +519,7 @@ export async function collectAlerts(): Promise<AlertsReport> {
const { notifications } = await getSettings();
const failing = getFailingSources();
// A failure explained by something it needs that is down is folded under that, like a guest under its host.
const cover = failing.length > 0 ? await dependencyCover(await offlineServers, failing.map((f) => f.source)).catch(() => null) : null;
const cover = failing.length > 0 ? await dependencyCover(await offlineServers, failing.map((f) => f.source), await offlineDeviceIds).catch(() => null) : null;
for (const f of failing) {
const cause = cover ? integrationTypeCause(f.source, cover) : null;
const affects = cover ? takenByType(f.source, cover) : [];
+1 -1
View File
@@ -41,7 +41,7 @@ export interface SilenceUndo {
restored: { id: number; endsAt: string; reason: string | null }[];
}
type Target = { type: "server" | "integration" | "dns_provider"; id: number };
type Target = { type: "server" | "integration" | "dns_provider" | "device"; id: number };
/** Puts each target under maintenance (and, if asked, what depends on a server). Targets that are already under it have their window extended. */
export async function silenceTargets(targets: Target[], minutes: number, reason: string | null, createdBy: string, withDependents: boolean, now: Date = new Date()): Promise<{ silenced: { type: string; id: number; name: string }[]; skipped: Skipped[]; undo: SilenceUndo | null }> {
+37 -14
View File
@@ -3,14 +3,15 @@
* server that needs a service (a guest that only exists while Proxmox answers). When the thing depended on is down, the things that need it
* are down too — and only the one that matters is worth an alert, so the rest are folded under it: shown, not announced.
*
* The graph is the "runs on" links of servers (set by hand or worked out from Proxmox, see serverParents.ts) plus the dependencies written
* here. Servers and integrations are the things that can be down and be needed. (DNS providers raise no alerts of their own, so there is
* The graph is the "runs on" links of servers (set by hand or worked out from Proxmox, see serverParents.ts), the uplinks of network devices (which
* device each is connected through, as a UniFi controller says), plus the dependencies written here. Servers, network devices and integrations are the things
* 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.
*/
import { eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { dependencies, integrations, servers } from "../db/schema.js";
import { dependencies, integrations, networkDevices, servers } from "../db/schema.js";
import { getInternalFlag } from "./settingsStore.js";
import { listActiveWindows } from "./maintenance.js";
import { loadParentRows, resolveParents, type ParentLink } from "./serverParents.js";
@@ -18,7 +19,7 @@ import { loadParentRows, resolveParents, type ParentLink } from "./serverParents
/** 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"] as const;
export const nodeTypes = ["server", "integration", "device"] as const;
export type NodeType = (typeof nodeTypes)[number];
export const nodeKey = (type: NodeType, id: number) => `${type}:${id}`;
@@ -128,26 +129,43 @@ export interface Graph {
}
export async function loadGraph(): Promise<Graph> {
const [serverRows, intRows, depRows, parentRows] = await Promise.all([
const [serverRows, intRows, depRows, parentRows, deviceRows] = await Promise.all([
db.select({ id: servers.id, name: servers.name }).from(servers),
db.select({ id: integrations.id, name: integrations.name, type: integrations.type, enabled: integrations.enabled }).from(integrations),
db.select().from(dependencies),
loadParentRows(),
db.select({ id: networkDevices.id, name: networkDevices.name, integrationId: networkDevices.integrationId, externalId: networkDevices.externalId, uplinkExternalId: networkDevices.uplinkExternalId }).from(networkDevices),
]);
const names = new Map<string, string>();
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);
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]);
return { edges: buildEdges(resolveParents(parentRows), rows, (k) => names.has(k)), names, rows, instances, intRows };
// A device needs the one it is connected through: the controller says so, and nobody has to write it.
const uplinks = uplinkEdges(deviceRows);
return { edges: buildEdges(resolveParents(parentRows), [...rows, ...uplinks], (k) => names.has(k)), names, rows, instances, intRows };
}
/** The edges from each device to the device it is connected through, from what the controller reports; a device whose uplink is not (or no longer) known has none. */
export function uplinkEdges(devices: { id: number; integrationId: number; externalId: string; uplinkExternalId: string | null }[]): DependencyEdge[] {
const idOf = new Map(devices.map((d) => [`${d.integrationId}:${d.externalId}`, d.id]));
const out: DependencyEdge[] = [];
for (const d of devices) {
if (!d.uplinkExternalId) continue;
const to = idOf.get(`${d.integrationId}:${d.uplinkExternalId}`);
if (to !== undefined && to !== d.id) out.push({ fromType: "device", fromId: d.id, toType: "device", toId: to });
}
return out;
}
/** The id of the alert about a node being down, when it has one (a server's "offline", a kind of service's "failing"). */
export function alertIdOfNode(key: string, graph: Graph): string | null {
const m = /^(server|integration):(\d+)$/.exec(key);
const m = /^(server|integration|device):(\d+)$/.exec(key);
if (!m) return null;
if (m[1] === "server") return `offline:offline:server:${m[2]}`;
if (m[1] === "device") return `offline:offline:device:${m[2]}`;
const row = graph.intRows.find((r) => r.id === Number(m[2]));
return row ? `integration:failing:${row.type}` : null;
}
@@ -190,11 +208,12 @@ export interface Cover {
graph: Graph;
}
/** Works out what is down because of what, given the servers that are offline and the kinds of integration that are failing. */
export async function dependencyCover(offlineServerIds: Iterable<number>, failingTypes: Iterable<string>): Promise<Cover> {
/** Works out what is down because of what, given the servers and network devices that are offline and the kinds of integration that are failing. */
export async function dependencyCover(offlineServerIds: Iterable<number>, failingTypes: Iterable<string>, offlineDeviceIds: Iterable<number> = []): Promise<Cover> {
const graph = await loadGraph();
const down = new Set<string>();
for (const id of offlineServerIds) down.add(nodeKey("server", id));
for (const id of offlineDeviceIds) down.add(nodeKey("device", id));
const failing = new Set(failingTypes);
for (const [type, ids] of graph.instances) if (failing.has(type)) for (const id of ids) down.add(nodeKey("integration", id));
const cause = coveredNodes(down, graph.edges);
@@ -223,15 +242,15 @@ export function takenByType(type: string, cover: Cover): string[] {
return out;
}
/** The servers the health monitor is announcing as offline (or holding back as explained), from what it last stored. */
export async function offlineServerIdsFromState(): Promise<number[]> {
/** The servers or network devices the health monitor is announcing as offline (or holding back as explained), from what it last stored. */
async function offlineIdsFromState(kind: "server" | "device"): Promise<number[]> {
try {
const raw = await getInternalFlag(HEALTH_STATE_FLAG);
if (!raw) return [];
const ids: number[] = [];
for (const key of Object.keys(JSON.parse(raw) as Record<string, unknown>)) {
const m = /^offline:server:(\d+)$/.exec(key);
if (m) ids.push(Number(m[1]));
const m = /^offline:(server|device):(\d+)$/.exec(key);
if (m && m[1] === kind) ids.push(Number(m[2]));
}
return ids;
} catch {
@@ -239,13 +258,16 @@ export async function offlineServerIdsFromState(): Promise<number[]> {
}
}
export const offlineServerIdsFromState = () => offlineIdsFromState("server");
export const offlineDeviceIdsFromState = () => offlineIdsFromState("device");
/**
* Whether a kind of integration that has started failing is failing because of something it needs that is down — a server the health
* monitor says is offline, or another service that is failing. Never throws: a problem here must not swallow a real outage.
*/
export async function integrationCausedBy(type: string, failingTypes: string[]): Promise<{ name: string } | null> {
try {
const cover = await dependencyCover(await offlineServerIdsFromState(), failingTypes);
const cover = await dependencyCover(await offlineServerIdsFromState(), failingTypes, await offlineDeviceIdsFromState());
return integrationTypeCause(type, cover);
} catch (err) {
console.error("[dependencies] couldn't work out whether a failure is explained:", err);
@@ -254,6 +276,7 @@ export async function integrationCausedBy(type: string, failingTypes: string[]):
}
export async function nodeExists(type: NodeType, id: number): Promise<boolean> {
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;
}
+53 -9
View File
@@ -1,12 +1,13 @@
import { eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { integrations, serverPorts, servers } from "../db/schema.js";
import { integrations, networkDevices, serverPorts, servers } from "../db/schema.js";
import { loadIntegrationConfig } from "../integrations/loadIntegration.js";
import { createProxmoxAdapter, type ProxmoxNodeStats } from "../integrations/proxmox/adapter.js";
import { createSynologyAdapter, type SynologyStorageInfo } from "../integrations/synology/adapter.js";
import { notifyHealthIssues, notifyHealthRecovered } from "./notify.js";
import { recordAudit } from "./audit.js";
import { getInternalFlag, getSettings, setInternalFlag } from "./settingsStore.js";
import { isFresh, syncStatuses } from "./unifiSync.js";
import { activeSubjects, subjectOfConditionKey } from "./maintenance.js";
import { dependencyCover, HEALTH_STATE_FLAG } from "./dependencies.js";
import { getFailingSources } from "./integrationHealthMonitor.js";
@@ -54,14 +55,23 @@ export interface SynologySnapshot {
integrationName: string;
storage: SynologyStorageInfo;
}
/** The network equipment of one UniFi controller, as last read; only offered when that reading is recent enough to be believed. */
export interface UnifiSnapshot {
integrationId: number;
integrationName: string;
devices: { id: number; name: string; kind: string; model: string | null; state: string; offlineSince: string | null }[];
}
export interface HealthSnapshot {
servers: ServerSnapshot[];
proxmox: ProxmoxSnapshot[];
synology: SynologySnapshot[];
unifi?: UnifiSnapshot[];
}
export interface Thresholds {
serverOfflineMinutes: number;
diskUsagePercent: number;
/** Minutes a network device may be offline before it is raised (10 if left out). */
deviceOfflineMinutes?: number;
}
// ─── Formatting helpers ─────────────────────────────────────────────────────
@@ -145,6 +155,21 @@ export function evaluateHealth(snapshot: HealthSnapshot, thresholds: Thresholds,
}
}
for (const u of snapshot.unifi ?? []) {
const limitMs = (thresholds.deviceOfflineMinutes ?? 10) * 60_000;
for (const d of u.devices) {
if (d.state !== "offline" || !d.offlineSince) continue;
const age = now - parseTimestamp(d.offlineSince);
if (!Number.isFinite(age) || age <= limitMs) continue;
out.push({
key: `offline:device:${d.id}`,
source: `unifi:${u.integrationId}`,
message: `${d.name} (${d.kind.replace("_", " ")}${d.model ? `, ${d.model}` : ""}) has been offline for ${formatDuration(age)}`,
severity: "critical",
});
}
}
for (const px of snapshot.proxmox) {
const seenShared = new Set<string>();
for (const node of px.nodes) {
@@ -331,6 +356,24 @@ export async function collectSnapshot(): Promise<{ snapshot: HealthSnapshot; hel
.from(integrations)
.where(eq(integrations.enabled, true));
// UniFi controllers are read by their own pass every few minutes; what is judged here is what that pass stored, and only while it is recent.
const unifiRows = rows.filter((r) => r.type === "unifi");
if (unifiRows.length > 0) {
const statuses = await syncStatuses();
const nowMs = Date.now();
for (const row of unifiRows) {
if (!isFresh(statuses[row.id], nowMs)) {
held.add(`unifi:${row.id}`);
continue;
}
const devices = await db
.select({ id: networkDevices.id, name: networkDevices.name, kind: networkDevices.kind, model: networkDevices.model, state: networkDevices.state, offlineSince: networkDevices.offlineSince })
.from(networkDevices)
.where(eq(networkDevices.integrationId, row.id));
(snapshot.unifi ??= []).push({ integrationId: row.id, integrationName: row.name, devices });
}
}
for (const row of rows) {
if (row.type !== "proxmox" && row.type !== "synology") continue;
try {
@@ -410,24 +453,25 @@ export async function runHealthCheck(now: number = Date.now()): Promise<{ added:
const current = evaluateHealth(snapshot, healthChecks, now, { skipServers: inGrace });
// A server that is down because the one it runs on is down is folded under that one: recorded, but not announced on its own.
const offlineIds = new Set<number>();
const offlineDevices = new Set<number>();
for (const c of current) {
const m = /^offline:server:(\d+)$/.exec(c.key);
if (m) offlineIds.add(Number(m[1]));
const m = /^offline:(server|device):(\d+)$/.exec(c.key);
if (m) (m[1] === "server" ? offlineIds : offlineDevices).add(Number(m[2]));
}
// (Also when it needs a service that is failing, or runs on a server that needs one.)
const cover = await dependencyCover(offlineIds, getFailingSources().map((f) => f.source));
// (Also when it needs a service that is failing, or runs on a server that needs one, or is connected through a device that is down.)
const cover = await dependencyCover(offlineIds, getFailingSources().map((f) => f.source), offlineDevices);
const coveredKeys = new Set<string>();
for (const child of cover.cause.keys()) {
const m = /^server:(\d+)$/.exec(child);
if (m) coveredKeys.add(`offline:server:${m[1]}`);
const m = /^(server|device):(\d+)$/.exec(child);
if (m) coveredKeys.add(`offline:${m[1]}:${m[2]}`);
}
const { added: announced, resolved, next, newlyDown, ended } = diffConditions(await loadState(), current, held, await activeSubjects(new Date(now)), coveredKeys);
await setInternalFlag(STATE_FLAG, JSON.stringify(next));
// A host's message says what else it takes with it.
const added = announced.map((c) => {
const m = /^offline:server:(\d+)$/.exec(c.key);
const children = m ? cover.taken.get(`server:${m[1]}`) : undefined;
const m = /^offline:(server|device):(\d+)$/.exec(c.key);
const children = m ? cover.taken.get(`${m[1]}:${m[2]}`) : undefined;
return children?.length ? { ...c, message: `${c.message} — also takes down ${alsoList(children)}` } : c;
});
+7 -1
View File
@@ -1,6 +1,6 @@
import { and, eq, gt, lt, lte } from "drizzle-orm";
import { db } from "../db/client.js";
import { dnsProviders, integrations, maintenanceWindows, servers } from "../db/schema.js";
import { dnsProviders, integrations, maintenanceWindows, networkDevices, servers } from "../db/schema.js";
export type ActiveWindow = typeof maintenanceWindows.$inferSelect;
@@ -27,6 +27,8 @@ export function subjectOfConditionKey(key: string): string | null {
if (m) return `server:${m[1]}`;
m = /^(?:endpoint(?:-cert)?|heartbeat(?:-fail)?):\d+:server:(\d+)$/.exec(key);
if (m) return `server:${m[1]}`;
m = /^offline:device:(\d+)$/.exec(key);
if (m) return `device:${m[1]}`;
m = /^disk:proxmox:(\d+):/.exec(key);
if (m) return `integration:${m[1]}`;
m = /^(?:synology-volume|synology-disk|disk:synology):(\d+):/.exec(key);
@@ -110,6 +112,10 @@ export async function describeTarget(targetType: ActiveWindow["targetType"], tar
const [r] = await db.select({ name: servers.name }).from(servers).where(eq(servers.id, targetId)).limit(1);
return r ? { name: r.name, kind: "Server" } : null;
}
if (targetType === "device") {
const [r] = await db.select({ name: networkDevices.name, kind: networkDevices.kind }).from(networkDevices).where(eq(networkDevices.id, targetId)).limit(1);
return r ? { name: r.name, kind: `Network device (${r.kind.replace("_", " ")})` } : null;
}
if (targetType === "integration") {
const [r] = await db.select({ name: integrations.name, type: integrations.type }).from(integrations).where(eq(integrations.id, targetId)).limit(1);
return r ? { name: r.name, kind: `Integration (${r.type})` } : null;
+1
View File
@@ -606,6 +606,7 @@ const SOURCE_LABELS: Record<string, string> = {
phpipam: "phpIPAM",
pbs: "Proxmox Backup Server",
osticket: "osTicket",
unifi: "UniFi",
};
export function sourceLabel(source: string): string {
+3 -1
View File
@@ -117,6 +117,8 @@ export interface HealthCheckSettings {
newPortAlerts: boolean;
/** An alert raised this many times within an hour is "flapping": one message says so and its further raised/cleared messages are held until it has been quiet for an hour. 0 turns it off. */
flapRaises: number;
/** A network device (switch, access point, gateway) that a UniFi controller has not seen online for this many minutes is raised as offline. */
deviceOfflineMinutes: number;
}
/** The monthly report: last month's availability, incidents, updates and renewals, in one message on a day of the month. Off until switched on. */
@@ -287,7 +289,7 @@ const DEFAULTS: AppSettings = {
selfBackup: { enabled: true, time: "03:30", keep: 14 },
profilePictures: { gravatar: false, identityProvider: false },
signIn: { roleFromGroups: false, groupsClaim: "groups", adminGroups: [], operatorGroups: [], otherwise: "viewer" },
healthChecks: { serverOfflineMinutes: 60, diskUsagePercent: 90, domainWarnDays: 30, diskForecastDays: 14, backupStaleHours: 48, restoreTestDays: 0, newPortAlerts: true, flapRaises: 3 },
healthChecks: { serverOfflineMinutes: 60, diskUsagePercent: 90, domainWarnDays: 30, diskForecastDays: 14, backupStaleHours: 48, restoreTestDays: 0, newPortAlerts: true, flapRaises: 3, deviceOfflineMinutes: 10 },
// Docker's default bridge (172.17.0.0/16) and the pool it hands custom networks from (172.18–31) live here, and every
// Docker host repeats them. Shown on the Consistency page, where it can be removed if 172.16/12 is used as a real LAN.
consistency: { excludedRanges: ["172.16.0.0/12"] },
+166
View File
@@ -0,0 +1,166 @@
/**
* Keeps the network equipment of every UniFi integration in the database: the devices (state, IP, uptime, firmware, uplink), and the networks and Wi-Fi names beside
* them. A pass runs every few minutes and on request. The rows are what the Network devices page shows, what the dependency map and the offline alerts are
* built from — so none of those talk to the controller themselves, and a controller that is down costs only the freshness of what they show.
*
* What is kept is small and exact: a device that has gone offline carries `offlineSince` until it is back, which is what an "offline" alert counts from.
*/
import { and, eq, inArray, or } from "drizzle-orm";
import { db } from "../db/client.js";
import { dependencies, integrations, networkDevices, networkSegments } from "../db/schema.js";
import { loadIntegrationConfig } from "../integrations/loadIntegration.js";
import { createUnifiAdapter, type UnifiDevice, type UnifiInventory } from "../integrations/unifi/adapter.js";
import { getInternalFlag, setInternalFlag } from "./settingsStore.js";
export const SYNC_INTERVAL_MS = 5 * 60_000;
/** A device's state is only as good as the last pass: after this long without a good one, offline alerts are held rather than judged. */
export const STALE_AFTER_MS = 20 * 60_000;
const STATUS_FLAG = "unifiSync";
export interface SyncStatus {
at: string;
ok: boolean;
error: string | null;
sites: string[];
mode: "api_key" | "login" | null;
devices: number;
networks: number;
ssids: number;
}
type DeviceRow = typeof networkDevices.$inferSelect;
/** What a device's offline bookkeeping becomes now. Pure. `offlineSince` starts when it is first seen not online and stays until it is online again. */
export function trackOffline(previous: { offlineSince: string | null; lastOnlineAt: string | null } | undefined, state: UnifiDevice["state"], nowIso: string): { offlineSince: string | null; lastOnlineAt: string | null } {
const lastOnlineAt = previous?.lastOnlineAt ?? null;
if (state === "online") return { offlineSince: null, lastOnlineAt: nowIso };
if (state === "offline") return { offlineSince: previous?.offlineSince ?? nowIso, lastOnlineAt };
// Updating, being adopted or unknown: neither back nor newly gone, so what was known stays.
return { offlineSince: previous?.offlineSince ?? null, lastOnlineAt };
}
async function readStatuses(): Promise<Record<string, SyncStatus>> {
try {
const raw = await getInternalFlag(STATUS_FLAG);
return raw ? (JSON.parse(raw) as Record<string, SyncStatus>) : {};
} catch {
return {};
}
}
export async function syncStatuses(): Promise<Record<number, SyncStatus>> {
return Object.fromEntries(Object.entries(await readStatuses()).map(([k, v]) => [Number(k), v]));
}
async function writeStatus(integrationId: number, status: SyncStatus): Promise<void> {
const all = await readStatuses();
all[String(integrationId)] = status;
await setInternalFlag(STATUS_FLAG, JSON.stringify(all));
}
/** Writes one controller's inventory: updates what is there, adds what is new, removes what the controller no longer has. */
export async function storeInventory(integrationId: number, inventory: UnifiInventory, now: Date = new Date()): Promise<void> {
const nowIso = now.toISOString();
const existing = await db.select().from(networkDevices).where(eq(networkDevices.integrationId, integrationId));
const byExternal = new Map(existing.map((r) => [r.externalId, r]));
const seen = new Set<string>();
for (const d of inventory.devices) {
if (seen.has(d.externalId)) continue;
seen.add(d.externalId);
const prev = byExternal.get(d.externalId);
const track = trackOffline(prev, d.state, nowIso);
const values = {
siteName: d.siteName,
name: d.name,
model: d.model,
kind: d.kind,
ip: d.ip,
mac: d.mac,
state: d.state,
uptimeSeconds: d.uptimeSeconds,
firmware: d.firmware,
firmwareUpdatable: d.firmwareUpdatable,
uplinkExternalId: d.uplinkExternalId,
offlineSince: track.offlineSince,
lastOnlineAt: track.lastOnlineAt,
updatedAt: nowIso,
};
if (prev) await db.update(networkDevices).set(values).where(eq(networkDevices.id, prev.id));
else await db.insert(networkDevices).values({ integrationId, externalId: d.externalId, firstSeenAt: nowIso, ...values });
}
const gone = existing.filter((r) => !seen.has(r.externalId)).map((r) => r.id);
if (gone.length > 0) await db.delete(networkDevices).where(inArray(networkDevices.id, gone));
const segments: (typeof networkSegments.$inferInsert)[] = [
...inventory.networks.map((n) => ({ integrationId, kind: "network" as const, externalId: n.externalId, siteName: n.siteName, name: n.name, enabled: n.enabled, vlanId: n.vlanId, subnet: n.subnet, purpose: n.purpose, security: null, networkName: null, updatedAt: nowIso })),
...inventory.ssids.map((s) => ({ integrationId, kind: "ssid" as const, externalId: s.externalId, siteName: s.siteName, name: s.name, enabled: s.enabled, vlanId: s.vlanId, subnet: null, purpose: null, security: s.security, networkName: s.networkName, updatedAt: nowIso })),
];
await db.delete(networkSegments).where(eq(networkSegments.integrationId, integrationId));
if (segments.length > 0) await db.insert(networkSegments).values(segments);
}
/** Reads one UniFi integration and stores what it says. Never throws: how it went is the returned status, and what was stored before is left alone when it failed. */
export async function syncUnifiIntegration(integrationId: number, now: Date = new Date()): Promise<SyncStatus> {
let status: SyncStatus;
try {
const loaded = await loadIntegrationConfig(integrationId);
if (!loaded || loaded.integration.type !== "unifi") throw new Error("not a UniFi integration");
const inventory = await createUnifiAdapter(loaded.config as never).fetchInventory();
await storeInventory(integrationId, inventory, now);
status = { at: now.toISOString(), ok: true, error: null, sites: inventory.sites, mode: inventory.mode, devices: inventory.devices.length, networks: inventory.networks.length, ssids: inventory.ssids.length };
} catch (err) {
const previous = (await readStatuses())[String(integrationId)];
// The time of the last good pass is kept: it is what says how stale the stored states are.
status = { at: previous?.ok ? previous.at : (previous?.at ?? now.toISOString()), ok: false, error: err instanceof Error ? err.message : String(err), sites: previous?.sites ?? [], mode: previous?.mode ?? null, devices: previous?.devices ?? 0, networks: previous?.networks ?? 0, ssids: previous?.ssids ?? 0 };
console.error(`[unifi] couldn't read integration ${integrationId}:`, status.error);
}
try {
await writeStatus(integrationId, status);
} catch (err) {
console.error("[unifi] couldn't record the result:", err);
}
return status;
}
export async function syncAllUnifi(now: Date = new Date()): Promise<Record<number, SyncStatus>> {
const rows = await db.select({ id: integrations.id }).from(integrations).where(and(eq(integrations.type, "unifi"), eq(integrations.enabled, true)));
const out: Record<number, SyncStatus> = {};
for (const r of rows) out[r.id] = await syncUnifiIntegration(r.id, now);
return out;
}
/**
* Forgets everything read from a controller — when its integration is removed. Dependencies written by hand that pointed at one of its devices go too:
* they would never be shown again, and a device that comes back under a new integration is a new device.
*/
export async function removeIntegrationData(integrationId: number): Promise<void> {
const ids = (await db.select({ id: networkDevices.id }).from(networkDevices).where(eq(networkDevices.integrationId, integrationId))).map((r) => r.id);
if (ids.length > 0) {
await db.delete(dependencies).where(or(and(eq(dependencies.fromType, "device"), inArray(dependencies.fromId, ids)), and(eq(dependencies.toType, "device"), inArray(dependencies.toId, ids))));
await db.delete(networkDevices).where(inArray(networkDevices.id, ids));
}
await db.delete(networkSegments).where(eq(networkSegments.integrationId, integrationId));
const all = await readStatuses();
if (String(integrationId) in all) {
delete all[String(integrationId)];
await setInternalFlag(STATUS_FLAG, JSON.stringify(all));
}
}
/** Whether the stored states of an integration can be trusted: it has been read successfully within the last while. */
export function isFresh(status: SyncStatus | undefined, nowMs: number): boolean {
return !!status && status.ok && nowMs - Date.parse(status.at) <= STALE_AFTER_MS;
}
export type { DeviceRow };
let timer: ReturnType<typeof setInterval> | null = null;
export function initUnifiSync(): void {
if (timer) return;
const pass = () => void syncAllUnifi().catch((err) => console.error("[unifi] pass failed:", err));
timer = setInterval(pass, SYNC_INTERVAL_MS);
// Not awaited, and not at once: the controller is not needed to start, and the first pass should not compete with the migrations and the first health pass.
setTimeout(pass, 5_000);
console.log(`[unifi] reading network equipment from UniFi controllers every ${SYNC_INTERVAL_MS / 60000} minutes`);
}
+490
View File
@@ -0,0 +1,490 @@
/**
* UniFi: reading a controller either way (API key, or a login), what is kept, when a device is called offline, and how network devices take part in the
* dependency map, the alerts and the pages that list 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 { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
import type { AddressInfo } from "node:net";
const dir = mkdtempSync(join(tmpdir(), "hm-unifi-"));
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, integrationCredentials, networkDevices, networkSegments, dependencies, maintenanceWindows } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const { encryptSecret } = await import("../src/crypto.js");
const adapterModule = await import("../src/integrations/unifi/adapter.js");
const { createUnifiAdapter, normaliseMac, deviceKind, stateFromApi, stateFromLegacy, deviceFromApi, deviceFromLegacy, ssidFromLegacy } = adapterModule;
const { syncUnifiIntegration, trackOffline, isFresh, removeIntegrationData, syncStatuses } = await import("../src/services/unifiSync.js");
const { evaluateHealth } = await import("../src/services/healthMonitor.js");
const { dependencyCover, uplinkEdges, loadGraph, alertIdOfNode } = await import("../src/services/dependencies.js");
const { subjectOfConditionKey, describeTarget } = await import("../src/services/maintenance.js");
const { networkRouter } = await import("../src/routes/network.js");
const { validateIntegrationConfig } = await import("../src/integrations/fieldSchemas.js");
const { getAlerts, invalidateAlertsCache } = await import("../src/services/alerts.js");
const { setInternalFlag } = await import("../src/services/settingsStore.js");
const { eq } = await import("drizzle-orm");
await runMigrations();
// ─── A pretend controller ───────────────────────────────────────────────────
const MAC = { gw: "00:11:22:33:44:01", sw: "00:11:22:33:44:02", ap: "00:11:22:33:44:03" };
const SECRET_PASSPHRASE = "correct-horse-battery-staple";
const siteList = { offset: 0, limit: 200, count: 1, totalCount: 1, data: [{ id: "site-1", internalReference: "default", name: "Default" }] };
const deviceList = {
offset: 0,
limit: 200,
count: 3,
totalCount: 3,
data: [
{ id: "d-gw", macAddress: "00:11:22:33:44:01", ipAddress: "192.168.1.1", name: "Gateway", model: "UDM Pro", state: "ONLINE", firmwareVersion: "4.0.6", firmwareUpdatable: false, features: ["switching"] },
{ id: "d-sw", macAddress: "00:11:22:33:44:02", ipAddress: "192.168.1.2", name: "Rack switch", model: "USW-24-PoE", state: "ONLINE", firmwareVersion: "7.0.50", firmwareUpdatable: true, features: ["switching"] },
{ id: "d-ap", macAddress: "00:11:22:33:44:03", ipAddress: "192.168.1.3", name: "Hallway AP", model: "U6 Pro", state: "OFFLINE", firmwareVersion: "6.6.55", firmwareUpdatable: false, features: ["accessPoint"] },
],
};
const detail: Record<string, unknown> = { "d-sw": { uplink: { deviceId: "d-gw" } }, "d-ap": { uplink: { deviceId: "d-sw" } }, "d-gw": {} };
const stats: Record<string, unknown> = { "d-gw": { uptimeSec: 864000 }, "d-sw": { uptimeSec: 3600 }, "d-ap": {} };
const networkList = { offset: 0, limit: 200, count: 2, totalCount: 2, data: [{ id: "n-1", name: "Default", enabled: true, vlanId: 1, management: "GATEWAY" }, { id: "n-2", name: "IoT", enabled: true, vlanId: 20, management: "GATEWAY" }] };
const networkDetail: Record<string, unknown> = { "n-1": { ipv4Configuration: { hostIpAddress: "192.168.1.1", prefixLength: 24 } }, "n-2": { ipv4Configuration: { hostIpAddress: "192.168.20.1", prefixLength: 24 } } };
const wifiList = {
offset: 0,
limit: 200,
count: 2,
totalCount: 2,
data: [
{ id: "w-1", name: "Home", enabled: true, securityConfiguration: { type: "WPA2_PERSONAL" }, network: { type: "NATIVE" } },
{ id: "w-2", name: "IoT-net", enabled: true, securityConfiguration: { type: "WPA3_PERSONAL" }, network: { type: "SPECIFIC", networkId: "n-2" } },
],
};
const legacyDevices = [
{ _id: "x1", mac: "00:11:22:33:44:01", ip: "192.168.1.1", name: "Gateway", model: "UDMPRO", type: "udm", state: 1, uptime: 1000, version: "4.0.6", upgradable: false },
{ _id: "x2", mac: "00:11:22:33:44:02", ip: "192.168.1.2", name: "Rack switch", model: "US24PRO", type: "usw", state: 1, uptime: 500, version: "7.0.50", upgradable: true, uplink: { uplink_mac: "00:11:22:33:44:01", type: "wire" } },
{ _id: "x3", mac: "00:11:22:33:44:03", ip: "192.168.1.3", name: "Hallway AP", model: "U6PRO", type: "uap", state: 0, version: "6.6.55", uplink: { uplink_mac: "00:11:22:33:44:02", type: "wire" } },
];
const legacyNetworks = [{ _id: "ln-1", name: "Default", purpose: "corporate", vlan_enabled: false, ip_subnet: "192.168.1.1/24" }, { _id: "ln-2", name: "IoT", purpose: "corporate", vlan_enabled: true, vlan: "20", ip_subnet: "192.168.20.1/24" }];
const legacyWlans = [{ _id: "lw-1", name: "Home", enabled: true, security: "wpapsk", x_passphrase: SECRET_PASSPHRASE, networkconf_id: "ln-1" }, { _id: "lw-2", name: "Guests", enabled: false, security: "open", networkconf_id: "ln-2" }];
type Mode = "os-key" | "selfhosted-key" | "os-login" | "selfhosted-login";
let mode: Mode = "os-key";
let controller: Server;
let controllerUrl = "";
let loginsSeen = 0;
let logoutsSeen = 0;
function reply(res: ServerResponse, status: number, body?: unknown) {
res.writeHead(status, { "content-type": "application/json" });
res.end(body === undefined ? "" : JSON.stringify(body));
}
function handleApi(url: URL, res: ServerResponse, strip: string) {
const path = url.pathname.slice(strip.length);
const m = /^\/sites\/site-1\/(devices|networks|wifi\/broadcasts)(?:\/([^/]+?)(\/statistics\/latest)?)?$/.exec(path);
if (path === "/sites") return reply(res, 200, siteList);
if (!m) return reply(res, 404, { message: "no such endpoint" });
if (m[1] === "devices") return reply(res, 200, m[2] ? (m[3] ? (stats[m[2]] ?? {}) : (detail[m[2]] ?? {})) : deviceList);
if (m[1] === "networks") return reply(res, 200, m[2] ? (networkDetail[m[2]] ?? {}) : networkList);
return reply(res, 200, wifiList);
}
function handleLegacy(url: URL, res: ServerResponse, strip: string) {
const path = url.pathname.slice(strip.length);
if (path === "/api/self/sites") return reply(res, 200, { data: [{ name: "default", desc: "Default" }] });
if (path === "/api/s/default/stat/device") return reply(res, 200, { data: legacyDevices });
if (path === "/api/s/default/rest/networkconf") return reply(res, 200, { data: legacyNetworks });
if (path === "/api/s/default/rest/wlanconf") return reply(res, 200, { data: legacyWlans });
return reply(res, 404, {});
}
function route(req: IncomingMessage, res: ServerResponse) {
const url = new URL(req.url ?? "/", "http://x");
if (mode === "os-key" || mode === "selfhosted-key") {
if (req.headers["x-api-key"] !== "good-key") return reply(res, 401, { message: "bad key" });
const prefix = mode === "os-key" ? "/proxy/network/integration/v1" : "/integration/v1";
if (!url.pathname.startsWith(prefix)) return reply(res, 404, { message: "not here" });
return handleApi(url, res, prefix);
}
const os = mode === "os-login";
const loginPath = os ? "/api/auth/login" : "/api/login";
if (req.method === "POST" && url.pathname === loginPath) {
let body = "";
req.on("data", (c) => (body += c));
req.on("end", () => {
const { username, password } = JSON.parse(body || "{}");
if (username !== "reader" || password !== "pw") return reply(res, 401, { message: "nope" });
loginsSeen++;
res.setHeader("set-cookie", ["TOKEN=abc123; Path=/; HttpOnly", "other=1; Path=/"]);
if (os) res.setHeader("x-csrf-token", "csrf-1");
reply(res, 200, { ok: true });
});
return;
}
if (req.method === "POST" && url.pathname === (os ? "/api/auth/logout" : "/api/logout")) {
logoutsSeen++;
return reply(res, 200, {});
}
if (!String(req.headers.cookie ?? "").includes("TOKEN=abc123")) return reply(res, 401, {});
return handleLegacy(url, res, os ? "/proxy/network" : "");
}
// ─── The adapter ────────────────────────────────────────────────────────────
before(async () => {
controller = await new Promise<Server>((resolve) => {
const s = createServer(route).listen(0, "127.0.0.1", () => resolve(s));
});
controllerUrl = `http://127.0.0.1:${(controller.address() as AddressInfo).port}`;
});
after(() => {
controller.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows may still hold the database file
}
});
describe("normalising what a controller says", () => {
test("a MAC address is written one way, and anything else is not a MAC address", () => {
assert.equal(normaliseMac("AA-BB-CC-DD-EE-FF"), "aa:bb:cc:dd:ee:ff");
assert.equal(normaliseMac("aabbccddeeff"), "aa:bb:cc:dd:ee:ff");
assert.equal(normaliseMac("not a mac"), null);
assert.equal(normaliseMac(undefined), null);
});
test("the kind of device comes from its model, features or type — a gateway with a built-in switch is a gateway", () => {
assert.equal(deviceKind("UDM Pro", ["switching"], null), "gateway");
assert.equal(deviceKind("USW-24-PoE", ["switching"], null), "switch");
assert.equal(deviceKind("U6 Pro", ["accessPoint"], null), "access_point");
assert.equal(deviceKind(null, [], "uap"), "access_point");
assert.equal(deviceKind("UCG-Max", [], null), "gateway");
assert.equal(deviceKind("Mystery", [], null), "other");
});
test("only OFFLINE-like states are offline; adopting and updating devices are not a problem", () => {
assert.equal(stateFromApi("ONLINE"), "online");
assert.equal(stateFromApi("OFFLINE"), "offline");
assert.equal(stateFromApi("CONNECTION_INTERRUPTED"), "offline");
assert.equal(stateFromApi("UPDATING"), "updating");
assert.equal(stateFromApi("PENDING_ADOPTION"), "pending");
assert.equal(stateFromApi("something new"), "other");
assert.equal(stateFromLegacy(1), "online");
assert.equal(stateFromLegacy(0), "offline");
assert.equal(stateFromLegacy(6), "offline");
assert.equal(stateFromLegacy(4), "updating");
assert.equal(stateFromLegacy(7), "pending");
assert.equal(stateFromLegacy(99), "other");
});
test("a device from the Integration API gets its uplink as a MAC, and a missing detail only costs the uplink", () => {
const macById = new Map([["d-gw", MAC.gw], ["d-sw", MAC.sw]]);
const d = deviceFromApi(deviceList.data[1], detail["d-sw"], stats["d-sw"], "Default", macById)!;
assert.deepEqual([d.externalId, d.uplinkExternalId, d.uptimeSeconds, d.kind, d.firmwareUpdatable], [MAC.sw, MAC.gw, 3600, "switch", true]);
const bare = deviceFromApi(deviceList.data[1], null, null, "Default", macById)!;
assert.deepEqual([bare.uplinkExternalId, bare.uptimeSeconds, bare.name], [null, null, "Rack switch"]);
assert.equal(deviceFromApi({ name: "no mac" }, null, null, "Default", macById), null);
});
test("the classic API's device and Wi-Fi: the uplink MAC is read, and a passphrase is never carried over", () => {
const d = deviceFromLegacy(legacyDevices[2], "Default")!;
assert.deepEqual([d.uplinkExternalId, d.state, d.kind, d.model], [MAC.sw, "offline", "access_point", "U6PRO"]);
const s = ssidFromLegacy(legacyWlans[0], new Map([["ln-1", "Default"]]), "Default")!;
assert.deepEqual([s.name, s.security, s.networkName], ["Home", "WPA personal", "Default"]);
assert.ok(!JSON.stringify(s).includes(SECRET_PASSPHRASE));
});
});
describe("reading a controller", () => {
const cfg = (extra: Record<string, unknown>) => ({ url: controllerUrl, ...extra }) as never;
test("with an API key on a UniFi OS console: sites, devices with uplinks and uptime, networks with their ranges, Wi-Fi names", async () => {
mode = "os-key";
const inv = await createUnifiAdapter(cfg({ apiKey: "good-key" })).fetchInventory();
assert.equal(inv.mode, "api_key");
assert.deepEqual(inv.sites, ["Default"]);
const by = Object.fromEntries(inv.devices.map((d) => [d.name, d]));
assert.deepEqual([by["Gateway"].kind, by["Gateway"].uptimeSeconds, by["Gateway"].uplinkExternalId], ["gateway", 864000, null]);
assert.deepEqual([by["Rack switch"].uplinkExternalId, by["Hallway AP"].uplinkExternalId], [MAC.gw, MAC.sw]);
assert.deepEqual([by["Hallway AP"].state, by["Hallway AP"].uptimeSeconds], ["offline", null]);
assert.deepEqual(inv.networks.map((n) => [n.name, n.vlanId, n.subnet]), [["Default", 1, "192.168.1.1/24"], ["IoT", 20, "192.168.20.1/24"]]);
assert.deepEqual(inv.ssids.map((s) => [s.name, s.security, s.networkName]), [["Home", "WPA2", "Default"], ["IoT-net", "WPA3", "IoT"]]);
});
test("a self-hosted controller answers without /proxy/network: the other form of the address is found when the first is not there", async () => {
mode = "selfhosted-key";
const viaProbe = await createUnifiAdapter(cfg({ apiKey: "good-key" })).fetchInventory();
assert.equal(viaProbe.devices.length, 3);
const viaFlag = await createUnifiAdapter(cfg({ apiKey: "good-key", selfHosted: true })).fetchInventory();
assert.equal(viaFlag.devices.length, 3);
});
test("a key that is not accepted says so, and a site that does not exist says so", async () => {
mode = "os-key";
await assert.rejects(createUnifiAdapter(cfg({ apiKey: "wrong" })).fetchInventory(), /did not accept the API key/);
await assert.rejects(createUnifiAdapter(cfg({ apiKey: "good-key", site: "Garage" })).fetchInventory(), /no site called/);
const only = await createUnifiAdapter(cfg({ apiKey: "good-key", site: "default" })).fetchInventory();
assert.equal(only.devices.length, 3);
});
test("with a login on a UniFi OS console: the session cookie and CSRF token are used, the Wi-Fi passphrase is dropped, and the session is given back", async () => {
mode = "os-login";
loginsSeen = 0;
logoutsSeen = 0;
const inv = await createUnifiAdapter(cfg({ username: "reader", password: "pw" })).fetchInventory();
assert.equal(inv.mode, "login");
assert.equal(inv.devices.length, 3);
assert.equal(inv.devices.find((d) => d.name === "Hallway AP")!.uplinkExternalId, MAC.sw);
assert.deepEqual(inv.networks.map((n) => [n.name, n.vlanId, n.subnet]), [["Default", null, "192.168.1.1/24"], ["IoT", 20, "192.168.20.1/24"]]);
assert.deepEqual(inv.ssids.map((s) => [s.name, s.enabled, s.security, s.networkName]), [["Home", true, "WPA personal", "Default"], ["Guests", false, "Open", "IoT"]]);
assert.ok(!JSON.stringify(inv).includes(SECRET_PASSPHRASE));
assert.deepEqual([loginsSeen, logoutsSeen], [1, 1]);
});
test("with a login on a self-hosted controller, and the wrong password", async () => {
mode = "selfhosted-login";
const inv = await createUnifiAdapter(cfg({ username: "reader", password: "pw", selfHosted: true })).fetchInventory();
assert.equal(inv.devices.length, 3);
await assert.rejects(createUnifiAdapter(cfg({ username: "reader", password: "no" })).fetchInventory(), /did not accept the username and password/);
});
test("ping says whether it can get in", async () => {
mode = "os-key";
assert.equal((await createUnifiAdapter(cfg({ apiKey: "good-key" })).ping()).ok, true);
const bad = await createUnifiAdapter(cfg({ apiKey: "wrong" })).ping();
assert.equal(bad.ok, false);
assert.match(bad.error ?? "", /API key/);
});
test("the form needs a key, or a username with its password", () => {
assert.deepEqual(validateIntegrationConfig("unifi", { url: "https://x" }), ["apiKey"]);
assert.deepEqual(validateIntegrationConfig("unifi", { url: "https://x", username: "u" }), ["password"]);
assert.deepEqual(validateIntegrationConfig("unifi", { url: "https://x", apiKey: "k" }), []);
assert.deepEqual(validateIntegrationConfig("unifi", { url: "https://x", username: "u", password: "p" }), []);
});
});
// ─── What is kept ───────────────────────────────────────────────────────────
describe("keeping what was read", () => {
test("a device is offline from the first time it is seen not online, until it is online again", () => {
const t0 = "2026-01-01T10:00:00.000Z";
const t1 = "2026-01-01T10:05:00.000Z";
const t2 = "2026-01-01T10:10:00.000Z";
let s = trackOffline(undefined, "online", t0);
assert.deepEqual(s, { offlineSince: null, lastOnlineAt: t0 });
s = trackOffline(s, "offline", t1);
assert.deepEqual(s, { offlineSince: t1, lastOnlineAt: t0 });
s = trackOffline(s, "offline", t2);
assert.equal(s.offlineSince, t1, "still counted from the first time");
s = trackOffline(s, "updating", t2);
assert.equal(s.offlineSince, t1, "updating says nothing either way");
s = trackOffline(s, "online", t2);
assert.deepEqual(s, { offlineSince: null, lastOnlineAt: t2 });
});
test("freshness: only a good, recent read can be believed", () => {
const now = Date.parse("2026-01-01T12:00:00.000Z");
const status = (at: string, ok = true) => ({ at, ok, error: null, sites: [], mode: null, devices: 0, networks: 0, ssids: 0 });
assert.equal(isFresh(undefined, now), false);
assert.equal(isFresh(status("2026-01-01T11:55:00.000Z"), now), true);
assert.equal(isFresh(status("2026-01-01T11:00:00.000Z"), now), false);
assert.equal(isFresh(status("2026-01-01T11:55:00.000Z", false), now), false);
});
});
describe("a controller in the database", () => {
let integrationId = 0;
let gwId = 0;
let swId = 0;
let apId = 0;
let webId = 0;
before(async () => {
await db.insert(users).values([
{ oidcSub: "admin", name: "Ada", role: "admin" },
{ oidcSub: "viewer", name: "Vic", role: "viewer" },
{ oidcSub: "operator", name: "Olga", role: "operator" },
]);
mode = "os-key";
const [cred] = await db.insert(integrationCredentials).values({ name: "unifi:Home", encryptedSecret: encryptSecret(JSON.stringify({ apiKey: "good-key" })) }).returning();
const [row] = await db.insert(integrations).values({ type: "unifi", name: "Home UniFi", baseUrl: controllerUrl, credentialId: cred.id, config: JSON.stringify({ url: controllerUrl }) }).returning();
integrationId = row.id;
webId = (await db.insert(servers).values({ name: "web", apiTokenHash: "w", apiTokenPrefix: "w", lastSeenAt: new Date().toISOString() }).returning({ id: servers.id }))[0].id;
});
test("the first read stores the devices, the networks and the Wi-Fi names, and says how it went", async () => {
const status = await syncUnifiIntegration(integrationId);
assert.equal(status.ok, true);
assert.deepEqual([status.devices, status.networks, status.ssids, status.mode], [3, 2, 2, "api_key"]);
const rows = await db.select().from(networkDevices);
assert.equal(rows.length, 3);
gwId = rows.find((r) => r.name === "Gateway")!.id;
swId = rows.find((r) => r.name === "Rack switch")!.id;
apId = rows.find((r) => r.name === "Hallway AP")!.id;
const ap = rows.find((r) => r.id === apId)!;
assert.deepEqual([ap.state, ap.kind, ap.ip, ap.uplinkExternalId], ["offline", "access_point", "192.168.1.3", MAC.sw]);
assert.ok(ap.offlineSince, "offline since the first look");
assert.equal((await db.select().from(networkSegments)).length, 4);
assert.equal((await syncStatuses())[integrationId].ok, true);
});
test("a second read keeps when the offline began, and a device that is gone from the controller is removed", async () => {
const before = (await db.select().from(networkDevices).where(eq(networkDevices.id, apId)))[0].offlineSince;
await new Promise((r) => setTimeout(r, 15));
await syncUnifiIntegration(integrationId, new Date());
assert.equal((await db.select().from(networkDevices).where(eq(networkDevices.id, apId)))[0].offlineSince, before);
assert.equal((await db.select().from(networkDevices)).length, 3, "updated in place, not added again");
});
test("a controller that cannot be read leaves what was stored, and says why", async () => {
mode = "selfhosted-key"; // the console form of the address now 404s... but the probe finds the other form, so break the key instead
const [cred] = await db.select().from(integrationCredentials);
await db.update(integrationCredentials).set({ encryptedSecret: encryptSecret(JSON.stringify({ apiKey: "revoked" })) }).where(eq(integrationCredentials.id, cred.id));
const status = await syncUnifiIntegration(integrationId);
assert.equal(status.ok, false);
assert.match(status.error ?? "", /API key/);
assert.equal((await db.select().from(networkDevices)).length, 3);
await db.update(integrationCredentials).set({ encryptedSecret: encryptSecret(JSON.stringify({ apiKey: "good-key" })) }).where(eq(integrationCredentials.id, cred.id));
mode = "os-key";
assert.equal((await syncUnifiIntegration(integrationId)).ok, true);
});
test("uplinks are dependencies nobody had to write: the access point needs the switch, which needs the gateway", async () => {
const graph = await loadGraph();
assert.deepEqual(graph.edges.get(`device:${apId}`), [`device:${swId}`]);
assert.deepEqual(graph.edges.get(`device:${swId}`), [`device:${gwId}`]);
assert.equal(graph.edges.get(`device:${gwId}`), undefined);
assert.equal(graph.rows.length, 0, "none of them is a written dependency");
assert.equal(alertIdOfNode(`device:${swId}`, graph), `offline:offline:device:${swId}`);
assert.deepEqual(uplinkEdges([{ id: 1, integrationId: 1, externalId: "a", uplinkExternalId: "zz" }]), [], "an uplink that is not known is none");
});
test("a server written as needing the access point is folded under whatever of them is the root cause", async () => {
await db.insert(dependencies).values({ fromType: "server", fromId: webId, toType: "device", toId: apId });
const cover = await dependencyCover([webId], [], [apId, swId]);
assert.equal(cover.cause.get(`device:${apId}`), `device:${swId}`, "the access point is down because the switch is");
assert.equal(cover.cause.get(`server:${webId}`), `device:${swId}`, "and so is the server that needs it");
assert.equal(cover.cause.get(`device:${swId}`), undefined, "the switch stands alone: nothing it needs is down");
assert.deepEqual([...(cover.taken.get(`device:${swId}`) ?? [])].sort(), ["Hallway AP", "web"]);
// with only the access point down, it is its own cause
const alone = await dependencyCover([], [], [apId]);
assert.equal(alone.cause.size, 0);
});
test("a device offline for longer than the limit is a critical offline alert about it", () => {
const device = (state: string, since: string | null) => ({ id: 7, name: "Hallway AP", kind: "access_point", model: "U6 Pro", state, offlineSince: since });
const snap = (devices: ReturnType<typeof device>[]) => ({ servers: [], proxmox: [], synology: [], unifi: [{ integrationId: 3, integrationName: "Home UniFi", devices }] });
const now = Date.parse("2026-01-01T12:00:00.000Z");
const limits = { serverOfflineMinutes: 60, diskUsagePercent: 90, deviceOfflineMinutes: 10 };
const five = evaluateHealth(snap([device("offline", "2026-01-01T11:55:00.000Z")]), limits, now);
assert.deepEqual(five, [], "five minutes is not yet");
const twenty = evaluateHealth(snap([device("offline", "2026-01-01T11:40:00.000Z")]), limits, now);
assert.equal(twenty.length, 1);
assert.deepEqual([twenty[0].key, twenty[0].source, twenty[0].severity], ["offline:device:7", "unifi:3", "critical"]);
assert.match(twenty[0].message, /Hallway AP \(access point, U6 Pro\) has been offline for 20 min/);
assert.deepEqual(evaluateHealth(snap([device("updating", "2026-01-01T11:00:00.000Z")]), limits, now), [], "updating is not offline");
assert.deepEqual(evaluateHealth(snap([device("online", null)]), limits, now), []);
assert.equal(subjectOfConditionKey("offline:device:7"), "device:7", "maintenance on a device holds its alert");
});
test("a maintenance window can be put on a device, and describes it", async () => {
const described = await describeTarget("device", apId);
assert.deepEqual(described, { name: "Hallway AP", kind: "Network device (access point)" });
assert.equal(await describeTarget("device", 99999), null);
await db.insert(maintenanceWindows).values({ targetType: "device", targetId: swId, startedAt: new Date(Date.now() - 1000).toISOString(), endsAt: new Date(Date.now() + 3600_000).toISOString(), reason: "rack work" });
});
test("on the Alerts page: the offline device, who it is about and where to go, silenced by maintenance, and held back when the controller has not been read for a while", async () => {
await db.update(networkDevices).set({ offlineSince: new Date(Date.now() - 30 * 60_000).toISOString() }).where(eq(networkDevices.id, apId));
invalidateAlertsCache();
const alertId = `offline:offline:device:${apId}`;
let report = await getAlerts(true);
const alert = report.alerts.find((a) => a.id === alertId)!;
assert.ok(alert, "the access point is raised");
assert.deepEqual([alert.severity, alert.category, alert.source, alert.link, alert.target?.type, alert.target?.name, alert.silenced], ["critical", "offline", "UniFi", "/network/devices", "device", "Hallway AP", false]);
assert.match(alert.message, /has been offline for 30 min/);
const [window] = await db.insert(maintenanceWindows).values({ targetType: "device", targetId: apId, startedAt: new Date(Date.now() - 1000).toISOString(), endsAt: new Date(Date.now() + 3600_000).toISOString() }).returning();
invalidateAlertsCache();
report = await getAlerts(true);
assert.equal(report.alerts.find((a) => a.id === alertId)!.silenced, true);
await db.delete(maintenanceWindows).where(eq(maintenanceWindows.id, window.id));
// Not read for longer than anyone should trust it: neither raised nor cleared, and the page says it cannot tell.
const stale = { [integrationId]: { at: new Date(Date.now() - 3600_000).toISOString(), ok: true, error: null, sites: [], mode: "api_key", devices: 3, networks: 2, ssids: 2 } };
await setInternalFlag("unifiSync", JSON.stringify(stale));
invalidateAlertsCache();
report = await getAlerts(true);
assert.equal(report.alerts.some((a) => a.id === alertId), false);
assert.ok(report.couldntCheck.some((c) => /UniFi/.test(c.name)), "it says it could not check");
assert.equal((await syncUnifiIntegration(integrationId)).ok, true);
invalidateAlertsCache();
});
describe("the page's data", () => {
let app: Server;
let base = "";
let who = "viewer";
before(async () => {
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/network", networkRouter);
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/network`;
});
after(() => app.close());
test("everyone signed in sees the devices with their address, uptime, uplink and what depends on them", async () => {
const res = await fetch(base);
assert.equal(res.status, 200);
const body = (await res.json()) as any;
const by = Object.fromEntries(body.devices.map((d: any) => [d.name, d]));
assert.deepEqual([by["Rack switch"].ip, by["Rack switch"].uptimeSeconds, by["Rack switch"].uplink.name, by["Rack switch"].firmwareUpdatable], ["192.168.1.2", 3600, "Gateway", true]);
assert.equal(by["Hallway AP"].state, "offline");
assert.equal(by["Gateway"].dependents, 3, "the switch, the access point and the server behind them");
assert.equal(by["Hallway AP"].needs, 2);
assert.equal(by["Rack switch"].inMaintenance, true);
assert.deepEqual(body.networks.map((n: any) => [n.name, n.vlanId, n.subnet]), [["Default", 1, "192.168.1.1/24"], ["IoT", 20, "192.168.20.1/24"]]);
assert.deepEqual(body.ssids.map((s: any) => [s.name, s.networkName]).sort(), [["Home", "Default"], ["IoT-net", "IoT"]]);
assert.equal(body.integrations[0].status.ok, true);
assert.ok(!JSON.stringify(body).includes(SECRET_PASSPHRASE));
});
test("reading again needs an operator", async () => {
who = "viewer";
assert.equal((await fetch(`${base}/sync`, { method: "POST", headers: { "content-type": "application/json" }, body: "{}" })).status, 403);
who = "operator";
const res = await fetch(`${base}/sync`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ integrationId }) });
assert.equal(res.status, 200);
assert.equal(((await res.json()) as any).statuses[integrationId].ok, true);
const other = await fetch(`${base}/sync`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ integrationId: 424242 }) });
assert.equal(other.status, 404);
});
});
test("removing the integration removes what was read from it, and the dependencies written about its devices", async () => {
await removeIntegrationData(integrationId);
assert.equal((await db.select().from(networkDevices)).length, 0);
assert.equal((await db.select().from(networkSegments)).length, 0);
assert.equal((await db.select().from(dependencies)).length, 0);
assert.equal((await syncStatuses())[integrationId], undefined);
});
});