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:
bobbanandClaude Sonnet 5.5 committed 2026-10-11 23:43:47 +02:00
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)`);
}
+249
View File
@@ -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 };
}
+10 -3
View File
@@ -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)));
}
/**