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 @@
|
||||
ALTER TABLE `maintenance_windows` ADD `source` text;
|
||||
File diff suppressed because it is too large.
Load diff
@@ -120,6 +120,13 @@
|
||||
"when": 1791667275424,
|
||||
"tag": "0016_great_glorian",
|
||||
"breakpoints": true
|
||||
},
|
||||
{
|
||||
"idx": 17,
|
||||
"version": "6",
|
||||
"when": 1791754643361,
|
||||
"tag": "0017_yummy_lady_ursula",
|
||||
"breakpoints": true
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -23,6 +23,7 @@
|
||||
"nodemailer": "^6.9.14",
|
||||
"openid-client": "^6.1.7",
|
||||
"session-file-store": "^1.5.0",
|
||||
"socket.io-client": "^4.8.4",
|
||||
"xml2js": "^0.6.2",
|
||||
"zod": "^3.24.1"
|
||||
},
|
||||
@@ -35,6 +36,7 @@
|
||||
"@types/session-file-store": "^1.2.5",
|
||||
"@types/xml2js": "^0.4.14",
|
||||
"drizzle-kit": "^0.31.10",
|
||||
"socket.io": "^4.8.4",
|
||||
"tsx": "^4.19.2",
|
||||
"typescript": "^5.7.3"
|
||||
}
|
||||
|
||||
@@ -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) ───────────────────────────────────────────────────
|
||||
|
||||
@@ -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}`);
|
||||
|
||||
@@ -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" },
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
});
|
||||
});
|
||||
});
|
||||
}
|
||||
@@ -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)`);
|
||||
}
|
||||
@@ -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)));
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
/**
|
||||
* The Uptime Kuma integration's new fields, saved through the real integrations route, reach the code that uses them:
|
||||
* the login password is stored encrypted (not in the visible config), and the "keep in step" tick-box arrives as a real boolean.
|
||||
*
|
||||
* Run with: npm test --workspace server
|
||||
*/
|
||||
import { test, describe, before, after } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { mkdtempSync, rmSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import http from "node:http";
|
||||
import type { AddressInfo } from "node:net";
|
||||
|
||||
const dir = mkdtempSync(join(tmpdir(), "hm-kuma-fields-"));
|
||||
process.env.DATABASE_PATH = join(dir, "test.sqlite");
|
||||
process.env.SESSION_DIR = join(dir, "sessions");
|
||||
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
|
||||
|
||||
const express = (await import("express")).default;
|
||||
const { db } = await import("../src/db/client.js");
|
||||
const { users, integrations } = await import("../src/db/schema.js");
|
||||
const { runMigrations } = await import("../src/db/migrate.js");
|
||||
const { integrationsRouter } = await import("../src/routes/integrations.js");
|
||||
const { loadIntegrationConfig } = await import("../src/integrations/loadIntegration.js");
|
||||
|
||||
await runMigrations();
|
||||
|
||||
describe("Uptime Kuma maintenance fields", () => {
|
||||
let app: http.Server;
|
||||
let base = "";
|
||||
|
||||
before(async () => {
|
||||
await db.insert(users).values({ oidcSub: "tester", name: "Tester", role: "admin" });
|
||||
const a = express();
|
||||
a.use(express.json());
|
||||
a.use((req, _res, next) => {
|
||||
(req as unknown as { session: unknown }).session = { user: { sub: "tester" } };
|
||||
next();
|
||||
});
|
||||
a.use("/api/integrations", integrationsRouter);
|
||||
app = await new Promise<http.Server>((resolve) => {
|
||||
const s = a.listen(0, "127.0.0.1", () => resolve(s));
|
||||
});
|
||||
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/integrations`;
|
||||
});
|
||||
|
||||
after(() => {
|
||||
app.close();
|
||||
try {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
} catch {
|
||||
// Windows keeps the database file locked until the process exits.
|
||||
}
|
||||
});
|
||||
|
||||
test("the login password is sealed away and the tick-box is a boolean when loaded", async () => {
|
||||
const res = await fetch(base, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/json" },
|
||||
body: JSON.stringify({
|
||||
type: "uptimekuma",
|
||||
name: "Kuma",
|
||||
config: { url: "https://kuma.example.lan", password: "api-key", loginUsername: "hm-reader", loginPassword: "very-secret", syncMaintenance: true },
|
||||
}),
|
||||
});
|
||||
assert.equal(res.status, 201, await res.clone().text());
|
||||
const created = (await res.json()).integration;
|
||||
|
||||
const [row] = await db.select().from(integrations);
|
||||
assert.ok(!(row.config ?? "").includes("very-secret"), "the password is not in the plain config column");
|
||||
assert.match(row.config ?? "", /hm-reader/);
|
||||
|
||||
const loaded = await loadIntegrationConfig(created.id);
|
||||
const config = loaded!.config as Record<string, unknown>;
|
||||
assert.equal(config.loginPassword, "very-secret");
|
||||
assert.equal(config.loginUsername, "hm-reader");
|
||||
assert.equal(config.syncMaintenance, true);
|
||||
});
|
||||
|
||||
test("editing without touching the login password keeps it", async () => {
|
||||
const [row] = await db.select().from(integrations);
|
||||
const res = await fetch(`${base}/${row.id}`, {
|
||||
method: "PATCH",
|
||||
headers: { "content-type": "application/json" },
|
||||
body: JSON.stringify({ config: { syncMaintenance: false } }),
|
||||
});
|
||||
assert.equal(res.status, 200, await res.clone().text());
|
||||
const config = (await loadIntegrationConfig(row.id))!.config as Record<string, unknown>;
|
||||
assert.equal(config.loginPassword, "very-secret");
|
||||
assert.equal(config.syncMaintenance, false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,398 @@
|
||||
/**
|
||||
* Mirroring Uptime Kuma's maintenance schedule as maintenance windows.
|
||||
*
|
||||
* The first half tests the pure parts (reading Kuma's dates, deciding what windows to make or change). The second half runs the
|
||||
* real sync and route against a stand-in Uptime Kuma that speaks the same protocol as the real one: an HTTP /metrics endpoint and
|
||||
* a Socket.IO connection with "login", "maintenanceList" and "getMonitorMaintenance".
|
||||
*
|
||||
* Run with: npm test --workspace server
|
||||
*/
|
||||
import { test, describe, before, after } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { mkdtempSync, rmSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import http from "node:http";
|
||||
import type { AddressInfo } from "node:net";
|
||||
|
||||
const dir = mkdtempSync(join(tmpdir(), "hm-kuma-sync-"));
|
||||
process.env.DATABASE_PATH = join(dir, "test.sqlite");
|
||||
process.env.SESSION_DIR = join(dir, "sessions");
|
||||
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
|
||||
|
||||
const express = (await import("express")).default;
|
||||
const { Server: IOServer } = await import("socket.io");
|
||||
const { db } = await import("../src/db/client.js");
|
||||
const { users, servers, integrations, maintenanceWindows } = await import("../src/db/schema.js");
|
||||
const { runMigrations } = await import("../src/db/migrate.js");
|
||||
const { maintenanceRouter } = await import("../src/routes/maintenance.js");
|
||||
const { kumaInstant, normalizeMaintenanceList, monitorIdsFromReply } = await import("../src/integrations/uptimekuma/maintenanceFeed.js");
|
||||
const { planWindowSync, desiredWindows, MANUAL_WINDOW_MS } = await import("../src/services/kumaMaintenanceSync.js");
|
||||
const { listActiveWindows, listUpcomingWindows } = await import("../src/services/maintenance.js");
|
||||
|
||||
await runMigrations();
|
||||
|
||||
const iso = (ms: number) => new Date(ms).toISOString();
|
||||
const MIN = 60_000;
|
||||
const HOUR = 60 * MIN;
|
||||
|
||||
describe("kumaInstant", () => {
|
||||
test("a time with an offset or Z is taken as given", () => {
|
||||
assert.equal(kumaInstant("2026-10-12T02:00:00.000Z", null)?.toISOString(), "2026-10-12T02:00:00.000Z");
|
||||
assert.equal(kumaInstant("2026-10-12T04:00:00+02:00", null)?.toISOString(), "2026-10-12T02:00:00.000Z");
|
||||
});
|
||||
|
||||
test("a local time is read in the window's own timezone, summer and winter", () => {
|
||||
assert.equal(kumaInstant("2026-07-01 02:00:00", "Europe/Stockholm")?.toISOString(), "2026-07-01T00:00:00.000Z"); // UTC+2
|
||||
assert.equal(kumaInstant("2026-12-01 02:00:00", "Europe/Stockholm")?.toISOString(), "2026-12-01T01:00:00.000Z"); // UTC+1
|
||||
assert.equal(kumaInstant("2026-12-01 02:00", "America/New_York")?.toISOString(), "2026-12-01T07:00:00.000Z");
|
||||
assert.equal(kumaInstant("2026-12-01 02:00:00", "UTC")?.toISOString(), "2026-12-01T02:00:00.000Z");
|
||||
});
|
||||
|
||||
test("something unreadable gives null, not a wrong time", () => {
|
||||
assert.equal(kumaInstant("2026-12-01 02:00:00", null), null);
|
||||
assert.equal(kumaInstant("2026-12-01 02:00:00", "Mars/Olympus"), null);
|
||||
assert.equal(kumaInstant("tomorrow", "UTC"), null);
|
||||
assert.equal(kumaInstant(undefined, "UTC"), null);
|
||||
});
|
||||
});
|
||||
|
||||
describe("reading Kuma's lists", () => {
|
||||
test("maintenanceList becomes plain records; unreadable entries are skipped", () => {
|
||||
const list = normalizeMaintenanceList({
|
||||
"2": { id: 2, title: "Nightly", strategy: "recurring-interval", active: true, status: "scheduled", timezone: "Europe/Stockholm", timeslotList: [{ startDate: "2026-10-12T00:00:00.000Z", endDate: "2026-10-12T01:00:00.000Z" }, { startDate: "junk", endDate: "junk" }] },
|
||||
"1": { id: 1, title: "Once", strategy: "single", active: true, status: "scheduled", timezone: "UTC", timeslotList: [{ startDate: "2026-12-01 02:00:00", endDate: "2026-12-01 03:00:00" }] },
|
||||
"3": "not an object",
|
||||
});
|
||||
assert.deepEqual(list.map((m) => m.id), [1, 2]);
|
||||
assert.deepEqual(list[0].timeslots, [{ start: "2026-12-01T02:00:00.000Z", end: "2026-12-01T03:00:00.000Z" }]);
|
||||
assert.equal(list[1].timeslots.length, 1, "the unreadable slot is dropped, the good one kept");
|
||||
});
|
||||
|
||||
test("the monitors of a window, in either reply shape", () => {
|
||||
assert.deepEqual(monitorIdsFromReply({ ok: true, monitors: [{ id: 4 }, { id: 9 }] }), ["4", "9"]);
|
||||
assert.deepEqual(monitorIdsFromReply({ ok: true, monitorID: [4, 9] }), ["4", "9"]);
|
||||
assert.deepEqual(monitorIdsFromReply({ ok: false }), []);
|
||||
assert.deepEqual(monitorIdsFromReply(null), []);
|
||||
});
|
||||
});
|
||||
|
||||
describe("planWindowSync", () => {
|
||||
const now = new Date("2026-10-10T12:00:00.000Z");
|
||||
const S = "kuma:1:5";
|
||||
const want = (start: string | null, end: string, serverId = 7) => ({ source: S, serverId, start, end, reason: "r" });
|
||||
const row = (id: number, startedAt: string, endsAt: string, targetId = 7) => ({ id, source: S, targetId, startedAt, endsAt });
|
||||
|
||||
test("a slot Kuma reports that isn't here yet is added", () => {
|
||||
const plan = planWindowSync([want("2026-10-11T00:00:00.000Z", "2026-10-11T01:00:00.000Z")], [], now);
|
||||
assert.equal(plan.insert.length, 1);
|
||||
assert.equal(plan.insert[0].start, "2026-10-11T00:00:00.000Z");
|
||||
});
|
||||
|
||||
test("running it again changes nothing", () => {
|
||||
const plan = planWindowSync([want("2026-10-11T00:00:00.000Z", "2026-10-11T01:00:00.000Z")], [row(1, "2026-10-11T00:00:00.000Z", "2026-10-11T01:00:00.000Z")], now);
|
||||
assert.deepEqual(plan, { insert: [], setEnd: [], remove: [] });
|
||||
});
|
||||
|
||||
test("a changed end is adjusted", () => {
|
||||
const plan = planWindowSync([want("2026-10-11T00:00:00.000Z", "2026-10-11T02:00:00.000Z")], [row(1, "2026-10-11T00:00:00.000Z", "2026-10-11T01:00:00.000Z")], now);
|
||||
assert.deepEqual(plan.setEnd, [{ id: 1, endsAt: "2026-10-11T02:00:00.000Z" }]);
|
||||
});
|
||||
|
||||
test("a future window Kuma no longer has is removed", () => {
|
||||
const plan = planWindowSync([], [row(1, "2026-10-11T00:00:00.000Z", "2026-10-11T01:00:00.000Z")], now);
|
||||
assert.deepEqual(plan.remove, [1]);
|
||||
});
|
||||
|
||||
test("a running window Kuma no longer has is cut short, not deleted", () => {
|
||||
const plan = planWindowSync([], [row(1, "2026-10-10T11:00:00.000Z", "2026-10-10T13:00:00.000Z")], now);
|
||||
assert.deepEqual(plan.setEnd, [{ id: 1, endsAt: now.toISOString() }]);
|
||||
assert.deepEqual(plan.remove, []);
|
||||
});
|
||||
|
||||
test("a window ended by hand stays ended while Kuma still lists it", () => {
|
||||
const ended = row(1, "2026-10-10T11:00:00.000Z", "2026-10-10T11:30:00.000Z");
|
||||
const plan = planWindowSync([want("2026-10-10T11:00:00.000Z", "2026-10-10T13:00:00.000Z")], [ended], now);
|
||||
assert.deepEqual(plan, { insert: [], setEnd: [], remove: [] });
|
||||
});
|
||||
|
||||
test("a window cancelled before it began stays cancelled", () => {
|
||||
const cancelled = row(1, "2026-10-11T00:00:00.000Z", "2026-10-11T00:00:00.000Z");
|
||||
const plan = planWindowSync([want("2026-10-11T00:00:00.000Z", "2026-10-11T01:00:00.000Z")], [cancelled], now);
|
||||
assert.deepEqual(plan, { insert: [], setEnd: [], remove: [] });
|
||||
});
|
||||
|
||||
test("a manual window carries on the running one instead of starting another", () => {
|
||||
const running = row(1, "2026-10-10T11:50:00.000Z", "2026-10-10T12:20:00.000Z");
|
||||
const plan = planWindowSync([want(null, "2026-10-10T12:45:00.000Z")], [running], now);
|
||||
assert.deepEqual(plan.insert, []);
|
||||
assert.deepEqual(plan.setEnd, [{ id: 1, endsAt: "2026-10-10T12:45:00.000Z" }]);
|
||||
});
|
||||
|
||||
test("a manual window with nothing running starts now", () => {
|
||||
const plan = planWindowSync([want(null, "2026-10-10T12:45:00.000Z")], [], now);
|
||||
assert.equal(plan.insert[0].start, now.toISOString());
|
||||
});
|
||||
|
||||
test("windows long over are tidied away", () => {
|
||||
const plan = planWindowSync([], [row(1, "2026-10-01T00:00:00.000Z", "2026-10-01T01:00:00.000Z")], now);
|
||||
assert.deepEqual(plan.remove, [1]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("desiredWindows", () => {
|
||||
const now = new Date("2026-10-10T12:00:00.000Z");
|
||||
const server = (id: string) => (id === "1" ? { id: 10, name: "elsa" } : id === "2" ? { id: 20, name: "anna" } : null);
|
||||
const label = (id: string) => `monitor ${id}`;
|
||||
const base = { id: 5, title: "Nightly", strategy: "recurring-interval", active: true, status: "scheduled", timezone: "UTC", timeslots: [] as { start: string; end: string }[], monitorIds: ["1", "2", "3"] };
|
||||
const run = (m: Partial<typeof base>) => desiredWindows(1, "Kuma", [{ ...base, ...m }], server, label, now);
|
||||
|
||||
test("each slot on each matching server; monitors that match no server are reported", () => {
|
||||
const { desired, summary } = run({ timeslots: [{ start: iso(now.getTime() + 2 * HOUR), end: iso(now.getTime() + 3 * HOUR) }] });
|
||||
assert.equal(desired.length, 2);
|
||||
assert.deepEqual(desired.map((d) => d.serverId).sort(), [10, 20]);
|
||||
assert.deepEqual(summary[0].servers, ["anna", "elsa"]);
|
||||
assert.deepEqual(summary[0].unmatched, ["monitor 3"]);
|
||||
assert.equal(summary[0].note, null);
|
||||
});
|
||||
|
||||
test("a switched-off or ended window makes nothing", () => {
|
||||
assert.equal(run({ active: false, status: "inactive", timeslots: [{ start: iso(now.getTime() + HOUR), end: iso(now.getTime() + 2 * HOUR) }] }).desired.length, 0);
|
||||
assert.equal(run({ status: "ended" }).desired.length, 0);
|
||||
});
|
||||
|
||||
test("a slot already over, or too far ahead, is left out", () => {
|
||||
const over = { start: iso(now.getTime() - 3 * HOUR), end: iso(now.getTime() - 2 * HOUR) };
|
||||
const far = { start: iso(now.getTime() + 30 * 24 * HOUR), end: iso(now.getTime() + 30 * 24 * HOUR + HOUR) };
|
||||
assert.equal(run({ timeslots: [over, far] }).desired.length, 0);
|
||||
});
|
||||
|
||||
test("a slot is capped at 31 days, however long Kuma's is", () => {
|
||||
const start = now.getTime() + HOUR;
|
||||
const { desired } = run({ timeslots: [{ start: iso(start), end: iso(start + 365 * 24 * HOUR) }] });
|
||||
assert.equal(Date.parse(desired[0].end) - start, 31 * 24 * HOUR);
|
||||
});
|
||||
|
||||
test("a manual window that is on is mirrored for a short while; one that is off is not", () => {
|
||||
const on = run({ strategy: "manual", status: "under-maintenance" });
|
||||
assert.equal(on.desired[0].start, null);
|
||||
assert.equal(Date.parse(on.desired[0].end) - now.getTime(), MANUAL_WINDOW_MS);
|
||||
assert.equal(run({ strategy: "manual", status: "inactive", active: true }).desired.length, 0);
|
||||
});
|
||||
|
||||
test("a window covering no monitors says why it made nothing", () => {
|
||||
const { desired, summary } = run({ monitorIds: [], timeslots: [{ start: iso(now.getTime() + HOUR), end: iso(now.getTime() + 2 * HOUR) }] });
|
||||
assert.equal(desired.length, 0);
|
||||
assert.equal(summary[0].note, "covers no monitors");
|
||||
});
|
||||
});
|
||||
|
||||
// ─── The whole thing, against a stand-in Uptime Kuma ────────────────────────
|
||||
|
||||
describe("syncing from a stand-in Uptime Kuma", () => {
|
||||
const kuma = {
|
||||
list: {} as Record<string, unknown>,
|
||||
monitorsOf: {} as Record<string, number[]>,
|
||||
password: "pw",
|
||||
twofa: false,
|
||||
logins: 0,
|
||||
};
|
||||
let httpServer: http.Server;
|
||||
let io: InstanceType<typeof IOServer>;
|
||||
let app: http.Server;
|
||||
let base = "";
|
||||
let integrationId = 0;
|
||||
let elsaId = 0;
|
||||
let annaId = 0;
|
||||
|
||||
const metric = (id: number, host: string) =>
|
||||
`monitor_status{monitor_id="${id}",monitor_name="m${id}",monitor_type="ping",monitor_url="",monitor_hostname="${host}",monitor_port=""} 1`;
|
||||
|
||||
before(async () => {
|
||||
httpServer = http.createServer((req, res) => {
|
||||
if (req.url === "/metrics") {
|
||||
res.end([metric(1, "elsa.lab.example"), metric(2, "anna.lab.example"), metric(3, "10.9.9.9")].join("\n"));
|
||||
} else {
|
||||
res.statusCode = 404;
|
||||
res.end();
|
||||
}
|
||||
});
|
||||
io = new IOServer(httpServer);
|
||||
io.on("connection", (socket) => {
|
||||
socket.on("login", (data: { username: string; password: string }, cb: (r: unknown) => void) => {
|
||||
kuma.logins++;
|
||||
if (kuma.twofa) return cb({ tokenRequired: true });
|
||||
if (data.username !== "admin" || data.password !== kuma.password) return cb({ ok: false, msg: "authIncorrectCreds", msgi18n: true });
|
||||
socket.emit("maintenanceList", kuma.list);
|
||||
cb({ ok: true, token: "t" });
|
||||
});
|
||||
socket.on("getMonitorMaintenance", (id: number, cb: (r: unknown) => void) => {
|
||||
cb({ ok: true, monitors: (kuma.monitorsOf[String(id)] ?? []).map((m) => ({ id: m })) });
|
||||
});
|
||||
});
|
||||
await new Promise<void>((resolve) => httpServer.listen(0, "127.0.0.1", resolve));
|
||||
const kumaUrl = `http://127.0.0.1:${(httpServer.address() as AddressInfo).port}`;
|
||||
|
||||
await db.insert(users).values({ oidcSub: "tester", name: "Tester", role: "admin" });
|
||||
elsaId = (await db.insert(servers).values({ name: "elsa", hostname: "elsa.lab.example", apiTokenHash: "x", apiTokenPrefix: "x" }).returning())[0].id;
|
||||
annaId = (await db.insert(servers).values({ name: "anna", hostname: "anna.lab.example", apiTokenHash: "y", apiTokenPrefix: "y" }).returning())[0].id;
|
||||
integrationId = (
|
||||
await db
|
||||
.insert(integrations)
|
||||
.values({
|
||||
type: "uptimekuma",
|
||||
name: "Kuma",
|
||||
baseUrl: kumaUrl,
|
||||
config: JSON.stringify({ url: kumaUrl, password: "key", loginUsername: "admin", loginPassword: "pw", syncMaintenance: true }),
|
||||
})
|
||||
.returning()
|
||||
)[0].id;
|
||||
|
||||
const a = express();
|
||||
a.use(express.json());
|
||||
a.use((req, _res, next) => {
|
||||
(req as unknown as { session: unknown }).session = { user: { sub: "tester" } };
|
||||
next();
|
||||
});
|
||||
a.use("/api/maintenance", maintenanceRouter);
|
||||
app = await new Promise<http.Server>((resolve) => {
|
||||
const s = a.listen(0, "127.0.0.1", () => resolve(s));
|
||||
});
|
||||
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/maintenance`;
|
||||
});
|
||||
|
||||
after(async () => {
|
||||
await io.close();
|
||||
app.close();
|
||||
try {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
} catch {
|
||||
// Windows keeps the database file locked until the process exits.
|
||||
}
|
||||
});
|
||||
|
||||
async function sync() {
|
||||
const res = await fetch(`${base}/sync/uptimekuma`, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/json" },
|
||||
body: JSON.stringify({ integrationId }),
|
||||
});
|
||||
return { status: res.status, body: await res.json() };
|
||||
}
|
||||
|
||||
const daily = (start: number, end: number, extra: Record<string, unknown> = {}) => ({
|
||||
id: 5,
|
||||
title: "Nightly patching",
|
||||
strategy: "recurring-interval",
|
||||
active: true,
|
||||
status: "scheduled",
|
||||
timezone: "UTC",
|
||||
timeslotList: [{ startDate: iso(start), endDate: iso(end) }],
|
||||
...extra,
|
||||
});
|
||||
|
||||
test("a daily window becomes a scheduled window on the servers it covers", async () => {
|
||||
const start = Date.now() + 3 * HOUR;
|
||||
kuma.list = { "5": daily(start, start + HOUR) };
|
||||
kuma.monitorsOf = { "5": [1, 2, 3] };
|
||||
const { status, body } = await sync();
|
||||
assert.equal(status, 200);
|
||||
assert.equal(body.started, 2);
|
||||
assert.deepEqual(body.maintenances[0].servers, ["anna", "elsa"]);
|
||||
assert.deepEqual(body.maintenances[0].unmatched, ["m3"]);
|
||||
|
||||
assert.equal((await listActiveWindows()).length, 0, "it hasn't begun, so it silences nothing yet");
|
||||
const upcoming = await listUpcomingWindows();
|
||||
assert.deepEqual(upcoming.map((w) => w.targetId).sort(), [elsaId, annaId].sort());
|
||||
assert.equal(upcoming[0].source, `kuma:${integrationId}:5`);
|
||||
assert.match(upcoming[0].reason ?? "", /Nightly patching/);
|
||||
});
|
||||
|
||||
test("syncing again adds nothing", async () => {
|
||||
const { body } = await sync();
|
||||
assert.deepEqual([body.started, body.updated, body.removed], [0, 0, 0]);
|
||||
assert.equal((await listUpcomingWindows()).length, 2);
|
||||
});
|
||||
|
||||
test("when the slot is running it is an active window that silences, ending when Kuma's slot does", async () => {
|
||||
await db.delete(maintenanceWindows);
|
||||
const start = Date.now() - 10 * MIN;
|
||||
kuma.list = { "5": daily(start, start + HOUR, { status: "under-maintenance" }) };
|
||||
const { body } = await sync();
|
||||
assert.equal(body.started, 2);
|
||||
const active = await listActiveWindows();
|
||||
assert.equal(active.length, 2);
|
||||
assert.equal(Date.parse(active[0].endsAt), start + HOUR);
|
||||
});
|
||||
|
||||
test("a window ended by hand is not brought back by the next sync", async () => {
|
||||
const [w] = await listActiveWindows();
|
||||
const res = await fetch(`${base}/${w.id}`, { method: "DELETE" });
|
||||
assert.equal(res.status, 204);
|
||||
const { body } = await sync();
|
||||
assert.equal(body.started, 0);
|
||||
assert.equal((await listActiveWindows()).length, 1);
|
||||
});
|
||||
|
||||
test("a window deleted in Kuma stops silencing here", async () => {
|
||||
kuma.list = {};
|
||||
const { body } = await sync();
|
||||
assert.ok(body.updated >= 1);
|
||||
assert.equal((await listActiveWindows()).length, 0);
|
||||
});
|
||||
|
||||
test("a future window Kuma drops is removed, and one cancelled by hand stays cancelled", async () => {
|
||||
await db.delete(maintenanceWindows);
|
||||
const start = Date.now() + 5 * HOUR;
|
||||
kuma.list = { "5": daily(start, start + HOUR) };
|
||||
await sync();
|
||||
const [first] = await listUpcomingWindows();
|
||||
await fetch(`${base}/${first.id}`, { method: "DELETE" });
|
||||
assert.equal((await listUpcomingWindows()).length, 1, "the cancelled one no longer counts");
|
||||
const again = await sync();
|
||||
assert.equal(again.body.started, 0, "and the sync does not recreate it");
|
||||
|
||||
kuma.list = {};
|
||||
const { body } = await sync();
|
||||
assert.ok(body.removed >= 1);
|
||||
assert.equal((await listUpcomingWindows()).length, 0);
|
||||
});
|
||||
|
||||
test("a wrong password says so", async () => {
|
||||
kuma.password = "something else";
|
||||
const { status, body } = await sync();
|
||||
assert.equal(status, 502);
|
||||
assert.match(body.message, /rejected the login username or password/);
|
||||
kuma.password = "pw";
|
||||
});
|
||||
|
||||
test("a login with two-factor says it can't be used", async () => {
|
||||
kuma.twofa = true;
|
||||
const { status, body } = await sync();
|
||||
assert.equal(status, 502);
|
||||
assert.match(body.message, /two-factor/);
|
||||
kuma.twofa = false;
|
||||
});
|
||||
|
||||
test("without a login on the integration it asks for one", async () => {
|
||||
const [bare] = await db
|
||||
.insert(integrations)
|
||||
.values({ type: "uptimekuma", name: "Bare", baseUrl: "http://127.0.0.1:1", config: JSON.stringify({ url: "http://127.0.0.1:1", password: "key" }) })
|
||||
.returning();
|
||||
const res = await fetch(`${base}/sync/uptimekuma`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ integrationId: bare.id }) });
|
||||
const body = await res.json();
|
||||
assert.equal(res.status, 400);
|
||||
assert.match(body.message, /needs a login/);
|
||||
});
|
||||
|
||||
test("an unreachable Uptime Kuma gives a readable message", async () => {
|
||||
const [dead] = await db
|
||||
.insert(integrations)
|
||||
.values({ type: "uptimekuma", name: "Dead", baseUrl: "http://127.0.0.1:1", config: JSON.stringify({ url: "http://127.0.0.1:1", password: "key", loginUsername: "admin", loginPassword: "pw" }) })
|
||||
.returning();
|
||||
const res = await fetch(`${base}/sync/uptimekuma`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ integrationId: dead.id }) });
|
||||
const body = await res.json();
|
||||
assert.equal(res.status, 502);
|
||||
assert.match(body.message, /Couldn't (connect to|read) Uptime Kuma/);
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user