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

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

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

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

No files matched your search

+9 -4
View File
@@ -2,7 +2,7 @@ import { Router } from "express";
import { eq } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { dependencies, servers } from "../db/schema.js";
import { dependencies, networkDevices, servers } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { invalidateAlertsCache } from "../services/alerts.js";
@@ -59,11 +59,12 @@ dependenciesRouter.get("/impact", asyncHandler(async (req, res) => {
dependenciesRouter.get("/graph", asyncHandler(async (_req, res) => {
const graph = await loadGraph();
const written = new Set(graph.rows.map((r) => `${nodeKey(r.fromType, r.fromId)}>${nodeKey(r.toType, r.toId)}`));
const edges: { from: string; to: string; kind: "written" | "runs-on" }[] = [];
const edges: { from: string; to: string; kind: "written" | "runs-on" | "uplink" }[] = [];
const taking = new Set<string>();
for (const [needing, needed] of graph.edges) {
for (const n of needed) {
edges.push({ from: n, to: needing, kind: written.has(`${needing}>${n}`) ? "written" : "runs-on" });
// A device connected through another is an uplink (the controller says so); a server's "runs on" is the other kind of link nobody wrote.
edges.push({ from: n, to: needing, kind: written.has(`${needing}>${n}`) ? "written" : needing.startsWith("device:") && n.startsWith("device:") ? "uplink" : "runs-on" });
taking.add(needing);
taking.add(n);
}
@@ -73,6 +74,7 @@ dependenciesRouter.get("/graph", asyncHandler(async (_req, res) => {
const serverRows = await db.select({ id: servers.id, lastSeenAt: servers.lastSeenAt, thresholds: servers.thresholds }).from(servers);
const serverById = new Map(serverRows.map((s) => [s.id, s]));
const intById = new Map(graph.intRows.map((i) => [i.id, i]));
const deviceById = new Map((await db.select({ id: networkDevices.id, state: networkDevices.state }).from(networkDevices)).map((d) => [d.id, d]));
const nodes = [...taking]
.map((key) => {
const [type, rawId] = key.split(":");
@@ -81,6 +83,9 @@ dependenciesRouter.get("/graph", asyncHandler(async (_req, res) => {
if (type === "server") {
const s = serverById.get(id);
if (s) status = serverStatus(s, healthChecks.serverOfflineMinutes, now);
} else if (type === "device") {
const d = deviceById.get(id);
if (d) status = d.state === "online" ? "ok" : d.state === "offline" ? "bad" : d.state === "updating" ? "warn" : "unknown";
} else {
const i = intById.get(id);
if (i?.enabled) {
@@ -88,7 +93,7 @@ dependenciesRouter.get("/graph", asyncHandler(async (_req, res) => {
status = st === "failing" ? "bad" : st === "ok" ? "ok" : "unknown";
}
}
return { key, type: type as "server" | "integration", id, name: graph.names.get(key) ?? key, status, href: type === "server" ? `/servers/${id}` : "/integrations" };
return { key, type: type as "server" | "integration" | "device", id, name: graph.names.get(key) ?? key, status, href: type === "server" ? `/servers/${id}` : type === "device" ? "/network/devices" : "/integrations" };
})
.sort((a, b) => a.name.localeCompare(b.name));
res.json({ nodes, edges });
+17 -2
View File
@@ -2,7 +2,7 @@ import { Router, type Request, type Response } from "express";
import { eq } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { integrations, integrationCredentials, integrationTypes, servers } from "../db/schema.js";
import { integrations, integrationCredentials, integrationTypes, servers, type IntegrationType } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { encryptSecret } from "../crypto.js";
@@ -25,6 +25,8 @@ import { createPbsAdapter } from "../integrations/pbs/adapter.js";
import { createOsTicketAdapter } from "../integrations/osticket/adapter.js";
import { attachMatchedServers, summarizeMonitors, toMatchableServers } from "../services/uptimeKumaMatch.js";
import { getSourceStatus } from "../services/integrationHealthMonitor.js";
import { removeIntegrationData, syncUnifiIntegration } from "../services/unifiSync.js";
import { invalidateAlertsCache } from "../services/alerts.js";
import { asyncHandler } from "../utils/asyncHandler.js";
import { ID_PATTERNS, isValidId } from "../utils/pathSegment.js";
@@ -60,6 +62,13 @@ integrationsRouter.get("/", asyncHandler(async (_req, res) => {
const configValueSchema = z.union([z.string(), z.boolean()]);
/** What to tell the person when a form was submitted without something it needs. */
function missingMessage(type: IntegrationType, missing: string[]): string {
if (type === "unifi") return "UniFi needs an API key, or a username together with its password.";
const labels = (INTEGRATION_FIELDS[type] ?? []).filter((f) => missing.includes(f.key)).map((f) => f.label);
return `Fill in: ${labels.length > 0 ? labels.join(", ") : missing.join(", ")}.`;
}
const createIntegrationSchema = z.object({
type: z.enum(integrationTypes),
name: z.string().min(1).max(200),
@@ -79,7 +88,7 @@ integrationsRouter.post("/", requireRole("admin"), asyncHandler(async (req, res)
const missing = validateIntegrationConfig(type, config);
if (missing.length > 0) {
return res.status(400).json({ error: "missing_fields", fields: missing });
return res.status(400).json({ error: "missing_fields", fields: missing, message: missingMessage(type, missing) });
}
const { secretFields, nonSecretFields } = splitIntegrationConfig(type, config);
@@ -114,6 +123,9 @@ integrationsRouter.post("/", requireRole("admin"), asyncHandler(async (req, res)
detail: { type, name },
});
// A new UniFi controller is read at once, so its equipment is there when the person opens the page (not waited for: a slow controller must not slow this).
if (type === "unifi") void syncUnifiIntegration(created.id).then(() => invalidateAlertsCache());
res.status(201).json({
integration: {
id: created.id,
@@ -213,6 +225,8 @@ integrationsRouter.patch("/:id", requireRole("admin"), asyncHandler(async (req,
},
});
if (updated.type === "unifi" && updated.enabled && (parsed.data.config || parsed.data.enabled === true)) void syncUnifiIntegration(updated.id).then(() => invalidateAlertsCache());
res.json({
integration: {
id: updated.id,
@@ -288,6 +302,7 @@ integrationsRouter.delete("/:id", requireRole("admin"), asyncHandler(async (req,
.where(eq(servers.proxmoxIntegrationId, id))
.returning({ id: servers.id });
if (existing.type === "unifi") await removeIntegrationData(id);
await db.delete(integrations).where(eq(integrations.id, id));
if (existing.credentialId) {
await db.delete(integrationCredentials).where(eq(integrationCredentials.id, existing.credentialId));
+11 -7
View File
@@ -2,7 +2,7 @@ import { Router } from "express";
import { and, eq, inArray } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { dnsProviders, integrations, maintenanceAliases, maintenanceSchedules, maintenanceTargetTypes, maintenanceWindows, servers } from "../db/schema.js";
import { dnsProviders, integrations, maintenanceAliases, maintenanceSchedules, maintenanceTargetTypes, maintenanceWindows, networkDevices, servers } from "../db/schema.js";
import { deleteSchedule, isValidTimeZone, materializeSchedules, occurrencesBetween, removeFutureWindows, targetsOf } from "../services/maintenanceSchedules.js";
import { hostOfAddress } from "../services/kumaTargets.js";
import { invalidateAlertsCache } from "../services/alerts.js";
@@ -37,10 +37,11 @@ maintenanceRouter.get("/", asyncHandler(async (_req, res) => {
const upcoming = await describe(await listUpcomingWindows());
upcoming.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
const [serverRows, integrationRows, providerRows] = await Promise.all([
const [serverRows, integrationRows, providerRows, deviceRows] = await Promise.all([
db.select({ id: servers.id, name: servers.name }).from(servers).orderBy(servers.name),
db.select({ id: integrations.id, name: integrations.name, type: integrations.type }).from(integrations).orderBy(integrations.name),
db.select({ id: dnsProviders.id, name: dnsProviders.name, providerType: dnsProviders.providerType }).from(dnsProviders).orderBy(dnsProviders.name),
db.select({ id: networkDevices.id, name: networkDevices.name, kind: networkDevices.kind }).from(networkDevices).orderBy(networkDevices.name),
]);
const aliases = [];
for (const a of await db.select().from(maintenanceAliases).orderBy(maintenanceAliases.address)) {
@@ -48,7 +49,7 @@ maintenanceRouter.get("/", asyncHandler(async (_req, res) => {
if (!target) continue; // target was deleted — the alias has nothing left to point at
aliases.push({ id: a.id, address: a.address, targetType: a.targetType, targetId: a.targetId, targetName: target.name, targetKind: target.kind });
}
res.json({ windows, upcoming, aliases, targets: { servers: serverRows, integrations: integrationRows, dnsProviders: providerRows } });
res.json({ windows, upcoming, aliases, targets: { servers: serverRows, integrations: integrationRows, dnsProviders: providerRows, devices: deviceRows } });
}));
const startSchema = z.object({
@@ -77,8 +78,8 @@ maintenanceRouter.post("/", requireRole("operator"), asyncHandler(async (req, re
}
// What depends on it goes down with it, so it is silenced for the same time (and says why).
const alsoSilenced: { type: "server" | "integration"; id: number; name: string }[] = [];
if (withDependents && (targetType === "server" || targetType === "integration")) {
const alsoSilenced: { type: "server" | "integration" | "device"; id: number; name: string }[] = [];
if (withDependents && (targetType === "server" || targetType === "integration" || targetType === "device")) {
const impact = await impactOf(targetType, targetId);
for (const d of impact?.dependents ?? []) {
const also = await startOrExtendWindow(d.type, d.id, minutes, `Depends on ${result.target.name}${reason ? ` — ${reason}` : ""}`.slice(0, 200), createdBy);
@@ -226,7 +227,7 @@ maintenanceRouter.delete("/aliases/:id", requireRole("operator"), asyncHandler(a
}));
const bulkSchema = z.object({
scope: z.enum(["everything", "servers", "integrations", "dns_providers"]),
scope: z.enum(["everything", "servers", "integrations", "dns_providers", "devices"]),
minutes: z.number().int().min(5).max(7 * 24 * 60),
reason: z.string().max(200).optional(),
});
@@ -243,13 +244,16 @@ maintenanceRouter.post("/bulk", requireRole("operator"), asyncHandler(async (req
}
const { scope, minutes, reason } = parsed.data;
const targets: { type: "server" | "integration" | "dns_provider"; id: number }[] = [];
const targets: { type: "server" | "integration" | "dns_provider" | "device"; id: number }[] = [];
if (scope === "everything" || scope === "servers") {
for (const s of await db.select({ id: servers.id }).from(servers)) targets.push({ type: "server", id: s.id });
}
if (scope === "everything" || scope === "integrations") {
for (const i of await db.select({ id: integrations.id }).from(integrations).where(eq(integrations.enabled, true))) targets.push({ type: "integration", id: i.id });
}
if (scope === "everything" || scope === "devices") {
for (const d of await db.select({ id: networkDevices.id }).from(networkDevices)) targets.push({ type: "device", id: d.id });
}
if (scope === "everything" || scope === "dns_providers") {
for (const p of await db.select({ id: dnsProviders.id }).from(dnsProviders).where(eq(dnsProviders.enabled, true))) targets.push({ type: "dns_provider", id: p.id });
}
+84
View File
@@ -0,0 +1,84 @@
import { Router } from "express";
import { eq } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { integrations, networkDevices, networkSegments } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { invalidateAlertsCache } from "../services/alerts.js";
import { dependentsOf, loadGraph, needsOfNode, nodeKey } from "../services/dependencies.js";
import { activeSubjects } from "../services/maintenance.js";
import { syncAllUnifi, syncStatuses, syncUnifiIntegration } from "../services/unifiSync.js";
import { asyncHandler } from "../utils/asyncHandler.js";
export const networkRouter = Router();
networkRouter.use(requireAuth);
/**
* The network equipment read from UniFi controllers: devices with their state, address, uptime and what they are connected through, the networks and the Wi-Fi
* names. Everyone signed in can see it (it is the same picture the dependency map and the alerts draw on); only starting a fresh read needs more.
*/
networkRouter.get("/", asyncHandler(async (_req, res) => {
const [intRows, devices, segments, statuses, graph, silenced] = await Promise.all([
db.select({ id: integrations.id, name: integrations.name, enabled: integrations.enabled }).from(integrations).where(eq(integrations.type, "unifi")),
db.select().from(networkDevices),
db.select().from(networkSegments),
syncStatuses(),
loadGraph(),
activeSubjects(),
]);
const intName = new Map(intRows.map((i) => [i.id, i.name]));
const byExternal = new Map(devices.map((d) => [`${d.integrationId}:${d.externalId}`, d]));
res.json({
integrations: intRows.map((i) => ({ id: i.id, name: i.name, enabled: i.enabled, status: statuses[i.id] ?? null })),
devices: devices
.map((d) => {
const key = nodeKey("device", d.id);
const uplink = d.uplinkExternalId ? byExternal.get(`${d.integrationId}:${d.uplinkExternalId}`) : undefined;
return {
id: d.id,
integrationId: d.integrationId,
integrationName: intName.get(d.integrationId) ?? "UniFi",
siteName: d.siteName,
name: d.name,
model: d.model,
kind: d.kind,
ip: d.ip,
mac: d.mac,
state: d.state,
uptimeSeconds: d.uptimeSeconds,
firmware: d.firmware,
firmwareUpdatable: d.firmwareUpdatable,
uplink: uplink ? { id: uplink.id, name: uplink.name } : null,
offlineSince: d.offlineSince,
lastOnlineAt: d.lastOnlineAt,
updatedAt: d.updatedAt,
// How many things depend on it (directly or through others), and how many it needs: what the dependency map says about it.
dependents: dependentsOf(graph.edges, key).length,
needs: needsOfNode(graph.edges, key).length,
inMaintenance: silenced.has(key),
};
})
.sort((a, b) => a.name.localeCompare(b.name)),
networks: segments.filter((s) => s.kind === "network").map(({ kind: _k, ...s }) => ({ ...s, integrationName: intName.get(s.integrationId) ?? "UniFi" })).sort((a, b) => (a.vlanId ?? 0) - (b.vlanId ?? 0) || a.name.localeCompare(b.name)),
ssids: segments.filter((s) => s.kind === "ssid").map(({ kind: _k, ...s }) => ({ ...s, integrationName: intName.get(s.integrationId) ?? "UniFi" })).sort((a, b) => a.name.localeCompare(b.name)),
});
}));
const syncSchema = z.object({ integrationId: z.number().int().positive().optional() });
// Reads the controller(s) now instead of waiting for the next pass.
networkRouter.post("/sync", requireRole("operator"), asyncHandler(async (req, res) => {
const parsed = syncSchema.safeParse(req.body ?? {});
if (!parsed.success) return res.status(400).json({ error: "invalid_body" });
if (parsed.data.integrationId !== undefined) {
const [row] = await db.select({ id: integrations.id, type: integrations.type }).from(integrations).where(eq(integrations.id, parsed.data.integrationId)).limit(1);
if (!row || row.type !== "unifi") return res.status(404).json({ error: "not_found", message: "That isn't a UniFi integration." });
const status = await syncUnifiIntegration(row.id);
invalidateAlertsCache();
return res.json({ statuses: { [row.id]: status } });
}
const statuses = await syncAllUnifi();
invalidateAlertsCache();
res.json({ statuses });
}));
+4 -2
View File
@@ -2,7 +2,7 @@ import { Router } from "express";
import { and, eq } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { dnsProviders, integrations, maintenanceTargetTypes, runbooks, servers } from "../db/schema.js";
import { dnsProviders, integrations, maintenanceTargetTypes, networkDevices, runbooks, servers } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { describeTarget } from "../services/maintenance.js";
@@ -39,16 +39,18 @@ runbooksRouter.get("/", asyncHandler(async (req, res) => {
// What there is, everywhere, by title only — so a page can show a "runbook" button exactly where one exists, without fetching the texts.
// Notes for something that has since been removed are left out.
runbooksRouter.get("/summary", asyncHandler(async (_req, res) => {
const [rows, serverIds, integrationIds, providerIds] = await Promise.all([
const [rows, serverIds, integrationIds, providerIds, deviceIds] = await Promise.all([
db.select({ id: runbooks.id, targetType: runbooks.targetType, targetId: runbooks.targetId, category: runbooks.category, title: runbooks.title }).from(runbooks),
db.select({ id: servers.id }).from(servers),
db.select({ id: integrations.id }).from(integrations),
db.select({ id: dnsProviders.id }).from(dnsProviders),
db.select({ id: networkDevices.id }).from(networkDevices),
]);
const exists = {
server: new Set(serverIds.map((r) => r.id)),
integration: new Set(integrationIds.map((r) => r.id)),
dns_provider: new Set(providerIds.map((r) => r.id)),
device: new Set(deviceIds.map((r) => r.id)),
};
res.json({ runbooks: rows.filter((r) => exists[r.targetType].has(r.targetId)) });
}));
+1 -1
View File
@@ -144,7 +144,7 @@ const updateSchema = z.object({
.partial()
.optional(),
healthChecks: z
.object({ serverOfflineMinutes: z.number().int().min(15).max(10080), diskUsagePercent: z.number().int().min(50).max(99), domainWarnDays: z.number().int().min(1).max(365), diskForecastDays: z.number().int().min(0).max(90), backupStaleHours: z.number().int().min(0).max(2160), restoreTestDays: z.number().int().min(0).max(730), newPortAlerts: z.boolean(), flapRaises: z.number().int().min(0).max(20) })
.object({ serverOfflineMinutes: z.number().int().min(15).max(10080), diskUsagePercent: z.number().int().min(50).max(99), domainWarnDays: z.number().int().min(1).max(365), diskForecastDays: z.number().int().min(0).max(90), backupStaleHours: z.number().int().min(0).max(2160), restoreTestDays: z.number().int().min(0).max(730), newPortAlerts: z.boolean(), flapRaises: z.number().int().min(0).max(20), deviceOfflineMinutes: z.number().int().min(5).max(1440) })
.partial()
.optional(),
quietHours: z