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 -1
View File
@@ -140,7 +140,8 @@ required, so a forgotten window can't silence real problems forever.
| `target_id` | integer NOT NULL | The ID in the table `target_type` names. **Not a foreign key**; a window whose target was deleted is simply ignored. |
| `reason` | text | |
| `started_at`, `ends_at` | text NOT NULL | ISO. |
| `created_by` | text | Name of the person who opened it. |
| `created_by` | text | Name of the person who opened it. `Uptime Kuma sync` for mirrored ones. |
| `source` | text | `kuma:<integration id>:<maintenance id>` on windows mirrored from Uptime Kuma's schedule, so a later sync can find them again; NULL for ones started by hand. A window whose `started_at` is still in the future is *scheduled*: it silences nothing until it begins. A scheduled one that is cancelled has `ends_at` set equal to `started_at`. |
### Servers
+27 -4
View File
@@ -74,10 +74,33 @@ the dashboard views themselves load fine.
with no single network target (groups, push monitors, keyword checks with a complex URL) are shown
unmatched rather than guessed at. Uptime Kuma's tags aren't read, since the metrics endpoint doesn't
reliably distinguish a tag from any other label.
- **Maintenance import:** the Maintenance page can read which monitors are currently in maintenance in Uptime
Kuma and start (or extend) a maintenance window here for the matching server, for a duration you pick — the
metrics endpoint only exposes current status, not a monitor's scheduled start/end time, so this reflects
what's in maintenance right now rather than mirroring Uptime Kuma's own schedule.
- **Maintenance import ("Import now"):** the Maintenance page can read which monitors are currently in
maintenance in Uptime Kuma and start (or extend) a maintenance window here for the matching server, for a
duration you pick — the metrics endpoint only exposes current status, not a window's schedule.
- **Maintenance schedule ("Sync schedule"):** Uptime Kuma shares its maintenance windows only over the live
Socket.IO connection its own dashboard uses, and that connection takes a **login username and password** —
an API key is not accepted there. Fill in the optional *Login username* and *Login password* on the
integration to use it. Be aware that a Uptime Kuma login can change anything in Uptime Kuma (it has no
read-only accounts), so create a **dedicated account** for this. An account with two-factor authentication
cannot be used. The password is stored encrypted like every other credential here, and is used for nothing
but this. The login is sent as Uptime Kuma's own `login` event over `ws://` or `wss://` to the same address
as the integration, so use an `https://` address if it crosses anything but a trusted network.
- For each window Uptime Kuma reports (its running time slot and the next one), the app finds the
monitors it covers, matches their targets to servers the same way the Uptime Kuma page does, and makes a
maintenance window on each matched server. A window that hasn't started shows as *Scheduled* and silences
nothing yet.
- Tick *Keep maintenance windows in step with Uptime Kuma's schedule* to run this automatically every
15 minutes. Without it, the *Sync schedule* button does the same once.
- Windows are capped at 31 days, and only slots starting within two weeks are mirrored. A window Uptime
Kuma holds in maintenance "until switched off" (the manual kind) is mirrored 45 minutes at a time and
renewed on each pass, so it lapses by itself if Uptime Kuma becomes unreachable.
- A window you end or cancel here is not brought back by a later sync. One that is removed or switched
off in Uptime Kuma is removed here (a running one is ended at once).
- Monitors that match no server (groups, push monitors, hosts the app doesn't know) are listed as
unmatched in the result and silence nothing. A window on a *group* monitor does not extend to its
children here.
- Verified against the Uptime Kuma 1.23 and 2.0 source and against a stand-in server speaking the same
protocol; not yet run against a live Uptime Kuma.
### Proxmox Backup Server
+12 -6
View File
@@ -325,12 +325,18 @@ health, Proxmox backup alerts, Proxmox Backup Server verification alerts, and
Every window has a fixed end (5 minutes to 7 days) and expires on its own, and
a problem that began during a window and is still present when it ends alerts
then — a forgotten window can't hide an outage. A banner shows what's currently
silenced to every signed-in user. If you also run Uptime Kuma, "Import from
Uptime Kuma" on the Maintenance page reads which of its monitors are
currently in maintenance and starts (or extends) a window here for whichever
server each one's target matches, for a duration you choose — Uptime Kuma's
metrics only say what's in maintenance right now, not for how long, so this
doesn't try to mirror its schedule, only its current state.
silenced to every signed-in user. If you also run Uptime Kuma, the Maintenance
page can take its maintenance windows over: "Sync schedule" reads each window
(daily, weekly, one-off, cron or switched on by hand), finds the servers its
monitors belong to, and makes a window here for the one running now and the next
one — listed under Scheduled until it starts, then silencing alerts like any
other. Tick "Keep maintenance windows in step" on the Uptime Kuma integration
and this happens by itself every 15 minutes, so a daily window needs no
clicking at all; a window changed, switched off or deleted in Uptime Kuma is
followed, and one you end or cancel here by hand stays ended. Reading the
schedule needs a login on the Uptime Kuma integration (see INTEGRATIONS.md).
"Import now" is the older, simpler route: it only looks at what is in
maintenance this moment and starts a window for a duration you choose.
**Ports** — each server's detail page has a Ports card for finding free ports
and remembering what each one is for. "Scan…" runs a TCP scan of a port range
+144 -1
View File
@@ -1805,6 +1805,12 @@
"win32"
]
},
"node_modules/@socket.io/component-emitter": {
"version": "3.1.2",
"resolved": "https://registry.npmjs.org/@socket.io/component-emitter/-/component-emitter-3.1.2.tgz",
"integrity": "sha512-9BCxFwvbGg/RsZK9tjXd8s4UcwR0MWeFQ1XEKIQVVvAGJyINdrqKMcTRyLoK8Rse1GjzLV9cwjWV1olXRWEXVA==",
"license": "MIT"
},
"node_modules/@tabler/core": {
"version": "1.5.1",
"resolved": "https://registry.npmjs.org/@tabler/core/-/core-1.5.1.tgz",
@@ -1913,6 +1919,16 @@
"@types/node": "*"
}
},
"node_modules/@types/cors": {
"version": "2.8.19",
"resolved": "https://registry.npmjs.org/@types/cors/-/cors-2.8.19.tgz",
"integrity": "sha512-mFNylyeyqN93lfe/9CSxOGREz8cpzAhH+E93xJ4xWQf62V8sQ/24reV2nyzUWM6H6Xji+GGHpkbLe7pVoUEskg==",
"dev": true,
"license": "MIT",
"dependencies": {
"@types/node": "*"
}
},
"node_modules/@types/estree": {
"version": "1.0.9",
"resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
@@ -2372,6 +2388,24 @@
"integrity": "sha512-NXdYc3dLr47pBkpUCHtKSwIOQXLVn8dZEuywboCOJY/osA0wFSLlSawr3KN8qXJEyX66FcONTH8EIlVuK0yyFA==",
"license": "MIT"
},
"node_modules/cors": {
"version": "2.8.6",
"resolved": "https://registry.npmjs.org/cors/-/cors-2.8.6.tgz",
"integrity": "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==",
"dev": true,
"license": "MIT",
"dependencies": {
"object-assign": "^4",
"vary": "^1"
},
"engines": {
"node": ">= 0.10"
},
"funding": {
"type": "opencollective",
"url": "https://opencollective.com/express"
}
},
"node_modules/cron-parser": {
"version": "5.10.1",
"resolved": "https://registry.npmjs.org/cron-parser/-/cron-parser-5.10.1.tgz",
@@ -2413,7 +2447,6 @@
"version": "4.4.3",
"resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
"integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
"dev": true,
"license": "MIT",
"dependencies": {
"ms": "^2.1.3"
@@ -2644,6 +2677,49 @@
"node": ">= 0.8"
}
},
"node_modules/engine.io": {
"version": "6.6.11",
"resolved": "https://registry.npmjs.org/engine.io/-/engine.io-6.6.11.tgz",
"integrity": "sha512-z34mGpLoY/82ZbkX1LqGMIaf3wjVMPL6gVC681QDqnmzJ26synI8qAE32P+a7UazmpJZ8UGrFIeAavgRfXzYrg==",
"dev": true,
"license": "MIT",
"dependencies": {
"@types/cors": "^2.8.12",
"@types/node": ">=10.0.0",
"@types/ws": "^8.5.12",
"accepts": "~1.3.4",
"cookie": "~0.7.2",
"cors": "~2.8.5",
"debug": "~4.4.1",
"engine.io-parser": "~5.2.1",
"ws": "~8.21.0"
},
"engines": {
"node": ">=10.2.0"
}
},
"node_modules/engine.io-client": {
"version": "6.6.7",
"resolved": "https://registry.npmjs.org/engine.io-client/-/engine.io-client-6.6.7.tgz",
"integrity": "sha512-GyAvmPA7gnRCpDQbYACAy79Lg4ewevrmaPzySZz0OVvgyZc3gEfLLqPTYk8wVBScjOEpM9ZO4KryyFpVItjGEA==",
"license": "MIT",
"dependencies": {
"@socket.io/component-emitter": "~3.1.0",
"debug": "~4.4.1",
"engine.io-parser": "~5.2.1",
"ws": "~8.21.0",
"xmlhttprequest-ssl": "~2.1.1"
}
},
"node_modules/engine.io-parser": {
"version": "5.2.3",
"resolved": "https://registry.npmjs.org/engine.io-parser/-/engine.io-parser-5.2.3.tgz",
"integrity": "sha512-HqD3yTBfnBxIrbnM1DoD6Pcq8NECnh8d4As1Qgh0z5Gg3jRRIqijury0CL3ghu/edArpUYiYqQiDUQBIs4np3Q==",
"license": "MIT",
"engines": {
"node": ">=10.0.0"
}
},
"node_modules/es-define-property": {
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
@@ -4124,6 +4200,63 @@
"integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",
"license": "ISC"
},
"node_modules/socket.io": {
"version": "4.8.4",
"resolved": "https://registry.npmjs.org/socket.io/-/socket.io-4.8.4.tgz",
"integrity": "sha512-9ZV9zg8vN8hO3Y25DhR7nUkJ1VDnBhq5O/JrXhFT9s6+F0gqytSASTHVfCFc2mJXaTfARroErplXlzFWwETZqQ==",
"dev": true,
"license": "MIT",
"dependencies": {
"accepts": "~1.3.4",
"cors": "~2.8.5",
"debug": "~4.4.1",
"engine.io": "~6.6.0",
"socket.io-adapter": "~2.5.2",
"socket.io-parser": "~4.2.4"
},
"engines": {
"node": ">=10.2.0"
}
},
"node_modules/socket.io-adapter": {
"version": "2.5.8",
"resolved": "https://registry.npmjs.org/socket.io-adapter/-/socket.io-adapter-2.5.8.tgz",
"integrity": "sha512-6Oy52pbg+kvdCVvjcN+FnY7BvxZ7cIHNScbvztT/It5d0vbwoJoVZmF2gjJmnV0/4WlXRfG15zc45ySk9Ah8bw==",
"dev": true,
"license": "MIT",
"dependencies": {
"debug": "~4.4.1",
"ws": "~8.21.0"
}
},
"node_modules/socket.io-client": {
"version": "4.8.4",
"resolved": "https://registry.npmjs.org/socket.io-client/-/socket.io-client-4.8.4.tgz",
"integrity": "sha512-7wjKAvVXYOJsbmUgkWbnhPD4bFpkqrUR0++XOjpGFmqDqsqV1CI93VTraeExLxpjxEqrWgFoSRZu1ihjLWfkAA==",
"license": "MIT",
"dependencies": {
"@socket.io/component-emitter": "~3.1.0",
"debug": "~4.4.1",
"engine.io-client": "~6.6.1",
"socket.io-parser": "~4.2.4"
},
"engines": {
"node": ">=10.0.0"
}
},
"node_modules/socket.io-parser": {
"version": "4.2.7",
"resolved": "https://registry.npmjs.org/socket.io-parser/-/socket.io-parser-4.2.7.tgz",
"integrity": "sha512-IH/iSeO9T6gz1KkFleGDWkG9N3dl4jXVYUtMhIqH10Md0ttMer8nUNWiP1DKuNrybD2xBrixLJdCC9J6ECoYkg==",
"license": "MIT",
"dependencies": {
"@socket.io/component-emitter": "~3.1.0",
"debug": "~4.4.1"
},
"engines": {
"node": ">=10.0.0"
}
},
"node_modules/sorted-array-functions": {
"version": "1.3.0",
"resolved": "https://registry.npmjs.org/sorted-array-functions/-/sorted-array-functions-1.3.0.tgz",
@@ -4978,6 +5111,14 @@
"node": ">=4.0"
}
},
"node_modules/xmlhttprequest-ssl": {
"version": "2.1.2",
"resolved": "https://registry.npmjs.org/xmlhttprequest-ssl/-/xmlhttprequest-ssl-2.1.2.tgz",
"integrity": "sha512-TEU+nJVUUnA4CYJFLvK5X9AOeH4KvDvhIfm0vV1GaQRtchnG0hgK5p8hw/xjv8cunWYCsiPCSDzObPyhEwq3KQ==",
"engines": {
"node": ">=0.4.0"
}
},
"node_modules/yallist": {
"version": "3.1.1",
"resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
@@ -5008,6 +5149,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"
},
@@ -5020,6 +5162,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"
}
@@ -0,0 +1 @@
ALTER TABLE `maintenance_windows` ADD `source` text;
File diff suppressed because it is too large. Load diff
+7
View File
@@ -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
}
]
}
+2
View File
@@ -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"
}
+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)));
}
/**
+93
View File
@@ -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);
});
});
+398
View File
@@ -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/);
});
});
+21 -1
View File
@@ -42,6 +42,8 @@ export interface MaintenanceWindow {
startedAt: string;
endsAt: string;
createdBy: string | null;
/** Set on windows mirrored from Uptime Kuma's schedule ("kuma:<integration>:<maintenance>"); null for ones started by hand. */
source: string | null;
}
export interface MaintenanceTargets {
@@ -773,6 +775,22 @@ export interface UptimeKumaMonitorsResponse {
summary: { total: number; up: number; down: number; pending: number; maintenance: number; unknown: number };
}
export interface UptimeKumaSyncResult {
maintenances: {
id: number;
title: string;
strategy: string;
status: string;
servers: string[];
unmatched: string[];
/** Why it produced no window, when it did not. */
note: string | null;
}[];
started: number;
updated: number;
removed: number;
}
export interface UptimeKumaImportResult {
imported: { serverId: number; serverName: string; monitorName: string; extended: boolean }[];
unmatched: string[];
@@ -1043,10 +1061,12 @@ export const api = {
}),
},
maintenance: {
list: () => request<{ windows: MaintenanceWindow[]; targets: MaintenanceTargets }>("/api/maintenance"),
list: () => request<{ windows: MaintenanceWindow[]; upcoming: MaintenanceWindow[]; targets: MaintenanceTargets }>("/api/maintenance"),
start: (data: { targetType: MaintenanceTargetType; targetId: number; minutes: number; reason?: string }) =>
request<{ window: MaintenanceWindow }>("/api/maintenance", { method: "POST", body: JSON.stringify(data) }),
end: (id: number) => request<void>(`/api/maintenance/${id}`, { method: "DELETE" }),
syncUptimeKuma: (data: { integrationId: number }) =>
request<UptimeKumaSyncResult>("/api/maintenance/sync/uptimekuma", { method: "POST", body: JSON.stringify(data) }),
importUptimeKuma: (data: { integrationId: number; minutes: number }) =>
request<UptimeKumaImportResult>("/api/maintenance/import/uptimekuma", { method: "POST", body: JSON.stringify(data) }),
},
+112 -5
View File
@@ -7,6 +7,7 @@ import {
type MaintenanceTargetType,
type MaintenanceWindow,
type UptimeKumaImportResult,
type UptimeKumaSyncResult,
} from "../api/client";
import { formatDateTime } from "../utils/date";
import { formatRemaining } from "../utils/duration";
@@ -30,6 +31,7 @@ function announceChange() {
export default function Maintenance({ user }: { user: CurrentUser }) {
const canEdit = user.role === "admin" || user.role === "operator";
const [windows, setWindows] = useState<MaintenanceWindow[] | null>(null);
const [upcoming, setUpcoming] = useState<MaintenanceWindow[]>([]);
const [targets, setTargets] = useState<MaintenanceTargets | null>(null);
const [error, setError] = useState<string | null>(null);
const [now, setNow] = useState(() => Date.now());
@@ -45,6 +47,9 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
const [kumaBusy, setKumaBusy] = useState(false);
const [kumaError, setKumaError] = useState<string | null>(null);
const [kumaResult, setKumaResult] = useState<UptimeKumaImportResult | null>(null);
const [syncBusy, setSyncBusy] = useState(false);
const [syncError, setSyncError] = useState<string | null>(null);
const [syncResult, setSyncResult] = useState<UptimeKumaSyncResult | null>(null);
useEffect(() => {
api.integrations
@@ -63,6 +68,7 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
.list()
.then((res) => {
setWindows(res.windows);
setUpcoming(res.upcoming ?? []);
setTargets(res.targets);
})
.catch((err) => setError(readableError(err)));
@@ -109,6 +115,23 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
}
}
async function syncFromUptimeKuma() {
if (kumaIntegrationId === "") return;
setSyncError(null);
setSyncResult(null);
setSyncBusy(true);
try {
const result = await api.maintenance.syncUptimeKuma({ integrationId: kumaIntegrationId });
setSyncResult(result);
load();
announceChange();
} catch (err) {
setSyncError(readableError(err));
} finally {
setSyncBusy(false);
}
}
async function importFromUptimeKuma(e: React.FormEvent) {
e.preventDefault();
if (kumaIntegrationId === "") return;
@@ -216,9 +239,16 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
<form onSubmit={importFromUptimeKuma}>
<div className="card-body row g-3">
<div className="text-secondary">
Uptime Kuma only ever tells us what's in maintenance <em>right now</em>, not for how long, so pick a
duration below — it doesn't have to match Uptime Kuma's own schedule exactly, and importing again
later just extends the window instead of stacking a second one.
<strong>Sync schedule</strong> copies Uptime Kuma's maintenance windows — the one running now and the
next one of each daily, weekly or one-off window — onto the servers their monitors belong to, so they
show up under Scheduled below and silence alerts when they start. It needs the login username and
password filled in on the integration, and runs by itself every 15 minutes when{" "}
<em>Keep maintenance windows in step</em> is ticked there.
</div>
<div className="text-secondary">
<strong>Import now</strong> only looks at what is in maintenance <em>this moment</em>: pick a duration
— it doesn't have to match Uptime Kuma's own schedule exactly, and importing again later just extends
the window instead of stacking a second one.
</div>
{kumaIntegrations.length > 1 && (
<div className="col-md-5">
@@ -248,6 +278,32 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
</select>
</div>
</div>
{syncError && (
<div className="card-body pt-0">
<div className="alert alert-danger mb-0">{syncError}</div>
</div>
)}
{syncResult && (
<div className="card-body pt-0">
<div className={`alert ${syncResult.started + syncResult.updated + syncResult.removed > 0 ? "alert-success" : "alert-info"} mb-0`}>
{syncResult.maintenances.length === 0
? "Uptime Kuma has no maintenance windows."
: `Read ${syncResult.maintenances.length} maintenance window${syncResult.maintenances.length === 1 ? "" : "s"} from Uptime Kuma: ${syncResult.started} added, ${syncResult.updated} changed, ${syncResult.removed} removed here.`}
<ul className="mb-0 mt-2">
{syncResult.maintenances.map((m) => (
<li key={m.id}>
<strong>{m.title}</strong>{" "}
<span className="text-secondary">
({m.strategy}, {m.status})
</span>
{m.servers.length > 0 ? ` → ${m.servers.join(", ")}` : m.note ? ` — nothing to schedule: ${m.note}` : ""}
{m.unmatched.length > 0 && <span className="text-secondary"> · no server for {m.unmatched.join(", ")}</span>}
</li>
))}
</ul>
</div>
</div>
)}
{kumaError && (
<div className="card-body pt-0">
<div className="alert alert-danger mb-0">{kumaError}</div>
@@ -289,8 +345,11 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
</div>
)}
<div className="card-footer d-flex align-items-center gap-3">
<button type="submit" className="btn btn-primary" disabled={kumaBusy || kumaIntegrationId === ""}>
{kumaBusy ? "Importing…" : "Import"}
<button type="button" className="btn btn-primary" onClick={syncFromUptimeKuma} disabled={syncBusy || kumaIntegrationId === ""}>
{syncBusy ? "Syncing…" : "Sync schedule"}
</button>
<button type="submit" className="btn" disabled={kumaBusy || kumaIntegrationId === ""}>
{kumaBusy ? "Importing…" : "Import now"}
</button>
{kumaIntegrationId === "" && (
<span className="text-secondary">Every Uptime Kuma integration is disabled — enable one under Integrations.</span>
@@ -300,6 +359,53 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
</div>
)}
{upcoming.length > 0 && (
<div className="card mb-3">
<div className="card-header">
<h3 className="card-title">Scheduled</h3>
</div>
<div className="table-responsive">
<table className="table table-vcenter card-table">
<thead>
<tr>
<th>Target</th>
<th>Reason</th>
<th>Starts</th>
<th>Ends</th>
{canEdit && <th className="w-1">Actions</th>}
</tr>
</thead>
<tbody>
{upcoming.map((w) => (
<tr key={w.id}>
<td>
{w.targetName} <span className="text-secondary">· {w.targetKind}</span>
</td>
<td className="text-secondary">{w.reason ?? "—"}</td>
<td>
<span className="badge bg-blue-lt text-blue me-2">in {formatRemaining(w.startedAt, now)}</span>
<span className="text-secondary small">{formatDateTime(new Date(w.startedAt))}</span>
</td>
<td className="text-secondary small">{formatDateTime(new Date(w.endsAt))}</td>
{canEdit && (
<td>
<button className="btn btn-sm btn-outline-secondary" onClick={() => end(w)}>
Cancel
</button>
</td>
)}
</tr>
))}
</tbody>
</table>
</div>
<div className="card-footer text-secondary small">
Not silencing anything yet. These start by themselves; the schedule comes from Uptime Kuma and is refreshed
every 15 minutes, so a cancelled one stays cancelled but a change in Uptime Kuma is followed.
</div>
</div>
)}
<div className="card mb-3">
<div className="card-header">
<h3 className="card-title">Active</h3>
@@ -320,6 +426,7 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
<tr key={w.id}>
<td>
{w.targetName} <span className="text-secondary">· {w.targetKind}</span>
{w.source?.startsWith("kuma:") && <span className="badge bg-cyan-lt ms-2">Uptime Kuma</span>}
</td>
<td className="text-secondary">{w.reason ?? "—"}</td>
<td>