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

+2
View File
@@ -72,6 +72,8 @@ export const maintenanceWindows = sqliteTable("maintenance_windows", {
startedAt: text("started_at").notNull(), // ISO
endsAt: text("ends_at").notNull(), // ISO — required: a forgotten open-ended window would silence real problems forever
createdBy: text("created_by"),
// Set on windows mirrored from another system (`kuma:<integration id>:<maintenance id>`), so a later sync can find and adjust them. NULL = started by hand.
source: text("source"),
});
// ─── Settings (key/value) ───────────────────────────────────────────────────
+2
View File
@@ -12,6 +12,7 @@ import { initPbsVerificationScheduler } from "./services/pbsVerificationSchedule
import { initQuietHoursScheduler } from "./services/quietHoursScheduler.js";
import { initHealthScheduler } from "./services/healthScheduler.js";
import { initAlertTicketScheduler } from "./services/alertTicketScheduler.js";
import { initKumaMaintenanceScheduler } from "./services/kumaMaintenanceScheduler.js";
{
// Sessions are signed with this secret. Without one, the app would sign them with a value that's in the source code.
@@ -38,6 +39,7 @@ await initPbsVerificationScheduler();
await initQuietHoursScheduler();
await initHealthScheduler();
await initAlertTicketScheduler();
await initKumaMaintenanceScheduler();
createApp().listen(env.port, () => {
console.log(`homelab-manager listening on port ${env.port}`);
+10
View File
@@ -49,6 +49,16 @@ export const INTEGRATION_FIELDS: Partial<Record<IntegrationType, IntegrationFiel
placeholder: "only needed on very old installs without API keys",
},
{ key: "password", label: "API key (or password, on old installs)", secret: true, type: "password" },
// Uptime Kuma only shares its maintenance schedule over its dashboard connection, which takes a login and not an API key.
{
key: "loginUsername",
label: "Login username, to read maintenance schedules (optional)",
secret: false,
optional: true,
placeholder: "a Kuma account without two-factor — it can change anything in Kuma, so use a dedicated one",
},
{ key: "loginPassword", label: "Login password (optional)", secret: true, optional: true, type: "password" },
{ key: "syncMaintenance", label: "Keep maintenance windows in step with Uptime Kuma's schedule", secret: false, type: "checkbox" },
],
phpipam: [
{ key: "url", label: "phpIPAM URL", secret: false, placeholder: "https://ipam.example.lan" },
+13 -1
View File
@@ -20,11 +20,17 @@
* distinguishable from any other label Uptime Kuma might add later).
*/
import { withDiagLogging } from "../../services/diagLog.js";
import { fetchMaintenance, type KumaMaintenance } from "./maintenanceFeed.js";
export interface UptimeKumaConfig {
url: string;
username?: string;
password: string;
/** Only for reading the maintenance schedule over Kuma's Socket.IO connection, which doesn't accept an API key. */
loginUsername?: string;
loginPassword?: string;
/** Keep this app's maintenance windows in step with Kuma's schedule, automatically. */
syncMaintenance?: boolean;
}
export type MonitorStatus = "up" | "down" | "pending" | "maintenance" | "unknown";
@@ -50,6 +56,8 @@ export interface UptimeKumaMonitor {
export interface UptimeKumaAdapter {
ping(): Promise<{ ok: boolean; latencyMs?: number; error?: string }>;
listMonitors(): Promise<UptimeKumaMonitor[]>;
/** The maintenance schedule — needs loginUsername/loginPassword. */
listMaintenance(): Promise<KumaMaintenance[]>;
}
// ─── Prometheus text-exposition parsing (pure) ─────────────────────────────
@@ -217,5 +225,9 @@ export function createUptimeKumaAdapter(config: UptimeKumaConfig): UptimeKumaAda
}
}
return withDiagLogging("uptimekuma", { ping, listMonitors });
async function listMaintenance(): Promise<KumaMaintenance[]> {
return fetchMaintenance({ url: config.url, loginUsername: config.loginUsername, loginPassword: config.loginPassword });
}
return withDiagLogging("uptimekuma", { ping, listMonitors, listMaintenance });
}
@@ -0,0 +1,243 @@
/**
* Reads Uptime Kuma's maintenance schedule.
*
* The /metrics endpoint only says what is in maintenance right now. The schedule itself — which windows exist, when each one
* runs next, which monitors it covers — is sent only over Kuma's live Socket.IO connection, the one its own dashboard uses,
* and that connection needs the account's username and password (an API key is not accepted there).
*
* The protocol, as in Uptime Kuma 1.23 and 2.0:
* - emit "login" {username, password, token} → callback {ok: true, token} | {tokenRequired: true} | {ok: false, msg}
* - after a successful login the server emits "maintenanceList": an object keyed by maintenance id
* - emit "getMonitorMaintenance" (id) → callback {ok: true, monitors: [{id}]} — the monitors a window covers
* Each maintenance carries `timeslotList`: for a recurring or cron window the running slot (if any) and the next one, as ISO
* timestamps; for a single window its start and end as local times in the window's own timezone; for a manual one, none.
*/
import { io } from "socket.io-client";
export interface KumaTimeslot {
/** ISO 8601, UTC. */
start: string;
end: string;
}
export interface KumaMaintenance {
id: number;
title: string;
/** manual | single | recurring-interval | recurring-weekday | recurring-day-of-month | cron */
strategy: string;
/** The switch on the window itself; a window that is switched off never runs. */
active: boolean;
/** under-maintenance | scheduled | inactive | ended | unknown — Kuma's own reading of the window right now. */
status: string;
timezone: string | null;
timeslots: KumaTimeslot[];
/** Ids as they appear in the metrics endpoint's monitor_id label. */
monitorIds: string[];
}
// ─── Pure parts ─────────────────────────────────────────────────────────────
/** Offset of a zone from UTC, in minutes, at a given instant. Null if the zone name isn't one this runtime knows. */
function zoneOffsetMinutes(timeZone: string, atMs: number): number | null {
try {
const parts = new Intl.DateTimeFormat("en-US", {
timeZone,
hourCycle: "h23",
year: "numeric",
month: "2-digit",
day: "2-digit",
hour: "2-digit",
minute: "2-digit",
second: "2-digit",
}).formatToParts(new Date(atMs));
const get = (type: string) => Number(parts.find((p) => p.type === type)?.value);
const asUtc = Date.UTC(get("year"), get("month") - 1, get("day"), get("hour"), get("minute"), get("second"));
return Math.round((asUtc - Math.floor(atMs / 1000) * 1000) / 60_000);
} catch {
return null;
}
}
const HAS_OFFSET = /(?:Z|[+-]\d{2}:?\d{2})$/i;
const LOCAL_TIME = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?(?:\.\d+)?$/;
/**
* An instant from one of Kuma's date strings. One with an offset or Z is taken as it is; a bare "2026-10-12 02:00:00" is a
* wall-clock time in the window's own timezone, so it is read in that zone (daylight saving included). Null when it can't be read.
*/
export function kumaInstant(value: unknown, timeZone: string | null): Date | null {
if (typeof value !== "string" || !value) return null;
const text = value.trim();
if (HAS_OFFSET.test(text)) {
const d = new Date(text);
return Number.isNaN(d.getTime()) ? null : d;
}
const m = LOCAL_TIME.exec(text);
if (!m || !timeZone) return null;
const guess = Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], m[6] ? +m[6] : 0);
const first = zoneOffsetMinutes(timeZone, guess);
if (first === null) return null;
let t = guess - first * 60_000;
const second = zoneOffsetMinutes(timeZone, t);
if (second !== null && second !== first) t = guess - second * 60_000;
return new Date(t);
}
/** Turns the "maintenanceList" payload into plain records. Anything unreadable is skipped rather than failing the whole list. */
export function normalizeMaintenanceList(raw: unknown): KumaMaintenance[] {
if (!raw || typeof raw !== "object") return [];
const out: KumaMaintenance[] = [];
for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
if (!value || typeof value !== "object") continue;
const m = value as Record<string, unknown>;
const id = Number(m.id ?? key);
if (!Number.isInteger(id)) continue;
const timezone = typeof m.timezone === "string" && m.timezone ? m.timezone : null;
const timeslots: KumaTimeslot[] = [];
if (Array.isArray(m.timeslotList)) {
for (const slot of m.timeslotList) {
if (!slot || typeof slot !== "object") continue;
const start = kumaInstant((slot as Record<string, unknown>).startDate, timezone);
const end = kumaInstant((slot as Record<string, unknown>).endDate, timezone);
if (start && end && end > start) timeslots.push({ start: start.toISOString(), end: end.toISOString() });
}
}
out.push({
id,
title: typeof m.title === "string" && m.title ? m.title : `Maintenance ${id}`,
strategy: typeof m.strategy === "string" ? m.strategy : "unknown",
active: m.active !== false,
status: typeof m.status === "string" ? m.status : "unknown",
timezone,
timeslots,
monitorIds: [],
});
}
return out.sort((a, b) => a.id - b.id);
}
/** The monitor ids in a "getMonitorMaintenance" reply — {monitors: [{id}]} on current versions, {monitorID: [id]} on older ones. */
export function monitorIdsFromReply(reply: unknown): string[] {
if (!reply || typeof reply !== "object") return [];
const r = reply as Record<string, unknown>;
const list = Array.isArray(r.monitors) ? r.monitors : Array.isArray(r.monitorID) ? r.monitorID : [];
const ids: string[] = [];
for (const item of list) {
const id = item && typeof item === "object" ? (item as Record<string, unknown>).id : item;
if (typeof id === "number" || typeof id === "string") ids.push(String(id));
}
return ids;
}
// ─── The connection ─────────────────────────────────────────────────────────
export interface MaintenanceFeedConfig {
url: string;
loginUsername?: string;
loginPassword?: string;
}
const OVERALL_TIMEOUT_MS = 25_000;
const ACK_TIMEOUT_MS = 10_000;
const MAX_MAINTENANCES = 200;
function loginProblem(reply: Record<string, unknown>): string {
if (reply.tokenRequired) {
return "This Uptime Kuma account uses two-factor authentication, which can't be used here. Use a separate account without it.";
}
const msg = typeof reply.msg === "string" ? reply.msg : "";
if (/incorrect|authIncorrectCreds|invalid/i.test(msg)) {
return "Uptime Kuma rejected the login username or password.";
}
return msg ? `Uptime Kuma refused the login: ${msg}` : "Uptime Kuma refused the login.";
}
export function fetchMaintenance(config: MaintenanceFeedConfig): Promise<KumaMaintenance[]> {
const hasLogin = !!config.loginUsername && !!config.loginPassword;
const base = new URL(config.url);
const socket = io(base.origin, {
path: `${base.pathname.replace(/\/+$/, "")}/socket.io/`,
transports: ["websocket"],
reconnection: false,
timeout: 10_000,
forceNew: true,
});
return new Promise<KumaMaintenance[]>((resolve, reject) => {
let finished = false;
let list: KumaMaintenance[] | null = null;
let authorised = false;
let loginFailure: string | null = null;
let collecting = false;
const finish = (err: Error | null, value?: KumaMaintenance[]) => {
if (finished) return;
finished = true;
clearTimeout(overall);
socket.disconnect();
if (err) reject(err);
else resolve(value ?? []);
};
const overall = setTimeout(() => finish(new Error("Uptime Kuma didn't send its maintenance list in time.")), OVERALL_TIMEOUT_MS);
const ask = (id: number) =>
new Promise<string[]>((res, rej) => {
socket.timeout(ACK_TIMEOUT_MS).emit("getMonitorMaintenance", id, (err: Error | null, reply: unknown) => {
if (err) return rej(new Error("Uptime Kuma didn't say which monitors a maintenance window covers."));
res(monitorIdsFromReply(reply));
});
});
// Once the list is in and the session is allowed to ask questions, find out which monitors each window covers.
const proceed = async () => {
if (collecting || list === null || !(authorised || (!hasLogin && loginFailure === null))) return;
collecting = true;
try {
for (const m of list.slice(0, MAX_MAINTENANCES)) m.monitorIds = await ask(m.id);
finish(null, list);
} catch (err) {
finish(err instanceof Error ? err : new Error(String(err)));
}
};
socket.on("connect_error", (err) => finish(new Error(`Couldn't connect to Uptime Kuma: ${err.message}`)));
socket.on("maintenanceList", (raw: unknown) => {
list = normalizeMaintenanceList(raw);
// A server with its login switched off sends the list without being asked; a login that was refused while the list
// still arrived means exactly that, so carry on.
if (loginFailure !== null) authorised = true;
void proceed();
});
socket.on("connect", () => {
if (!hasLogin) {
// Nothing to log in with. A server with authentication disabled sends the list anyway; give it a moment to.
setTimeout(() => {
if (list === null) {
finish(new Error("Uptime Kuma wants a login to share its maintenance schedule — add the login username and password to this integration."));
}
}, 4_000);
return;
}
socket.emit("login", { username: config.loginUsername, password: config.loginPassword, token: "" }, (reply: Record<string, unknown> | undefined) => {
if (reply?.ok === true) {
authorised = true;
void proceed();
// The list normally arrives with (or just before) this reply; if it doesn't, the overall timeout speaks up.
return;
}
loginFailure = loginProblem(reply ?? {});
if (list !== null) {
authorised = true;
void proceed();
} else {
setTimeout(() => {
if (list === null) finish(new Error(loginFailure ?? "Uptime Kuma refused the login."));
}, 1_500);
}
});
});
});
}
+46 -9
View File
@@ -5,7 +5,8 @@ import { db } from "../db/client.js";
import { dnsProviders, integrations, maintenanceTargetTypes, maintenanceWindows, servers } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { describeTarget, listActiveWindows, startOrExtendWindow } from "../services/maintenance.js";
import { describeTarget, listActiveWindows, listUpcomingWindows, startOrExtendWindow } from "../services/maintenance.js";
import { KumaSyncError, syncKumaMaintenance } from "../services/kumaMaintenanceSync.js";
import { loadIntegrationConfig } from "../integrations/loadIntegration.js";
import { createUptimeKumaAdapter } from "../integrations/uptimekuma/adapter.js";
import { attachMatchedServers, toMatchableServers } from "../services/uptimeKumaMatch.js";
@@ -18,20 +19,26 @@ export const maintenanceRouter = Router();
maintenanceRouter.use(requireAuth);
maintenanceRouter.get("/", asyncHandler(async (_req, res) => {
const windows = [];
for (const w of await listActiveWindows()) {
const target = await describeTarget(w.targetType, w.targetId);
if (!target) continue; // target was deleted — nothing left to silence
windows.push({ ...w, targetName: target.name, targetKind: target.kind });
}
const describe = async (rows: Awaited<ReturnType<typeof listActiveWindows>>) => {
const out = [];
for (const w of rows) {
const target = await describeTarget(w.targetType, w.targetId);
if (!target) continue; // target was deleted — nothing left to silence
out.push({ ...w, targetName: target.name, targetKind: target.kind });
}
return out;
};
const windows = await describe(await listActiveWindows());
windows.sort((a, b) => a.endsAt.localeCompare(b.endsAt));
const upcoming = await describe(await listUpcomingWindows());
upcoming.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
const [serverRows, integrationRows, providerRows] = 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),
]);
res.json({ windows, targets: { servers: serverRows, integrations: integrationRows, dnsProviders: providerRows } });
res.json({ windows, upcoming, targets: { servers: serverRows, integrations: integrationRows, dnsProviders: providerRows } });
}));
const startSchema = z.object({
@@ -138,6 +145,34 @@ maintenanceRouter.post("/import/uptimekuma", requireRole("operator"), asyncHandl
res.json({ imported, unmatched, monitorsInMaintenance: inMaintenance.length, monitorsChecked: monitors.length });
}));
const syncUptimeKumaSchema = z.object({ integrationId: z.number().int().positive() });
/** Reads Uptime Kuma's maintenance schedule now and brings the mirrored windows in line with it (the same pass that runs every 15 minutes when switched on). */
maintenanceRouter.post("/sync/uptimekuma", requireRole("operator"), asyncHandler(async (req, res) => {
const parsed = syncUptimeKumaSchema.safeParse(req.body);
if (!parsed.success) {
return res.status(400).json({ error: "invalid_body", message: "Choose an Uptime Kuma integration.", details: parsed.error.flatten() });
}
try {
const result = await syncKumaMaintenance(parsed.data.integrationId);
await recordAudit({
actor: req.currentUser!,
category: "maintenance",
action: "sync",
targetType: "integration",
targetId: parsed.data.integrationId,
detail: { started: result.started, updated: result.updated, removed: result.removed },
});
res.json(result);
} catch (err) {
if (err instanceof KumaSyncError) {
const status = err.code === "not_found" ? 404 : err.code === "unreachable" ? 502 : 400;
return res.status(status).json({ error: err.code, message: err.message });
}
throw err;
}
}));
maintenanceRouter.delete("/:id", requireRole("operator"), asyncHandler(async (req, res) => {
const id = Number(req.params.id);
const [existing] = await db.select().from(maintenanceWindows).where(eq(maintenanceWindows.id, id)).limit(1);
@@ -145,7 +180,9 @@ maintenanceRouter.delete("/:id", requireRole("operator"), asyncHandler(async (re
return res.status(404).json({ error: "not_found" });
}
// Ending moves the end to now, so it stops applying immediately; the row is pruned later like any expired one.
await db.update(maintenanceWindows).set({ endsAt: new Date().toISOString() }).where(eq(maintenanceWindows.id, id));
// A window that hasn't begun is cancelled instead: its end goes back to its start, so it never applies.
const now = new Date().toISOString();
await db.update(maintenanceWindows).set({ endsAt: existing.startedAt > now ? existing.startedAt : now }).where(eq(maintenanceWindows.id, id));
const target = await describeTarget(existing.targetType, existing.targetId);
await recordAudit({
@@ -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)));
}
/**