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:
1 parent
73a06ebe63
commit
396e074108
48 files changed
+6893
-102
No files matched your search
@@ -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
@@ -309,6 +309,13 @@
|
||||
"when": 1792443011097,
|
||||
"tag": "0043_puzzling_prism",
|
||||
"breakpoints": true
|
||||
},
|
||||
{
|
||||
"idx": 44,
|
||||
"version": "6",
|
||||
"when": 1792447584218,
|
||||
"tag": "0044_sparkling_scourge",
|
||||
"breakpoints": true
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -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
@@ -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(
|
||||
|
||||
@@ -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}`);
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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`);
|
||||
}
|
||||
|
||||
@@ -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 });
|
||||
}
|
||||
@@ -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 });
|
||||
|
||||
@@ -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));
|
||||
|
||||
@@ -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 });
|
||||
}
|
||||
|
||||
@@ -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 });
|
||||
}));
|
||||
@@ -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)) });
|
||||
}));
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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". */
|
||||
|
||||
@@ -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) : [];
|
||||
|
||||
@@ -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 }> {
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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;
|
||||
});
|
||||
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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"] },
|
||||
|
||||
@@ -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`);
|
||||
}
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user