Mirror Uptime Kuma's maintenance schedule as maintenance windows
Uptime Kuma shares its maintenance windows only over its dashboard Socket.IO connection, which takes a login. With a login username and password on the integration, "Sync schedule" on the Maintenance page (and a 15-minute background pass when switched on) reads each window's running and next time slot and the monitors it covers, and makes a maintenance window on every server those monitors match. Windows that haven't started are listed as Scheduled and silence nothing until they begin; ones ended or cancelled by hand stay ended, and ones removed in Kuma are removed here. maintenance_windows gets a source column (migration 0017) and active windows now require their start to have passed. Adds socket.io-client, and tests against a stand-in Uptime Kuma speaking the same protocol. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
5e416b0273
commit
9e483f2163
21 files changed
+3259
-31
No files matched your search
@@ -0,0 +1,38 @@
|
||||
import { eq } from "drizzle-orm";
|
||||
import { db } from "../db/client.js";
|
||||
import { integrations } from "../db/schema.js";
|
||||
import { loadIntegrationConfig } from "../integrations/loadIntegration.js";
|
||||
import { syncKumaMaintenance } from "./kumaMaintenanceSync.js";
|
||||
|
||||
// Kuma reports only the running slot and the next one, so a window that starts later today is picked up within this long of being
|
||||
// reported — and a window ended or removed in Kuma stops silencing here within it, too.
|
||||
const INTERVAL_MS = 15 * 60 * 1000;
|
||||
const FIRST_PASS_DELAY_MS = 60 * 1000;
|
||||
|
||||
let timer: ReturnType<typeof setInterval> | null = null;
|
||||
|
||||
/** One pass over every enabled Uptime Kuma integration that has syncing switched on and a login to read the schedule with. */
|
||||
export async function runKumaMaintenancePass(): Promise<void> {
|
||||
const rows = await db.select({ id: integrations.id, name: integrations.name, enabled: integrations.enabled }).from(integrations).where(eq(integrations.type, "uptimekuma"));
|
||||
for (const row of rows) {
|
||||
if (!row.enabled) continue;
|
||||
try {
|
||||
const loaded = await loadIntegrationConfig(row.id);
|
||||
const config = loaded?.config as { syncMaintenance?: unknown } | undefined;
|
||||
if (config?.syncMaintenance !== true && config?.syncMaintenance !== "true") continue;
|
||||
const result = await syncKumaMaintenance(row.id);
|
||||
if (result.started > 0 || result.updated > 0 || result.removed > 0) {
|
||||
console.log(`[kumaMaintenance] ${row.name}: ${result.started} started/scheduled, ${result.updated} adjusted, ${result.removed} removed`);
|
||||
}
|
||||
} catch (err) {
|
||||
console.error(`[kumaMaintenance] ${row.name}:`, err instanceof Error ? err.message : err);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export async function initKumaMaintenanceScheduler(): Promise<void> {
|
||||
if (timer) return;
|
||||
timer = setInterval(() => void runKumaMaintenancePass(), INTERVAL_MS);
|
||||
setTimeout(() => void runKumaMaintenancePass(), FIRST_PASS_DELAY_MS);
|
||||
console.log(`[kumaMaintenance] mirroring Uptime Kuma's maintenance schedule every ${INTERVAL_MS / 60000} minutes (only for integrations that have it switched on)`);
|
||||
}
|
||||
@@ -0,0 +1,249 @@
|
||||
/**
|
||||
* 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). Each slot on each
|
||||
* such server 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 { and, eq, like, lt } from "drizzle-orm";
|
||||
import { db } from "../db/client.js";
|
||||
import { maintenanceWindows, servers } 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 { attachMatchedServers, toMatchableServers } from "./uptimeKumaMatch.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;
|
||||
serverId: 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;
|
||||
targetId: number;
|
||||
startedAt: string;
|
||||
endsAt: string;
|
||||
}
|
||||
|
||||
export interface WindowPlan {
|
||||
insert: { source: string; serverId: 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, serverId: number, start: string) => `${source}|${serverId}|${start}`;
|
||||
const byKey = new Map(existing.map((w) => [keyOf(w.source, 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 server (recent enough to be the same run) is the one to renew.
|
||||
const carrying = existing
|
||||
.filter((w) => w.source === d.source && w.targetId === d.serverId && 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.serverId, start);
|
||||
wanted.add(key);
|
||||
|
||||
const row = byKey.get(key);
|
||||
if (!row) {
|
||||
plan.insert.push({ source: d.source, serverId: d.serverId, 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.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;
|
||||
/** Windows that apply here, by server name. */
|
||||
servers: string[];
|
||||
/** Monitors the window covers that match no server. */
|
||||
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[],
|
||||
serverForMonitor: (monitorId: string) => { id: number; name: string } | null,
|
||||
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<number, string>();
|
||||
const unmatched: string[] = [];
|
||||
for (const monitorId of m.monitorIds) {
|
||||
const server = serverForMonitor(monitorId);
|
||||
if (server) matched.set(server.id, server.name);
|
||||
else 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";
|
||||
if (matched.size > 0) {
|
||||
for (const [serverId] of matched) {
|
||||
for (const slot of slots) desired.push({ source, serverId, start: slot.start, end: slot.end, reason });
|
||||
}
|
||||
}
|
||||
summary.push({
|
||||
id: m.id,
|
||||
title: m.title,
|
||||
strategy: m.strategy,
|
||||
status: m.status,
|
||||
servers: [...matched.values()].sort(),
|
||||
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 matched = attachMatchedServers(monitors, toMatchableServers(serverRows));
|
||||
const byMonitor = new Map(matched.map((m) => [m.id, m]));
|
||||
|
||||
const { desired, summary } = desiredWindows(
|
||||
integrationId,
|
||||
loaded.integration.name,
|
||||
maintenances,
|
||||
(id) => byMonitor.get(id)?.matchedServer ?? null,
|
||||
(id) => byMonitor.get(id)?.name ?? `monitor #${id}`,
|
||||
now,
|
||||
);
|
||||
|
||||
const prefix = `kuma:${integrationId}:`;
|
||||
const existing = await db
|
||||
.select({ id: maintenanceWindows.id, source: maintenanceWindows.source, targetId: maintenanceWindows.targetId, startedAt: maintenanceWindows.startedAt, endsAt: maintenanceWindows.endsAt })
|
||||
.from(maintenanceWindows)
|
||||
.where(and(eq(maintenanceWindows.targetType, "server"), like(maintenanceWindows.source, `${prefix}%`)));
|
||||
const plan = planWindowSync(desired, existing as ExistingWindow[], now);
|
||||
|
||||
for (const row of plan.insert) {
|
||||
await db.insert(maintenanceWindows).values({
|
||||
targetType: "server",
|
||||
targetId: row.serverId,
|
||||
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 };
|
||||
}
|
||||
@@ -1,12 +1,19 @@
|
||||
import { eq, gt, lt } from "drizzle-orm";
|
||||
import { and, eq, gt, lt, lte } from "drizzle-orm";
|
||||
import { db } from "../db/client.js";
|
||||
import { dnsProviders, integrations, maintenanceWindows, servers } from "../db/schema.js";
|
||||
|
||||
export type ActiveWindow = typeof maintenanceWindows.$inferSelect;
|
||||
|
||||
/** Windows whose end is still in the future. ISO strings compare correctly as text, so this is a plain string comparison. */
|
||||
/** Windows that have started and not yet ended. ISO strings compare correctly as text, so these are plain string comparisons. */
|
||||
export async function listActiveWindows(now: Date = new Date()): Promise<ActiveWindow[]> {
|
||||
return db.select().from(maintenanceWindows).where(gt(maintenanceWindows.endsAt, now.toISOString()));
|
||||
const t = now.toISOString();
|
||||
return db.select().from(maintenanceWindows).where(and(lte(maintenanceWindows.startedAt, t), gt(maintenanceWindows.endsAt, t)));
|
||||
}
|
||||
|
||||
/** Windows that are set up but haven't begun — the schedule mirrored from another system. They silence nothing until they start. */
|
||||
export async function listUpcomingWindows(now: Date = new Date()): Promise<ActiveWindow[]> {
|
||||
// A window cancelled before it began has its end set back to its start, and is not a window any more.
|
||||
return db.select().from(maintenanceWindows).where(and(gt(maintenanceWindows.startedAt, now.toISOString()), gt(maintenanceWindows.endsAt, maintenanceWindows.startedAt)));
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
Reference in new issue
Block a user