Files
Homelab-manager/server/src/services/kumaMaintenanceSync.ts
T
bobbanandClaude Sonnet 5.5 44cc9d1cf2 Add address aliases for the Uptime Kuma maintenance sync, and ignore Kuma's "null"
Uptime Kuma often watches a host by another address than the one it was added
with here (a Proxmox host monitored over Tailscale, say). Address aliases on
the Maintenance page say that an address belongs to a server, integration or
DNS provider, so the sync puts the window there; matching stays exact.
Migration 0018 adds maintenance_aliases.

Also fixes monitors whose empty hostname/URL/port arrive from Kuma's metrics as
the text "null": they were taken as an address, hiding the real URL.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-13 20:25:57 +02:00

293 lines
14 KiB
TypeScript

/**
* Keeps this app's maintenance windows in step with Uptime Kuma's maintenance schedule.
*
* Kuma says, for each of its windows, which monitors it covers and when it runs (the running slot, if any, and the next one).
* A monitor belongs to a server here when its target matches (the same matching the Uptime Kuma page uses), and to an
* integration or DNS provider when its target is the address that one was added with (see kumaTargets.ts). Each slot on each
* such thing becomes an ordinary maintenance window: one that has started silences alerts exactly like one started by hand,
* and one that hasn't yet is listed as scheduled and silences nothing until it begins.
*
* Windows made here carry a `source` (`kuma:<integration id>:<maintenance id>`), which is how a later pass finds them again:
* a slot Kuma still reports is left alone (or has its end adjusted), a future one Kuma no longer reports is removed, and one
* that is running but is no longer reported is cut short. A window someone ended by hand stays ended.
*/
import { eq, like, lt } from "drizzle-orm";
import { db } from "../db/client.js";
import { dnsProviders, integrations, maintenanceAliases, maintenanceWindows, servers, type MaintenanceTargetType } from "../db/schema.js";
import { loadIntegrationConfig } from "../integrations/loadIntegration.js";
import { createUptimeKumaAdapter } from "../integrations/uptimekuma/adapter.js";
import type { KumaMaintenance } from "../integrations/uptimekuma/maintenanceFeed.js";
import { toMatchableServers } from "./uptimeKumaMatch.js";
import { hostOfAddress, targetsForHost, type AddressedTarget, type WindowTarget } from "./kumaTargets.js";
/** A slot further ahead than this is left for a later pass — Kuma only reports the next one anyway, so this rarely matters. */
export const LOOKAHEAD_MS = 14 * 24 * 3600_000;
/** Longest window mirrored, however long Kuma's runs: an open-ended one is how a real outage gets hidden. */
export const MAX_WINDOW_MS = 31 * 24 * 3600_000;
/** A window Kuma holds in maintenance "until switched off" has no end; it is mirrored this far ahead and renewed on every pass. */
export const MANUAL_WINDOW_MS = 45 * 60_000;
/** Rows whose window ended longer ago than this are tidied away. */
const KEEP_ENDED_MS = 24 * 3600_000;
export interface DesiredWindow {
source: string;
targetType: MaintenanceTargetType;
targetId: number;
/** ISO. Null for a window with no fixed start (manual): it continues the one already running, else starts now. */
start: string | null;
end: string;
reason: string;
}
export interface ExistingWindow {
id: number;
source: string;
targetType: MaintenanceTargetType;
targetId: number;
startedAt: string;
endsAt: string;
}
export interface WindowPlan {
insert: { source: string; targetType: MaintenanceTargetType; targetId: number; start: string; end: string; reason: string }[];
setEnd: { id: number; endsAt: string }[];
remove: number[];
}
/** What to change so that the mirrored windows (`existing`, all of one integration's) match `desired`. Pure. */
export function planWindowSync(desired: DesiredWindow[], existing: ExistingWindow[], now: Date): WindowPlan {
const nowIso = now.toISOString();
const plan: WindowPlan = { insert: [], setEnd: [], remove: [] };
const keyOf = (source: string, targetType: string, targetId: number, start: string) => `${source}|${targetType}:${targetId}|${start}`;
const byKey = new Map(existing.map((w) => [keyOf(w.source, w.targetType, w.targetId, w.startedAt), w]));
const wanted = new Set<string>();
for (const d of desired) {
let start = d.start;
if (start === null) {
// The window already carrying on for this target (recent enough to be the same run) is the one to renew.
const carrying = existing
.filter((w) => w.source === d.source && w.targetType === d.targetType && w.targetId === d.targetId && w.startedAt <= nowIso && w.endsAt > new Date(now.getTime() - 2 * 3600_000).toISOString())
.sort((a, b) => b.startedAt.localeCompare(a.startedAt))[0];
start = carrying ? carrying.startedAt : nowIso;
}
const key = keyOf(d.source, d.targetType, d.targetId, start);
wanted.add(key);
const row = byKey.get(key);
if (!row) {
plan.insert.push({ source: d.source, targetType: d.targetType, targetId: d.targetId, start, end: d.end, reason: d.reason });
} else if (row.endsAt <= nowIso || row.endsAt <= row.startedAt) {
// Over already (it ran its course, or someone ended it by hand), or cancelled before it began. Either way it isn't brought back.
} else if (row.endsAt !== d.end) {
plan.setEnd.push({ id: row.id, endsAt: d.end });
}
}
for (const w of existing) {
const key = keyOf(w.source, w.targetType, w.targetId, w.startedAt);
if (wanted.has(key)) continue;
if (w.endsAt < new Date(now.getTime() - KEEP_ENDED_MS).toISOString()) {
plan.remove.push(w.id); // long over: tidy away
} else if (w.startedAt > nowIso) {
plan.remove.push(w.id); // not begun, and no longer on Kuma's schedule
} else if (w.endsAt > nowIso) {
plan.setEnd.push({ id: w.id, endsAt: nowIso }); // running, but Kuma no longer has it: stop silencing now
}
}
return plan;
}
export interface MaintenanceSyncSummary {
/** How many of Kuma's windows were looked at. */
maintenances: {
id: number;
title: string;
strategy: string;
status: string;
/** How many monitors the window covers in Uptime Kuma, and the time slots Kuma reported for it (running and next). */
monitorCount: number;
slots: { start: string; end: string }[];
/** What the window applies to here: servers, integrations or DNS providers. */
targets: { type: MaintenanceTargetType; name: string }[];
/** Monitors the window covers that match nothing here, as "name (address)". */
unmatched: string[];
/** Why it produced nothing, when it did not. */
note: string | null;
}[];
started: number;
updated: number;
removed: number;
}
/** What each Kuma maintenance asks for, as windows on servers. Pure. */
export function desiredWindows(
integrationId: number,
integrationName: string,
maintenances: KumaMaintenance[],
targetsForMonitor: (monitorId: string) => WindowTarget[],
monitorLabel: (monitorId: string) => string,
now: Date,
): { desired: DesiredWindow[]; summary: MaintenanceSyncSummary["maintenances"] } {
const desired: DesiredWindow[] = [];
const summary: MaintenanceSyncSummary["maintenances"] = [];
const nowMs = now.getTime();
for (const m of maintenances) {
const source = `kuma:${integrationId}:${m.id}`;
const reason = `Uptime Kuma (${integrationName}): ${m.title}`.slice(0, 200);
const matched = new Map<string, WindowTarget>();
const unmatched: string[] = [];
for (const monitorId of m.monitorIds) {
const found = targetsForMonitor(monitorId);
for (const t of found) matched.set(`${t.type}:${t.id}`, t);
if (found.length === 0) unmatched.push(monitorLabel(monitorId));
}
// The slots this window asks for.
const slots: { start: string | null; end: string }[] = [];
let note: string | null = null;
if (!m.active || m.status === "inactive" || m.status === "ended") {
note = m.active ? "already ended" : "switched off in Uptime Kuma";
} else if (m.strategy === "manual") {
if (m.status === "under-maintenance") slots.push({ start: null, end: new Date(nowMs + MANUAL_WINDOW_MS).toISOString() });
else note = "not switched on";
} else {
for (const t of m.timeslots) {
const startMs = Date.parse(t.start);
const endMs = Math.min(Date.parse(t.end), startMs + MAX_WINDOW_MS);
if (endMs <= nowMs) continue; // already over
if (startMs > nowMs + LOOKAHEAD_MS) continue; // far ahead: a later pass
slots.push({ start: t.start, end: new Date(endMs).toISOString() });
}
if (slots.length === 0) note = m.timeslots.length === 0 ? "no upcoming time slot" : "nothing within the next two weeks";
}
if (slots.length > 0 && matched.size === 0) note = m.monitorIds.length === 0 ? "covers no monitors" : "no monitor matches a server, integration or DNS provider";
for (const t of matched.values()) {
for (const slot of slots) desired.push({ source, targetType: t.type, targetId: t.id, start: slot.start, end: slot.end, reason });
}
summary.push({
id: m.id,
title: m.title,
strategy: m.strategy,
status: m.status,
monitorCount: m.monitorIds.length,
slots: m.timeslots.slice(0, 3),
targets: [...matched.values()].map((t) => ({ type: t.type, name: t.name })).sort((a, b) => a.name.localeCompare(b.name)),
unmatched,
note,
});
}
return { desired, summary };
}
export class KumaSyncError extends Error {
constructor(
message: string,
readonly code: "not_found" | "wrong_type" | "disabled" | "no_login" | "unreachable",
) {
super(message);
}
}
/** One pass for one Uptime Kuma integration: read its schedule, match monitors to servers, bring the mirrored windows in line. */
export async function syncKumaMaintenance(integrationId: number, now: Date = new Date()): Promise<MaintenanceSyncSummary> {
const loaded = await loadIntegrationConfig(integrationId);
if (!loaded) throw new KumaSyncError("That Uptime Kuma integration no longer exists.", "not_found");
if (loaded.integration.type !== "uptimekuma") throw new KumaSyncError("That integration isn't an Uptime Kuma one.", "wrong_type");
if (!loaded.integration.enabled) throw new KumaSyncError("That integration is disabled. Enable it under Integrations first.", "disabled");
const config = loaded.config as unknown as { loginUsername?: string; loginPassword?: string };
if (!config.loginUsername || !config.loginPassword) {
throw new KumaSyncError(
"Reading Uptime Kuma's maintenance schedule needs a login. Add the login username and password to this integration (Integrations → edit).",
"no_login",
);
}
const adapter = createUptimeKumaAdapter(loaded.config as never);
let maintenances: KumaMaintenance[];
let monitors;
try {
maintenances = await adapter.listMaintenance();
monitors = await adapter.listMonitors();
} catch (err) {
throw new KumaSyncError(`Couldn't read Uptime Kuma: ${err instanceof Error ? err.message : String(err)}`, "unreachable");
}
const serverRows = await db.select({ id: servers.id, name: servers.name, hostname: servers.hostname, ips: servers.ipAddresses }).from(servers);
const matchableServers = toMatchableServers(serverRows);
const addressed: AddressedTarget[] = [];
for (const i of await db.select({ id: integrations.id, name: integrations.name, baseUrl: integrations.baseUrl }).from(integrations)) {
const host = hostOfAddress(i.baseUrl);
if (host && i.id !== integrationId) addressed.push({ type: "integration", id: i.id, name: i.name, host });
}
for (const p of await db.select({ id: dnsProviders.id, name: dnsProviders.name, config: dnsProviders.config }).from(dnsProviders)) {
let url: unknown;
try {
url = p.config ? (JSON.parse(p.config) as Record<string, unknown>).url : undefined;
} catch {
url = undefined;
}
const host = typeof url === "string" ? hostOfAddress(url) : null;
if (host) addressed.push({ type: "dns_provider", id: p.id, name: p.name, host });
}
// Addresses someone has said belong to a server, integration or DNS provider (the Tailscale IP of a host that was added by its LAN address).
const names = new Map<string, string>();
for (const r of serverRows) names.set(`server:${r.id}`, r.name);
for (const t of addressed) names.set(`${t.type}:${t.id}`, t.name);
for (const i of await db.select({ id: integrations.id, name: integrations.name }).from(integrations)) names.set(`integration:${i.id}`, i.name);
for (const p of await db.select({ id: dnsProviders.id, name: dnsProviders.name }).from(dnsProviders)) names.set(`dns_provider:${p.id}`, p.name);
for (const a of await db.select().from(maintenanceAliases)) {
const name = names.get(`${a.targetType}:${a.targetId}`);
if (name) addressed.push({ type: a.targetType, id: a.targetId, name, host: a.address });
}
const byMonitor = new Map(monitors.map((m) => [m.id, m]));
const { desired, summary } = desiredWindows(
integrationId,
loaded.integration.name,
maintenances,
(id) => targetsForHost(byMonitor.get(id)?.target ?? null, matchableServers, addressed),
(id) => {
const m = byMonitor.get(id);
if (!m) return `monitor #${id} (not in Uptime Kuma's metrics — paused?)`;
return m.target ? `${m.name} (${m.target}${m.port ? `:${m.port}` : ""})` : `${m.name} (no address)`;
},
now,
);
const prefix = `kuma:${integrationId}:`;
const existing = await db
.select({
id: maintenanceWindows.id,
source: maintenanceWindows.source,
targetType: maintenanceWindows.targetType,
targetId: maintenanceWindows.targetId,
startedAt: maintenanceWindows.startedAt,
endsAt: maintenanceWindows.endsAt,
})
.from(maintenanceWindows)
.where(like(maintenanceWindows.source, `${prefix}%`));
const plan = planWindowSync(desired, existing as ExistingWindow[], now);
for (const row of plan.insert) {
await db.insert(maintenanceWindows).values({
targetType: row.targetType,
targetId: row.targetId,
reason: row.reason,
startedAt: row.start,
endsAt: row.end,
createdBy: "Uptime Kuma sync",
source: row.source,
});
}
for (const change of plan.setEnd) await db.update(maintenanceWindows).set({ endsAt: change.endsAt }).where(eq(maintenanceWindows.id, change.id));
for (const id of plan.remove) await db.delete(maintenanceWindows).where(eq(maintenanceWindows.id, id));
// Same tidying as when a window is started by hand: long-over rows are clutter.
await db.delete(maintenanceWindows).where(lt(maintenanceWindows.endsAt, new Date(now.getTime() - KEEP_ENDED_MS).toISOString()));
return { maintenances: summary, started: plan.insert.length, updated: plan.setEnd.length, removed: plan.remove.length };
}