From 16b24f543678657c9ec2fb972564f3163f0cca7f Mon Sep 17 00:00:00 2001 From: Bobban Rydh Date: Thu, 22 Oct 2026 19:14:29 +0200 Subject: [PATCH] Away mode, and critical alerts through quiet hours For a one-person homelab, "on call" is when you can be reached. Settings -> Notifications -> When -> Away holds notifications while you are away (a banner on every page says so) and sends one digest when it ends, at its time or when you say you are back. Critical alerts can still come through. Quiet hours get the same "still send critical alerts" option. Escalation steps marked to send in quiet hours are sent while away too. What is held for one reason is not released while the other still holds it. Co-Authored-By: Claude Sonnet 5.5 --- DATABASE.md | 5 +- NOTIFICATIONS.md | 23 +- README.md | 5 + ROLES.md | 1 + docs/MONITORING.md | 2 +- server/src/app.ts | 2 + server/src/index.ts | 2 + server/src/routes/away.ts | 76 ++++++ server/src/routes/settings.ts | 4 +- server/src/services/availability.ts | 61 +++++ server/src/services/awayMonitor.ts | 35 +++ server/src/services/changeLog.ts | 5 + server/src/services/notify.ts | 57 ++-- server/src/services/settingsStore.ts | 21 +- server/test/away.test.ts | 254 ++++++++++++++++++ web/src/api/client.ts | 14 + web/src/components/RoutingEditor.tsx | 2 +- web/src/layout/AppShell.tsx | 37 ++- web/src/pages/settings/AwayCard.tsx | 163 +++++++++++ .../pages/settings/NotificationSettings.tsx | 16 +- web/src/utils/settingsIndex.ts | 2 + 21 files changed, 737 insertions(+), 50 deletions(-) create mode 100644 server/src/routes/away.ts create mode 100644 server/src/services/availability.ts create mode 100644 server/src/services/awayMonitor.ts create mode 100644 server/test/away.test.ts create mode 100644 web/src/pages/settings/AwayCard.tsx diff --git a/DATABASE.md b/DATABASE.md index 9684267..4035686 100644 --- a/DATABASE.md +++ b/DATABASE.md @@ -129,7 +129,7 @@ Who changed what. Written by the app on every change (see | `id` | integer PK | | | `actor_user_id` | integer → `users.id`, **set null** on delete | Null for automatic actions, and for entries whose user was deleted. | | `actor_label` | text | The user's name/email as it was at the time (or `system`), so an entry still reads correctly after the account is gone. | -| `category` | text NOT NULL | Free text. In use: `server` (including the health check's own `went_offline`, `back_online`, `disk_full` and `disk_ok`, and `agent_updated` when a server's agent reports a higher version than before, written as `system` and shown on a server's Activity card), `integration` (including the health check's `went_failing` / `recovered` for a kind of service, with `target_type` `integration_type` and the service type as `target_id`, which the dashboard summary and the uptime ribbons read), `dns`, `settings` (including `agent_auto_update`), `ipam`, `secret`, `domain`, `tag`, `task`, `session`, `network`, `maintenance`, `consistency`, `user`, `privacy`, `diag_log`, `alert_ticket`, `dependency` (`create`, `delete` — what needs what), `endpoint` (`create`, `update`, `delete`), `restore_test` (`record`, `delete`), `push` (`subscribe`, `unsubscribe` — a browser added or removed, never its address or keys), `share_link` (a link made or removed, and `update_status_page` when what a status page shows is changed — never the secret), `runbook`, `alert` (`ack`, `unack` — with the alert's id; on the thing it is about, so they show on a server's Activity card), `incident` (`note`, `note_removed`), `db_backup` (`create`, `upload`, `download`, `delete`, `restore_staged`, `restore_cancelled`, `settings`), `update_run` (`start`, `finished`, `failed`, `cancelled` — shown on the server's Activity card), `inventory`, `metrics_token` and `webhook` (made, changed or removed — never a secret or an address). `user` also records `role_from_groups` when a sign-in changed someone's role. | +| `category` | text NOT NULL | Free text. In use: `server` (including the health check's own `went_offline`, `back_online`, `disk_full` and `disk_ok`, and `agent_updated` when a server's agent reports a higher version than before, written as `system` and shown on a server's Activity card), `integration` (including the health check's `went_failing` / `recovered` for a kind of service, with `target_type` `integration_type` and the service type as `target_id`, which the dashboard summary and the uptime ribbons read), `dns`, `settings` (including `agent_auto_update`), `ipam`, `secret`, `domain`, `tag`, `task`, `session`, `network`, `maintenance`, `consistency`, `user`, `privacy`, `diag_log`, `alert_ticket`, `dependency` (`create`, `delete` — what needs what), `endpoint` (`create`, `update`, `delete`), `restore_test` (`record`, `delete`), `push` (`subscribe`, `unsubscribe` — a browser added or removed, never its address or keys), `share_link` (a link made or removed, and `update_status_page` when what a status page shows is changed — never the secret), `runbook`, `alert` (`ack`, `unack` — with the alert's id; on the thing it is about, so they show on a server's Activity card), `incident` (`note`, `note_removed`), `db_backup` (`create`, `upload`, `download`, `delete`, `restore_staged`, `restore_cancelled`, `settings`), `away` (`start`, `end` — with `automatic: true` when its time ran out), `update_run` (`start`, `finished`, `failed`, `cancelled` — shown on the server's Activity card), `inventory`, `metrics_token` and `webhook` (made, changed or removed — never a secret or an address). `user` also records `role_from_groups` when a sign-in changed someone's role. | | `action` | text NOT NULL | `create`, `update`, `delete`, `start`, `stop`, … — free text. | | `target_type`, `target_id` | text | What it happened to. `target_id` is text so it can hold any kind of ID; there's no foreign key. | | `detail` | text | JSON, free-form context (what changed, names, counts). Secrets are never put here. | @@ -1139,7 +1139,8 @@ that were never changed aren't stored; the app fills in defaults when reading. | `escalation` | `enabled` (false) and up to three `steps` of `{afterMinutes, minSeverity, channels, extraEmail, evenInQuietHours}`, in time order. | | `webPush` | Push to phones and browsers: `enabled` (false) and `contact` (an email or https address the push services may reach whoever runs this on; blank is fine). Who is subscribed is in `push_subscriptions`; the server's key pair is below. | | `notifications` | Which events notify (`dnsAdd`, `healthAlerts`, …), the daily-reminder time (`secretCheckTime`, default `08:00`) and `timezone` (default `UTC`), and the integration-failure threshold (default 3). | -| `quietHours` | `enabled`, `start`, `end`. | +| `quietHours` | `enabled`, `start`, `end`, `criticalThrough` (false — a critical alert is sent at once even inside the window). | +| `away` | Away mode: `until` (ISO, null when nobody is away), `from` (ISO, null when it began when it was set, or a later moment for one planned ahead), `criticalThrough` (true — critical alerts are still sent), `note`. An away stretch whose `until` has passed is cleared by a check every minute, which also sends what was held. | | `signIn` | Roles from groups: `roleFromGroups` (false), `groupsClaim` (`groups`), `adminGroups`, `operatorGroups`, `otherwise` (`viewer` or `keep`). | | `profilePictures` | Where pictures of people come from: `identityProvider` (false) and `gravatar` (false). Either one means the server fetches pictures from an outside address; they are checked, kept for a day and served from this app. | | `alertActions` | `enabled` (false): whether notifications carry buttons and links to acknowledge, silence and snooze (see NOTIFICATIONS.md). The links are signed tokens, so nothing about them is stored. | diff --git a/NOTIFICATIONS.md b/NOTIFICATIONS.md index 58966c8..b58e1ee 100644 --- a/NOTIFICATIONS.md +++ b/NOTIFICATIONS.md @@ -23,7 +23,11 @@ it: instead of sent immediately, then delivered as a single digest at the window's end time. This matters most for the real-time alerts below — the daily reminders already fire once at a time you pick, usually - outside the window anyway. + outside the window anyway. *Still send critical alerts* (off by default) + lets a **critical** one — a server down, a disk full, mains power lost — + through at once, so only the warnings wait for the morning. +- **Away** (Settings → Notifications → When, and a banner on every page while + it is on): "I'm away until Sunday". See [Away](#away). - **Maintenance windows** (the Maintenance page): opening one for a server, integration, or DNS provider silences the alerts that target it specifically (offline/disk-full for a server; storage, backup, and @@ -59,7 +63,7 @@ and only some kinds of alert — a phone for the critical things, a desktop for **Escalation.** When an alert has been raised for a while and **nobody has acknowledged it**, it is told again, in up to three steps — for example *after 30 minutes: push; after 2 hours: email the neighbour who holds the key*. Each step names its time, the least severity it applies to, the channels to use (chosen freely — routing rules don't apply to escalations), an optional extra email address to tell as well (sent through the email channel's server) and -whether to send during quiet hours (otherwise it waits for them to end like any other). Every step is sent once per alert; an acknowledgement stops the +whether to send during quiet hours and while away (otherwise it waits for them to end like any other). Every step is sent once per alert; an acknowledgement stops the rest, and the alert starts over if it goes away and comes back. Problems under maintenance, held back because something they depend on is down, or only informational never escalate. It is looked at every five minutes, so a step can arrive a few minutes after its time. Every escalation is written in the audit log (category *alert*, action *escalate*). @@ -210,6 +214,21 @@ Each link is a **signed token** for the alerts in that message only, valid for * notification time zone). Opening it shows a page that says what each button would do and changes nothing; only a button press does anything. What was done is in the audit log, *from a notification link*, with the address it came from. **Anyone who can read the notification can use it** for those 24 hours. A message held for quiet hours is sent without buttons; recovery messages never have them. +## Away + +For a stretch rather than every night. **Settings → Notifications → When → Away** takes the time you will be back (with shortcuts: tomorrow evening, Sunday evening, a week, two weeks), optionally a start later than now (to plan a +holiday ahead), a note to yourself and whether to **still send critical alerts**. While it lasts: + +- notifications are **held** — the same queue quiet hours use — and a banner on every page says that someone is away and how many are held; +- **critical** alerts still go out at once, if that box is ticked (it is by default); with it off, nothing does; +- at the time you gave, or when you press **I'm back**, what was held is sent as **one digest** — "Homelab Manager — Notifications from while you were away" — to the channels each was meant for, and the away stretch is cleared. It is looked at every + minute, and also right after the app restarts, so it ends within a minute of its time; +- an **escalation** step that says *send even during quiet hours* is sent while away too — that is what it is for, for example an email to the neighbour who holds the key; +- if quiet hours are on at that moment, the digest waits for them to end; if you come back in the middle of an away stretch's quiet hours nothing is lost. + +What it does **not** do: it does not stop the alerts themselves — they are on the Alerts page, in the event webhooks and in `/metrics` as ever, so a Home Assistant or Grafana setup still sees everything; it only holds the *messages to you*. Away mode is an +administrator's to set (it decides who is told what), everyone sees the banner, and starting, changing and ending it are in the audit log and the Change log. Times typed there are the clock of the screen they are typed on. + ## Flapping alerts A health alert that is raised, clears and is raised again is announced the first times as usual. When the same alert has been raised **three times within an hour** (Settings → Notifications → *Servers and disks*; 0 = off) it is *flapping*: diff --git a/README.md b/README.md index a51f753..0f228be 100644 --- a/README.md +++ b/README.md @@ -851,6 +851,11 @@ hours (maintenance), is handed to you or is still going is counted in the badge **A server's page in sections.** Overview (links, hardware, identity, runbooks), Health, Network (what it is connected through, ports), History (trends, activity), Tasks (scheduled tasks, run a playbook) and Settings (Proxmox link, its own alert limits), switched by `?view=`, so a section can be linked to: an alert about a failing service opens the Health section, a new-port alert the Network section. +**Away mode, and critical alerts through the night.** For a one-person homelab, "on call" is about *when you can be reached*. **Settings → Notifications → When → Away** is a one-off "I'm away until Sunday evening": notifications are held while it lasts +(a banner on every page says so and counts them) and sent as **one digest** when it ends — at the time you gave, or when you press *I'm back* — so a week away is one message to read, not a buzzing phone. **Critical** alerts (a server down, a disk full, mains +power lost) can still come through at once, which is the default; untick it for true silence. You can plan one ahead (start later) and add a note. **Quiet hours** got the same option, *Still send critical alerts*, off by default: a full disk at 03:00 is +sent, the warnings wait for the morning. Escalation steps marked *send even during quiet hours* are sent while away too. Held messages only: the alerts themselves are still on the Alerts page, in webhooks and in `/metrics`. See NOTIFICATIONS.md. + **Finding a setting, and undo instead of asking.** Settings has a *Find a setting* box (and the command palette lists every setting too) that goes straight to where it is set — it knows what each is for, so "quiet", "prometheus" or "disk full" all find something. Removing a dependency, an admin link, a runbook, a hand-made IP address (one or several), a port opening or a restore test no longer asks first: it is gone at once, with an **Undo** on the message for fifteen seconds that makes it again from what was on screen. Things that could not come back as they were — a secret, a check with its history, a share link or token, a DNS record, a hardware entry that has labels printed with its number — still ask first. diff --git a/ROLES.md b/ROLES.md index 41f6fc9..fe3dec7 100644 --- a/ROLES.md +++ b/ROLES.md @@ -116,6 +116,7 @@ even further, to admin only: **Settings search** is part of Settings, which is administrators'. - **Network devices** (Network → Network devices): everyone can see the devices, networks and Wi-Fi names read from UniFi controllers; **Read now** and putting a device under maintenance need operator; adding the UniFi integration itself (a key or login) is an administrator's job, like any integration. +- **Away mode** (Settings → Notifications → When): administrators start, plan, change and end it, since it decides who is told what; everyone signed in sees the banner that says someone is away and how many notifications are held. - **Buttons on notifications** (Settings → Notifications → Who hears what): switching them on is administrator-only. A link in a notification needs **no role at all** — the signed token is the access, for the alerts in that message, for 24 hours, to acknowledge, silence for an hour or snooze, and nothing else. - **Alert rules** (Monitoring → Alert rules): everyone signed in sees the rules and where each is raised now; making, changing, trying, switching and removing one is administrator-only (a rule decides who is woken up). **Snooze** an alert, and wake it, need operator, like acknowledging. The storage forecast beside Proxmox storages and Synology volumes is for everyone who can see those pages. diff --git a/docs/MONITORING.md b/docs/MONITORING.md index 682d534..24843d5 100644 --- a/docs/MONITORING.md +++ b/docs/MONITORING.md @@ -273,7 +273,7 @@ Several things can quiet an alert. They are different, and it matters which you ### Who hears about it Notifications go to the channels that are on (**Gotify, ntfy, email, a webhook, push to phones and browsers**), narrowed by **routing rules** (first match wins: by kind, by severity, by the server's tags) and each -browser's own wishes. **Quiet hours** hold messages and send one digest at the end of the window. Every message the app can send, and what toggles it, is in [NOTIFICATIONS.md](../NOTIFICATIONS.md). +browser's own wishes. **Quiet hours** hold messages and send one digest at the end of the window (critical alerts can be let through); **Away** mode does the same for a stretch you set, "until Sunday". Every message the app can send, and what toggles it, is in [NOTIFICATIONS.md](../NOTIFICATIONS.md). **Event webhooks** are a separate way of being told, for machines: they hear every raise and clear, flapping and snoozed included ([WEBHOOKS.md](WEBHOOKS.md)). ### Flapping diff --git a/server/src/app.ts b/server/src/app.ts index 847f987..c2219a4 100644 --- a/server/src/app.ts +++ b/server/src/app.ts @@ -56,6 +56,7 @@ import { dataUsageRouter } from "./routes/dataUsage.js"; import { alertActionsRouter } from "./routes/alertActions.js"; import { homeAssistantRouter } from "./routes/homeAssistant.js"; import { upsRouter } from "./routes/ups.js"; +import { awayRouter } from "./routes/away.js"; import { serviceLevelsRouter } from "./routes/serviceLevels.js"; import { publicApiRouter } from "./routes/publicApi.js"; import { generatorRouter } from "./routes/generator.js"; @@ -187,6 +188,7 @@ export function createApp() { app.use("/api/data-usage", dataUsageRouter); app.use("/api/home-assistant", homeAssistantRouter); app.use("/api/ups", upsRouter); + app.use("/api/away", awayRouter); app.use("/api/service-levels", serviceLevelsRouter); app.use("/api/todos", todosRouter); app.use("/api/notes", notesRouter); diff --git a/server/src/index.ts b/server/src/index.ts index f18bcd1..49ac41b 100644 --- a/server/src/index.ts +++ b/server/src/index.ts @@ -28,6 +28,7 @@ import { initSnoozeMonitor } from "./services/snoozeMonitor.js"; import { initUnifiSync } from "./services/unifiSync.js"; import { initHomeAssistantSync } from "./services/homeAssistantSync.js"; import { initUpsSync } from "./services/upsSync.js"; +import { initAwayMonitor } from "./services/awayMonitor.js"; import { backfillMetricRollups } from "./services/serverMetrics.js"; import { backfillEndpointHourly } from "./services/endpointChecks.js"; import { initSelfBackupScheduler } from "./services/selfBackupScheduler.js"; @@ -77,6 +78,7 @@ initSnoozeMonitor(); initUnifiSync(); initHomeAssistantSync(); initUpsSync(); +initAwayMonitor(); // The hourly and daily figures are built from what is already kept, once, the first time after they were added (in the background: nothing waits for it). void Promise.all([backfillMetricRollups(), backfillEndpointHourly()]).catch((err) => console.error("[history] couldn't build the hourly and daily figures:", err)); diff --git a/server/src/routes/away.ts b/server/src/routes/away.ts new file mode 100644 index 0000000..98c1bd1 --- /dev/null +++ b/server/src/routes/away.ts @@ -0,0 +1,76 @@ +import { Router } from "express"; +import { z } from "zod"; +import { requireAuth, requireRole } from "../auth/middleware.js"; +import { recordAudit } from "../services/audit.js"; +import { awayState } from "../services/availability.js"; +import { endAway } from "../services/awayMonitor.js"; +import { zonedTime } from "../services/maintenanceSchedules.js"; +import { listQueuedNotifications } from "../services/notificationQueue.js"; +import { getSettings, updateSettings } from "../services/settingsStore.js"; +import { asyncHandler } from "../utils/asyncHandler.js"; + +export const awayRouter = Router(); +awayRouter.use(requireAuth); + +export const MAX_AWAY_DAYS = 120; +const DAY_MS = 86_400_000; + +/** A wall-clock time ("2026-10-25T18:00") is on the clock of the notification time zone, like every other time in the settings; a full ISO moment is itself. */ +export function momentOf(text: string, timezone: string): Date | null { + if (/Z$|[+-]\d{2}:?\d{2}$/.test(text)) { + const t = Date.parse(text); + return Number.isFinite(t) ? new Date(t) : null; + } + const m = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/.exec(text); + if (!m) return null; + return zonedTime(Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4]), Number(m[5]), timezone); +} + +const bodySchema = z.object({ + until: z.string().min(1), + from: z.string().nullable().optional(), + criticalThrough: z.boolean().optional(), + note: z.string().trim().max(200).optional(), +}); + +async function view() { + const { away, notifications } = await getSettings(); + const now = new Date(); + return { away: { ...away, state: awayState(away, now) }, held: (await listQueuedNotifications()).length, timezone: notifications.timezone || "UTC" }; +} + +// Whether somebody is away, for the banner everyone sees; and how many notifications are being held. +awayRouter.get("/", asyncHandler(async (_req, res) => { + res.json(await view()); +})); + +// Starts, plans or changes an away stretch: administrators, since it decides who is told what. +awayRouter.put("/", requireRole("admin"), asyncHandler(async (req, res) => { + const parsed = bodySchema.safeParse(req.body); + if (!parsed.success) return res.status(400).json({ error: "invalid_body", message: "Say until when." }); + const settings = await getSettings(); + const tz = settings.notifications.timezone || "UTC"; + const now = new Date(); + const until = momentOf(parsed.data.until, tz); + const from = parsed.data.from ? momentOf(parsed.data.from, tz) : null; + if (!until) return res.status(400).json({ error: "invalid_until", message: "That isn't a time." }); + if (parsed.data.from && !from) return res.status(400).json({ error: "invalid_from", message: "That isn't a start time." }); + if (until.getTime() <= now.getTime()) return res.status(400).json({ error: "in_the_past", message: "That time has already passed." }); + if (until.getTime() > now.getTime() + MAX_AWAY_DAYS * DAY_MS) return res.status(400).json({ error: "too_long", message: `At most ${MAX_AWAY_DAYS} days ahead.` }); + if (from && from.getTime() >= until.getTime()) return res.status(400).json({ error: "bad_range", message: "It has to start before it ends." }); + const criticalThrough = parsed.data.criticalThrough ?? settings.away.criticalThrough; + const note = parsed.data.note ?? ""; + // A start that has already come is simply "now". + const startIso = from && from.getTime() > now.getTime() ? from.toISOString() : null; + await updateSettings({ away: { from: startIso, until: until.toISOString(), criticalThrough, note } }); + await recordAudit({ actor: req.currentUser!, category: "away", action: "start", detail: { from: startIso, until: until.toISOString(), criticalThrough, ...(note ? { note } : {}) } }); + res.json(await view()); +})); + +// "I'm back": ends it now (or cancels one planned), and sends what was held as one digest. +awayRouter.delete("/", requireRole("admin"), asyncHandler(async (req, res) => { + const { away } = await getSettings(); + if (!away.until) return res.status(404).json({ error: "not_away", message: "Nobody is away." }); + const sent = await endAway({ automatic: false, actor: req.currentUser! }); + res.json({ ...(await view()), sent }); +})); diff --git a/server/src/routes/settings.ts b/server/src/routes/settings.ts index 8dedf39..04c0ae9 100644 --- a/server/src/routes/settings.ts +++ b/server/src/routes/settings.ts @@ -148,7 +148,7 @@ const updateSchema = z.object({ .partial() .optional(), quietHours: z - .object({ enabled: z.boolean(), start: z.string().regex(/^\d{2}:\d{2}$/), end: z.string().regex(/^\d{2}:\d{2}$/) }) + .object({ enabled: z.boolean(), start: z.string().regex(/^\d{2}:\d{2}$/), end: z.string().regex(/^\d{2}:\d{2}$/), criticalThrough: z.boolean() }) .partial() .optional(), signIn: z @@ -312,7 +312,7 @@ settingsRouter.get("/quiet-hours-queue", requireRole("admin"), asyncHandler(asyn })); settingsRouter.post("/flush-quiet-hours", requireRole("admin"), asyncHandler(async (req, res) => { - const flushed = await flushQuietHoursQueue(); + const flushed = await flushQuietHoursQueue({ force: true }); await recordAudit({ actor: req.currentUser!, category: "settings", action: "flush_quiet_hours", detail: { flushed } }); res.json({ flushed }); })); diff --git a/server/src/services/availability.ts b/server/src/services/availability.ts new file mode 100644 index 0000000..d712e37 --- /dev/null +++ b/server/src/services/availability.ts @@ -0,0 +1,61 @@ +/** + * When are notifications held back rather than sent? Two things hold them: **quiet hours** (a daily window) and **away** (a stretch somebody set: "I'm away until Sunday"). + * A held notification is queued and delivered as one digest when the hold ends. Either can let *critical* alerts through (so a full disk at 03:00 or the lights going out while + * away still reach the person who can do something about it) — or not, for those who want true silence. + * + * This is only the decision. Sending, queueing and the digest are in notify.ts; ending an away stretch when its time comes is awayMonitor.ts. + */ +import { getSettings, type AwaySettings, type QuietHoursSettings } from "./settingsStore.js"; + +export type HoldReason = "away" | "quiet"; +/** No away stretch, one set for later, one going on now. */ +export type AwayState = "none" | "planned" | "active"; + +/** Pure: where an away stretch stands at `now`. One whose end has passed is over (and is cleared by the monitor). */ +export function awayState(away: Pick, now: Date): AwayState { + if (!away.until) return "none"; + const until = Date.parse(away.until); + if (!Number.isFinite(until) || until <= now.getTime()) return "none"; + const from = away.from ? Date.parse(away.from) : NaN; + return Number.isFinite(from) && from > now.getTime() ? "planned" : "active"; +} + +const toMinutes = (hhmm: string) => { + const [h, m] = hhmm.split(":").map(Number); + return (Number.isFinite(h) ? h : 0) * 60 + (Number.isFinite(m) ? m : 0); +}; + +function clockIn(timezone: string, now: Date): number { + let parts: Intl.DateTimeFormatPart[]; + try { + parts = new Intl.DateTimeFormat("en-GB", { timeZone: timezone, hour: "2-digit", minute: "2-digit", hour12: false }).formatToParts(now); + } catch { + parts = new Intl.DateTimeFormat("en-GB", { timeZone: "UTC", hour: "2-digit", minute: "2-digit", hour12: false }).formatToParts(now); + } + return (Number(parts.find((p) => p.type === "hour")?.value ?? "0") % 24) * 60 + Number(parts.find((p) => p.type === "minute")?.value ?? "0"); +} + +/** Pure: is `now` inside the quiet-hours window, on the clock of the time zone? A window that wraps past midnight (22:00 → 07:00) is the usual case. */ +export function inQuietWindow(quiet: Pick, timezone: string, now: Date): boolean { + if (!quiet.enabled) return false; + const nowMin = clockIn(timezone, now); + const start = toMinutes(quiet.start); + const end = toMinutes(quiet.end); + if (start === end) return false; // a zero-length window is never on + return start < end ? nowMin >= start && nowMin < end : nowMin >= start || nowMin < end; +} + +/** + * Pure: why a notification is held right now, or null if it goes out. Being away is checked first — it is the stronger statement. A critical one is let through when the + * thing holding it says so. + */ +export function holdFor(settings: { away: AwaySettings; quietHours: QuietHoursSettings; timezone: string }, critical: boolean, now: Date): HoldReason | null { + if (awayState(settings.away, now) === "active" && !(critical && settings.away.criticalThrough)) return "away"; + if (inQuietWindow(settings.quietHours, settings.timezone, now) && !(critical && settings.quietHours.criticalThrough)) return "quiet"; + return null; +} + +export async function holdReason(critical: boolean, now: Date = new Date()): Promise { + const s = await getSettings(); + return holdFor({ away: s.away, quietHours: s.quietHours, timezone: s.notifications.timezone }, critical, now); +} diff --git a/server/src/services/awayMonitor.ts b/server/src/services/awayMonitor.ts new file mode 100644 index 0000000..c208478 --- /dev/null +++ b/server/src/services/awayMonitor.ts @@ -0,0 +1,35 @@ +/** + * Away mode's moving parts: when somebody says they are back (or the time they gave arrives), what was held while they were away is sent as one digest and the stretch + * is cleared. Looked at every minute, so it ends within a minute of its time, and also right after the app has been restarted. + */ +import { recordAudit } from "./audit.js"; +import { flushQuietHoursQueue } from "./notify.js"; +import { awayState } from "./availability.js"; +import { getSettings, updateSettings } from "./settingsStore.js"; + +const CHECK_MS = 60_000; + +/** Clears the away stretch and sends what was held. Returns how many notifications went out in the digest (0 if quiet hours are holding them still). */ +export async function endAway(options: { automatic: boolean; actor?: Parameters[0]["actor"] }): Promise { + const { away } = await getSettings(); + await updateSettings({ away: { from: null, until: null, note: "" } }); + await recordAudit({ actor: options.actor, category: "away", action: "end", detail: { automatic: options.automatic, wasUntil: away.until } }); + return flushQuietHoursQueue({ reason: "away" }); +} + +/** Ends an away stretch whose time has come. True if one was ended. */ +export async function endAwayIfOver(now: Date = new Date()): Promise { + const { away } = await getSettings(); + if (!away.until || awayState(away, now) !== "none") return false; + await endAway({ automatic: true }); + return true; +} + +let timer: ReturnType | null = null; + +export function initAwayMonitor(): void { + if (timer) return; + const check = () => void endAwayIfOver().catch((err) => console.error("[away] couldn't end the away stretch:", err)); + timer = setInterval(check, CHECK_MS); + setTimeout(check, 15_000); +} diff --git a/server/src/services/changeLog.ts b/server/src/services/changeLog.ts index 7a07344..78ef561 100644 --- a/server/src/services/changeLog.ts +++ b/server/src/services/changeLog.ts @@ -42,6 +42,7 @@ const KIND_OF_CATEGORY: Record = { api_token: "settings", alert_rule: "alerts", service_level: "endpoints", + away: "settings", todo: "other", note: "servers", webhook: "settings", @@ -182,6 +183,10 @@ export function describeChange(category: string, action: string, detail: Record< return { title: detail.change === "undo" ? "A change to several pieces of hardware was undone" : `${typeof detail.changed === "number" ? detail.changed : "Several"} piece${detail.changed === 1 ? "" : "s"} of hardware changed at once`, tone: "neutral", detail: genericSummary(detail, ["ids", "changed", "change"]) }; case "webhook/retry": return { title: `A webhook message was sent again${name ? `: ${name}` : str(detail.label) ? `: ${str(detail.label)}` : ""}`, tone: detail.ok === false ? "bad" : "neutral", detail: str(detail.event) }; + case "away/start": + return { title: `Away mode started${str(detail.note) ? `: ${str(detail.note)}` : ""}`, tone: "neutral", detail: `until ${str(detail.until)?.slice(0, 16).replace("T", " ") ?? "?"} UTC${detail.criticalThrough ? ", critical alerts still sent" : ", everything held"}` }; + case "away/end": + return { title: detail.automatic ? "Away mode ended" : "Back from away", tone: "neutral", detail: null }; case "service_level/create": return { title: `Service-level target set${name ? `: ${name}` : ""}`, tone: "neutral", detail: typeof detail.target === "number" ? `${detail.target}%` : null }; case "service_level/update": diff --git a/server/src/services/notify.ts b/server/src/services/notify.ts index 8f5bc2f..5093b9f 100644 --- a/server/src/services/notify.ts +++ b/server/src/services/notify.ts @@ -1,5 +1,6 @@ import nodemailer from "nodemailer"; import { getSettings, type NotificationEvents } from "./settingsStore.js"; +import { holdFor, holdReason } from "./availability.js"; import { enqueueNotification, listQueuedNotifications, clearQueuedNotifications } from "./notificationQueue.js"; import { emitEvent } from "./eventWebhooks.js"; import { sendPush, subscriptionCount } from "./webPush.js"; @@ -185,9 +186,10 @@ async function sendToChannels(title: string, message: string, audience: Audience * Sends to an audience that is already worked out: held for the quiet-hours digest if it is quiet (unless told not to), nowhere if a rule * said nobody. Escalations use this with their own channels. */ -export async function notifyAudience(title: string, message: string, audience: Audience, options: { quietHours?: boolean; actions?: NotifyActions | null } = {}): Promise { +export async function notifyAudience(title: string, message: string, audience: Audience, options: { quietHours?: boolean; actions?: NotifyActions | null; critical?: boolean } = {}): Promise { if (isMuted(audience)) return; - if (options.quietHours !== false && (await isQuietHoursActive())) { + // Held when quiet hours or an away stretch say so — unless it is critical and they let critical through (services/availability.ts). + if (options.quietHours !== false && (await holdReason(options.critical === true))) { await enqueueNotification(title, message, audience.channels === null && audience.pushIds === null && !audience.email ? null : JSON.stringify(audience)); return; } @@ -207,39 +209,11 @@ async function notifyGrouped(items: T[], metaOf: (item: T) => NotifyMeta, bui for (const group of groups.values()) { const { title, message } = build(group.items); // Buttons, when the message is about alerts that have a key and an administrator has switched them on (a message held for quiet hours is sent without them). - await notifyAudience(title, message, group.audience, keysOf ? { actions: await actionsFor(group.items.map(keysOf)) } : {}); + const critical = group.items.some((i) => metaOf(i).severity === "critical"); + await notifyAudience(title, message, group.audience, { critical, ...(keysOf ? { actions: await actionsFor(group.items.map(keysOf)) } : {}) }); } } -function currentTimeInZone(timezone: string): { hh: number; mm: number } { - const parts = new Intl.DateTimeFormat("en-GB", { timeZone: timezone, hour: "2-digit", minute: "2-digit", hour12: false }).formatToParts( - new Date(), - ); - return { - hh: Number(parts.find((p) => p.type === "hour")?.value ?? "0"), - mm: Number(parts.find((p) => p.type === "minute")?.value ?? "0"), - }; -} - -function toMinutes(hhmm: string): number { - const [h, m] = hhmm.split(":").map(Number); - return (Number.isFinite(h) ? h : 0) * 60 + (Number.isFinite(m) ? m : 0); -} - -async function isQuietHoursActive(): Promise { - const { quietHours, notifications } = await getSettings(); - if (!quietHours.enabled) return false; - const { hh, mm } = currentTimeInZone(notifications.timezone); - const nowMin = hh * 60 + mm; - const startMin = toMinutes(quietHours.start); - const endMin = toMinutes(quietHours.end); - if (startMin === endMin) return false; // zero-length window — treat as always off - // A same-day window (e.g. 09:00 -> 17:00) is a simple range; a window that - // wraps past midnight (e.g. 22:00 -> 07:00, the common case) means "active" - // is everything outside [end, start) instead. - return startMin < endMin ? nowMin >= startMin && nowMin < endMin : nowMin >= startMin || nowMin < endMin; -} - /** Sends at once through every channel that is switched on, whatever the time — for something a person just asked for. */ export async function notifyNow(title: string, message: string): Promise { await sendToChannels(title, message); @@ -259,11 +233,20 @@ export async function enabledChannelCount(): Promise { /** `meta` says what it is about, so routing rules and browsers' wishes can apply; without it, it goes to everyone. */ export async function notify(title: string, message: string, meta?: NotifyMeta): Promise { - await notifyAudience(title, message, await audienceFor(meta)); + await notifyAudience(title, message, await audienceFor(meta), { critical: meta?.severity === "critical" }); } -/** Called by the daily scheduler at quiet-hours end (or manually) — sends everything queued during the window as one digest, then clears it. */ -export async function flushQuietHoursQueue(): Promise { +/** + * Sends everything held as one digest per audience, then clears the queue: called when quiet hours end, when an away stretch ends, or by hand (`force`). What is held for one + * reason is not let out while the other still holds it: quiet hours ending in the middle of a holiday release nothing, and coming back at 02:00 releases nothing until morning. + */ +export async function flushQuietHoursQueue(options: { reason?: "quiet" | "away"; force?: boolean } = {}): Promise { + const reason = options.reason ?? "quiet"; + if (!options.force) { + const s = await getSettings(); + const held = holdFor({ away: s.away, quietHours: s.quietHours, timezone: s.notifications.timezone }, false, new Date()); + if (held !== null) return 0; + } const queued = await listQueuedNotifications(); if (queued.length === 0) return 0; // One digest for each audience the held notifications were for. @@ -278,8 +261,8 @@ export async function flushQuietHoursQueue(): Promise { } const sections = items.map((q) => `— ${q.title} —\n${q.message}`); await sendToChannels( - "Homelab Manager — Notifications from quiet hours", - `${items.length} notification${items.length !== 1 ? "s were" : " was"} held during quiet hours:\n\n${sections.join("\n\n")}`, + reason === "away" ? "Homelab Manager — Notifications from while you were away" : "Homelab Manager — Notifications from quiet hours", + `${items.length} notification${items.length !== 1 ? "s were" : " was"} held ${reason === "away" ? "while you were away" : "during quiet hours"}:\n\n${sections.join("\n\n")}`, audience, ); } diff --git a/server/src/services/settingsStore.ts b/server/src/services/settingsStore.ts index 75a17dd..faaf93f 100644 --- a/server/src/services/settingsStore.ts +++ b/server/src/services/settingsStore.ts @@ -98,6 +98,23 @@ export interface QuietHoursSettings { start: string; /** "HH:MM" — when `start`..`end` wraps past midnight (e.g. 22:00 -> 07:00), the queue is flushed as one digest at this time. */ end: string; + /** A critical alert is sent at once even inside the window (a full disk at 03:00); everything else still waits. */ + criticalThrough: boolean; +} + +/** + * Away: "I'm away until Sunday". While it lasts, notifications are held (like quiet hours, but for as long as it says) and sent as one digest when it ends — at its time, or + * when somebody says they are back. `until` is null when nobody is away; `from` is null when it began when it was set, or a later moment for one planned ahead. + */ +export interface AwaySettings { + /** ISO. */ + from: string | null; + /** ISO. */ + until: string | null; + /** A critical alert is sent at once even while away. */ + criticalThrough: boolean; + /** What to remember about it ("Holiday in Spain"). */ + note: string; } export interface HealthCheckSettings { @@ -251,6 +268,7 @@ export interface AppSettings { display: DisplaySettings; logRetention: LogRetentionSettings; quietHours: QuietHoursSettings; + away: AwaySettings; healthChecks: HealthCheckSettings; digest: DigestSettings; monthlyReport: MonthlyReportSettings; @@ -295,7 +313,8 @@ const DEFAULTS: AppSettings = { integrationColors: {}, display: { dateFormat: "ymd", timeFormat: "24h", pageSize: 20 }, logRetention: { enabled: false, retentionDays: 90, intervalHours: 24 }, - quietHours: { enabled: false, start: "22:00", end: "07:00" }, + quietHours: { enabled: false, start: "22:00", end: "07:00", criticalThrough: false }, + away: { from: null, until: null, criticalThrough: true, note: "" }, digest: { enabled: false, day: 1, time: "08:00" }, monthlyReport: { enabled: false, quarterly: false, annual: false, day: 1, time: "08:00" }, inventory: { currency: "", pricePerKwh: null }, diff --git a/server/test/away.test.ts b/server/test/away.test.ts new file mode 100644 index 0000000..7094f2f --- /dev/null +++ b/server/test/away.test.ts @@ -0,0 +1,254 @@ +/** + * Away mode and what lets critical alerts through: when a notification is held (quiet hours, away), who it is let through for, what is sent when the hold ends, and the route + * that starts, plans and ends an away stretch. + * + * Run with: npm test --workspace server + */ +import { test, describe, before, after } from "node:test"; +import assert from "node:assert/strict"; +import { createServer as createHttpServer, type Server } from "node:http"; +import { mkdtempSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import type { AddressInfo } from "node:net"; + +const dir = mkdtempSync(join(tmpdir(), "hm-away-")); +process.env.DATABASE_PATH = join(dir, "test.sqlite"); +process.env.SESSION_DIR = join(dir, "sessions"); +process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32); +process.env.HEALTH_STARTUP_GRACE_MS = "0"; + +const express = (await import("express")).default; +const { db } = await import("../src/db/client.js"); +const { users, auditLog } = await import("../src/db/schema.js"); +const { runMigrations } = await import("../src/db/migrate.js"); +const avail = await import("../src/services/availability.js"); +const { endAwayIfOver } = await import("../src/services/awayMonitor.js"); +const { notify, notifyAudience, flushQuietHoursQueue, notifyHealthIssues } = await import("../src/services/notify.js"); +const { listQueuedNotifications, clearQueuedNotifications } = await import("../src/services/notificationQueue.js"); +const { awayRouter, momentOf } = await import("../src/routes/away.js"); +const { getSettings, updateSettings } = await import("../src/services/settingsStore.js"); +const { eq } = await import("drizzle-orm"); + +await runMigrations(); + +const NOW = new Date("2026-10-20T12:00:00Z"); +const HOUR = 3_600_000; +const iso = (ms: number) => new Date(ms).toISOString(); + +describe("when is a notification held", () => { + const away = (from: number | null, until: number | null, criticalThrough = true) => ({ from: from === null ? null : iso(from), until: until === null ? null : iso(until), criticalThrough, note: "" }); + const quiet = (criticalThrough = false) => ({ enabled: true, start: "22:00", end: "07:00", criticalThrough }); + + test("an away stretch is none, planned, active or over", () => { + const t = NOW.getTime(); + assert.equal(avail.awayState(away(null, null), NOW), "none"); + assert.equal(avail.awayState(away(null, t + HOUR), NOW), "active", "no start means it began when it was set"); + assert.equal(avail.awayState(away(t - HOUR, t + HOUR), NOW), "active"); + assert.equal(avail.awayState(away(t + HOUR, t + 2 * HOUR), NOW), "planned"); + assert.equal(avail.awayState(away(null, t - 1), NOW), "none", "over"); + assert.equal(avail.awayState({ from: null, until: "nonsense" }, NOW), "none"); + }); + + test("quiet hours: a window that wraps past midnight, one that doesn't, and the zone it is on", () => { + const at = (h: string, z = "UTC") => avail.inQuietWindow(quiet(), z, new Date(`2026-10-20T${h}:00Z`)); + assert.deepEqual([at("23:00"), at("03:00"), at("07:00"), at("12:00"), at("21:59")], [true, true, false, false, false]); + assert.equal(avail.inQuietWindow({ enabled: false, start: "22:00", end: "07:00" }, "UTC", new Date("2026-10-20T23:00:00Z")), false); + assert.equal(avail.inQuietWindow({ enabled: true, start: "08:00", end: "08:00" }, "UTC", NOW), false, "a window of no length is never on"); + assert.equal(avail.inQuietWindow({ enabled: true, start: "09:00", end: "17:00" }, "UTC", NOW), true, "an ordinary same-day window"); + assert.equal(at("21:30", "Europe/Stockholm"), true, "21:30 UTC is 23:30 there (summer time)"); + assert.equal(at("04:30", "Europe/Stockholm"), true, "04:30 UTC is 06:30 there: the window ends at 07:00"); + assert.equal(at("05:30", "Europe/Stockholm"), false, "05:30 UTC is 07:30 there"); + assert.equal(at("21:30", "America/New_York"), false, "21:30 UTC is 17:30 in New York"); + }); + + test("away holds everything, or everything but what is critical; quiet hours the same; away is looked at first", () => { + const night = new Date("2026-10-20T23:30:00Z"); + const s = (a: ReturnType, q = quiet()) => ({ away: a, quietHours: q, timezone: "UTC" }); + const t = night.getTime(); + assert.equal(avail.holdFor(s(away(null, t + HOUR)), false, night), "away"); + assert.equal(avail.holdFor(s(away(null, t + HOUR, true)), true, night), "quiet", "critical gets past away, and meets the quiet hours that are also on"); + assert.equal(avail.holdFor(s(away(null, t + HOUR, true), quiet(true)), true, night), null, "…unless they let it through too"); + assert.equal(avail.holdFor(s(away(null, t + HOUR, false), quiet(true)), true, night), "away", "away that lets nothing through holds a critical one"); + assert.equal(avail.holdFor(s(away(null, null)), false, night), "quiet"); + assert.equal(avail.holdFor(s(away(null, null), quiet(true)), true, night), null); + assert.equal(avail.holdFor(s(away(null, null)), true, night), "quiet", "critical is held by quiet hours unless they say otherwise"); + assert.equal(avail.holdFor(s(away(t + HOUR, t + 2 * HOUR), { ...quiet(), enabled: false }), false, night), null, "an away stretch that has not begun holds nothing"); + }); + + test("a time typed for the notification time zone is that zone's clock; an ISO moment is itself", () => { + assert.equal(momentOf("2026-10-25T18:00", "UTC")?.toISOString(), "2026-10-25T18:00:00.000Z"); + assert.equal(momentOf("2026-10-25T18:00", "Europe/Stockholm")?.toISOString(), "2026-10-25T17:00:00.000Z", "the clocks went back that morning: UTC+1"); + assert.equal(momentOf("2026-10-20T18:00", "Europe/Stockholm")?.toISOString(), "2026-10-20T16:00:00.000Z", "UTC+2 before"); + assert.equal(momentOf("2026-10-25T18:00:00.000Z", "Europe/Stockholm")?.toISOString(), "2026-10-25T18:00:00.000Z"); + assert.equal(momentOf("tomorrow", "UTC"), null); + assert.equal(momentOf("2026-10-25 18:00", "UTC"), null); + }); +}); + +describe("held, let through, and sent when it ends", () => { + let hook: Server; + let app: Server; + let base = ""; + let who = "admin"; + const messages: string[] = []; + const titles = () => messages.map((m) => /^\*\*(.*?)\*\*/.exec(m)?.[1] ?? m); + + before(async () => { + await db.insert(users).values([ + { oidcSub: "admin", name: "Ada", role: "admin" }, + { oidcSub: "viewer", name: "Vic", role: "viewer" }, + ]); + hook = createHttpServer((req, res) => { + const chunks: Buffer[] = []; + req.on("data", (c) => chunks.push(c)); + req.on("end", () => { + messages.push(String(JSON.parse(Buffer.concat(chunks).toString()).content)); + res.end("{}"); + }); + }); + await new Promise((r) => hook.listen(0, "127.0.0.1", r)); + await updateSettings({ webhook: { enabled: true, url: `http://127.0.0.1:${(hook.address() as AddressInfo).port}/` } }); + const a = express(); + a.use(express.json()); + a.use((req, _res, next) => { + (req as unknown as { session: unknown }).session = { user: { sub: who } }; + next(); + }); + a.use("/api/away", awayRouter); + app = await new Promise((resolve) => { + const s = a.listen(0, "127.0.0.1", () => resolve(s)); + }); + base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/away`; + }); + after(() => { + app.close(); + hook.close(); + try { + rmSync(dir, { recursive: true, force: true }); + } catch { + // Windows keeps the database file locked until the process exits. + } + }); + + const send = (method: string, body?: unknown) => fetch(base, { method, headers: { "content-type": "application/json", connection: "close" }, body: body === undefined ? undefined : JSON.stringify(body) }); + const tomorrow = () => iso(Date.now() + 24 * HOUR); + + test("away: a warning is held, a critical alert gets through, and coming back sends what was held as one digest", async () => { + who = "admin"; + const res = await send("PUT", { until: tomorrow(), criticalThrough: true, note: "Holiday" }); + assert.equal(res.status, 200); + assert.equal(((await res.json()) as any).away.state, "active"); + messages.length = 0; + await notify("Disk warning", "nas: / is 91% full", { category: "disk", severity: "warning" }); + await notify("Disk critical", "nas: / is 99% full", { category: "disk", severity: "critical" }); + assert.deepEqual(titles(), ["Disk critical"], "only the critical one went out"); + assert.equal((await listQueuedNotifications()).length, 1); + const v = (await (await send("GET")).json()) as any; + assert.deepEqual([v.away.state, v.away.note, v.held], ["active", "Holiday", 1]); + + messages.length = 0; + const back = await send("DELETE"); + assert.equal(back.status, 200); + assert.equal(((await back.json()) as any).sent, 1); + assert.deepEqual(titles(), ["Homelab Manager — Notifications from while you were away"]); + assert.match(messages[0], /1 notification was held while you were away:[\s\S]*nas: \/ is 91% full/); + assert.equal((await listQueuedNotifications()).length, 0); + assert.deepEqual((await getSettings()).away.until, null); + assert.equal((await send("DELETE")).status, 404, "nobody is away now"); + const audited = await db.select().from(auditLog).where(eq(auditLog.category, "away")); + assert.deepEqual(audited.map((a) => a.action), ["start", "end"]); + }); + + test("away that lets nothing through holds even a critical alert, and a health alert follows the same rule", async () => { + await send("PUT", { until: tomorrow(), criticalThrough: false }); + messages.length = 0; + await notify("Disk critical", "nas: / is 99% full", { category: "disk", severity: "critical" }); + await notifyHealthIssues([{ key: "offline:server:9", message: "pve hasn't reported for 2 h", severity: "critical" }]); + assert.deepEqual(messages, []); + assert.equal((await listQueuedNotifications()).length, 2); + await send("DELETE"); + assert.equal(messages.length, 1); + assert.match(messages[0], /2 notifications were held while you were away/); + }); + + test("an escalation step that says to send even in quiet hours is sent while away too", async () => { + await send("PUT", { until: tomorrow(), criticalThrough: false }); + messages.length = 0; + await notifyAudience("Still not acknowledged", "pve is still down", { channels: null, pushIds: null }, { quietHours: false }); + assert.deepEqual(titles(), ["Still not acknowledged"]); + await send("DELETE"); + await clearQueuedNotifications(); + }); + + test("an away stretch planned for later holds nothing until it begins", async () => { + const res = await send("PUT", { from: iso(Date.now() + 6 * HOUR), until: iso(Date.now() + 30 * HOUR) }); + assert.equal(((await res.json()) as any).away.state, "planned"); + messages.length = 0; + await notify("Disk warning", "nas: / is 91% full", { category: "disk", severity: "warning" }); + assert.equal(messages.length, 1, "sent as ever"); + assert.equal((await send("DELETE")).status, 200, "a planned one can be cancelled"); + assert.equal(messages.length, 1, "and nothing was waiting to be sent"); + }); + + test("when its time comes it ends by itself and sends the digest", async () => { + await updateSettings({ away: { from: null, until: iso(Date.now() + 5 * 60_000), criticalThrough: true, note: "" } }); + messages.length = 0; + await notify("Disk warning", "nas: / is 91% full", { category: "disk", severity: "warning" }); + assert.equal(messages.length, 0, "held"); + assert.equal(await endAwayIfOver(), false, "not yet"); + assert.equal(await endAwayIfOver(new Date(Date.now() + 10 * 60_000)), true, "ten minutes on, it is over"); + assert.deepEqual(titles(), ["Homelab Manager — Notifications from while you were away"]); + assert.equal((await getSettings()).away.until, null); + const last = (await db.select().from(auditLog).where(eq(auditLog.category, "away"))).at(-1)!; + assert.deepEqual([last.action, JSON.parse(last.detail!).automatic, last.actorLabel], ["end", true, "system"]); + }); + + test("what is held for one reason is not let out while the other still holds it", async () => { + // quiet hours around now, and away on top of them + const h = new Date().getUTCHours(); + const pad = (n: number) => `${String(n % 24).padStart(2, "0")}:00`; + await updateSettings({ quietHours: { enabled: true, start: pad(h + 23), end: pad(h + 1), criticalThrough: false }, notifications: { timezone: "UTC" } as never }); + await send("PUT", { until: tomorrow(), criticalThrough: true }); + messages.length = 0; + await notify("Disk warning", "nas: / is 91% full", { category: "disk", severity: "warning" }); + assert.equal(await flushQuietHoursQueue(), 0, "quiet hours ending in the middle of a holiday release nothing"); + assert.equal(await flushQuietHoursQueue({ reason: "away" }), 0, "and coming back during quiet hours releases nothing yet"); + await send("DELETE"); + assert.equal(messages.length, 0, "still quiet"); + assert.equal((await listQueuedNotifications()).length, 1); + assert.equal(await flushQuietHoursQueue({ force: true }), 1, "by hand it goes"); + assert.match(messages[0], /held during quiet hours/); + }); + + test("quiet hours can let critical alerts through, and say so", async () => { + const h = new Date().getUTCHours(); + const pad = (n: number) => `${String(n % 24).padStart(2, "0")}:00`; + await updateSettings({ quietHours: { enabled: true, start: pad(h + 23), end: pad(h + 1), criticalThrough: true } }); + messages.length = 0; + await notify("Disk warning", "held", { category: "disk", severity: "warning" }); + await notify("Disk critical", "sent", { category: "disk", severity: "critical" }); + assert.deepEqual(titles(), ["Disk critical"]); + await clearQueuedNotifications(); + await updateSettings({ quietHours: { enabled: false, start: "22:00", end: "07:00", criticalThrough: false } }); + }); + + test("anyone signed in can see whether somebody is away; only an administrator sets, plans and ends it, with a reason when it is wrong", async () => { + who = "viewer"; + assert.equal((await send("GET")).status, 200); + assert.equal((await send("PUT", { until: tomorrow() })).status, 403); + assert.equal((await send("DELETE")).status, 403); + who = "admin"; + const bad = async (body: unknown, error: string) => { + const r = await send("PUT", body); + assert.deepEqual([r.status, ((await r.json()) as any).error], [400, error], JSON.stringify(body)); + }; + await bad({ until: iso(Date.now() - HOUR) }, "in_the_past"); + await bad({ until: iso(Date.now() + 200 * 24 * HOUR) }, "too_long"); + await bad({ until: "next week" }, "invalid_until"); + await bad({ from: "soon", until: tomorrow() }, "invalid_from"); + await bad({ from: iso(Date.now() + 48 * HOUR), until: tomorrow() }, "bad_range"); + await bad({}, "invalid_body"); + assert.equal((await send("PUT", { until: "2999-01-01T00:00" })).status, 400, "a thousand years is too long"); + }); +}); diff --git a/web/src/api/client.ts b/web/src/api/client.ts index 78d7a95..e75be59 100644 --- a/web/src/api/client.ts +++ b/web/src/api/client.ts @@ -556,6 +556,15 @@ export interface QuietHoursSettings { enabled: boolean; start: string; end: string; + /** A critical alert is sent at once even inside the window. */ + criticalThrough: boolean; +} + +/** Whether somebody is away (notifications held until they are back), and how many are being held. */ +export interface AwayView { + away: { from: string | null; until: string | null; criticalThrough: boolean; note: string; state: "none" | "planned" | "active" }; + held: number; + timezone: string; } /** The weekly digest: one message a week through the notification channels. */ @@ -2557,6 +2566,11 @@ export const api = { create: (label: string) => request<{ token: MetricsToken; secret: string }>("/api/metrics-tokens", { method: "POST", body: JSON.stringify({ label }) }), remove: (id: number) => request(`/api/metrics-tokens/${id}`, { method: "DELETE" }), }, + away: { + get: () => request("/api/away"), + start: (data: { until: string; from?: string | null; criticalThrough: boolean; note?: string }) => request("/api/away", { method: "PUT", body: JSON.stringify(data) }), + end: () => request("/api/away", { method: "DELETE" }), + }, serviceLevels: { list: () => request<{ levels: ServiceLevel[]; subjects: Record }>("/api/service-levels"), create: (data: ServiceLevelInput) => request<{ id: number }>("/api/service-levels", { method: "POST", body: JSON.stringify(data) }), diff --git a/web/src/components/RoutingEditor.tsx b/web/src/components/RoutingEditor.tsx index f1620ef..7694f1a 100644 --- a/web/src/components/RoutingEditor.tsx +++ b/web/src/components/RoutingEditor.tsx @@ -232,7 +232,7 @@ export default function RoutingEditor({
diff --git a/web/src/layout/AppShell.tsx b/web/src/layout/AppShell.tsx index b19710f..3800bc2 100644 --- a/web/src/layout/AppShell.tsx +++ b/web/src/layout/AppShell.tsx @@ -1,7 +1,8 @@ import { useEffect, useRef, useState, type ReactNode } from "react"; import { Link, NavLink, useLocation } from "react-router-dom"; -import { IconKey, IconMenu2, IconSun, IconMoon, IconShieldLock, IconTool, IconChevronUp, IconLogout, IconDeviceDesktop, IconChevronsLeft, IconChevronsRight } from "@tabler/icons-react"; -import { api, type CurrentUser, type MaintenanceWindow } from "../api/client"; +import { IconPlaneDeparture, IconKey, IconMenu2, IconSun, IconMoon, IconShieldLock, IconTool, IconChevronUp, IconLogout, IconDeviceDesktop, IconChevronsLeft, IconChevronsRight } from "@tabler/icons-react"; +import { api, type AwayView, type CurrentUser, type MaintenanceWindow } from "../api/client"; +import { formatDateTime } from "../utils/date"; import { isCurrent, isGroup, visibleNav, type NavGroup } from "./nav"; import SidebarNav, { type NavBadge } from "./SidebarNav"; import { initFavorites } from "../utils/favorites"; @@ -79,6 +80,7 @@ export default function AppShell({ user, children }: { user: CurrentUser; childr return () => window.removeEventListener("toggle-sidebar", toggle); }, []); const [maintenance, setMaintenance] = useState([]); + const [away, setAway] = useState(null); const environment = useEnvironment(); useStackedTables(); useShortcuts(user); @@ -128,6 +130,26 @@ export default function AppShell({ user, children }: { user: CurrentUser; childr }; }, []); + // Everyone sees when notifications are being held because somebody is away, for the same reason. + useEffect(() => { + let cancelled = false; + const load = () => + api.away + .get() + .then((res) => { + if (!cancelled) setAway(res); + }) + .catch(() => {}); + load(); + const poll = setInterval(load, 60_000); + window.addEventListener("away-changed", load); + return () => { + cancelled = true; + clearInterval(poll); + window.removeEventListener("away-changed", load); + }; + }, []); + const nav = visibleNav(user.role); const { pathname } = useLocation(); @@ -358,6 +380,17 @@ export default function AppShell({ user, children }: { user: CurrentUser; childr
+ {away && away.away.state !== "none" && away.away.until && ( +
+ +
+ {away.away.state === "planned" ? `Away from ${formatDateTime(new Date(away.away.from!))} until ${formatDateTime(new Date(away.away.until))}` : `Away until ${formatDateTime(new Date(away.away.until))}`} + {away.away.note ? ` — ${away.away.note}` : ""}.{" "} + {away.away.state === "active" ? `Notifications are held${away.away.criticalThrough ? " (critical alerts still come through)" : ""}${away.held > 0 ? ` — ${away.held} so far` : ""}. ` : ""} + {user.role === "admin" ? "Manage" : "Details"} +
+
+ )} {maintenance.length > 0 && (
diff --git a/web/src/pages/settings/AwayCard.tsx b/web/src/pages/settings/AwayCard.tsx new file mode 100644 index 0000000..8037c33 --- /dev/null +++ b/web/src/pages/settings/AwayCard.tsx @@ -0,0 +1,163 @@ +import { useEffect, useState } from "react"; +import { api, type AwayView } from "../../api/client"; +import TimeAgo from "../../components/TimeAgo"; +import { confirmDialog } from "../../utils/dialogs"; +import { formatDateTime } from "../../utils/date"; +import { readableError } from "../../utils/errors"; +import { toast } from "../../utils/toast"; + +/** "2026-10-25T18:00" for a datetime-local input, from a moment. */ +function wall(ms: number): string { + const d = new Date(ms); + const p = (n: number) => String(n).padStart(2, "0"); + return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}T${p(d.getHours())}:${p(d.getMinutes())}`; +} + +/** Tomorrow, next Sunday, in a week — at 18:00, which is about when most people are home again. */ +function presets(): { label: string; value: string }[] { + const at18 = (offsetDays: number) => { + const d = new Date(); + d.setDate(d.getDate() + offsetDays); + d.setHours(18, 0, 0, 0); + return wall(d.getTime()); + }; + const untilSunday = (7 - new Date().getDay()) % 7 || 7; + return [ + { label: "Until tomorrow evening", value: at18(1) }, + { label: "Until Sunday evening", value: at18(untilSunday) }, + { label: "A week", value: at18(7) }, + { label: "Two weeks", value: at18(14) }, + ]; +} + +/** + * "I'm away until Sunday." Notifications are held while it lasts and sent as one digest when it ends (at its time, or when you say you are back); critical alerts can still come + * through. Everyone sees that somebody is away; an administrator sets it. The times are the clock of the screen it is set on. + */ +export default function AwayCard({ canEdit }: { canEdit: boolean }) { + const [view, setView] = useState(null); + const [until, setUntil] = useState(""); + const [from, setFrom] = useState(""); + const [critical, setCritical] = useState(true); + const [note, setNote] = useState(""); + const [busy, setBusy] = useState(false); + const [error, setError] = useState(null); + + function load() { + api.away + .get() + .then((v) => { + setView(v); + setCritical(v.away.criticalThrough); + }) + .catch((err) => setError(readableError(err))); + } + useEffect(load, []); + + async function start(e: React.FormEvent) { + e.preventDefault(); + setBusy(true); + setError(null); + try { + // What is typed is the clock on this screen, so it is sent as the exact moment it means. + const v = await api.away.start({ until: new Date(until).toISOString(), from: from ? new Date(from).toISOString() : null, criticalThrough: critical, note }); + setView(v); + toast.success(v.away.state === "planned" ? "Away mode planned." : "Away mode is on — notifications are held."); + window.dispatchEvent(new Event("away-changed")); + setUntil(""); + setFrom(""); + setNote(""); + } catch (err) { + setError(readableError(err)); + } finally { + setBusy(false); + } + } + + async function end() { + const planned = view?.away.state === "planned"; + if (!planned && view && view.held > 0 && !(await confirmDialog({ title: "Back already?", message: `${view.held} notification${view.held === 1 ? " was" : "s were"} held. They are sent now as one digest.`, confirmLabel: "I'm back" }))) return; + setBusy(true); + try { + const v = await api.away.end(); + setView(v); + toast.success(planned ? "Cancelled." : v.sent ? `Welcome back — ${v.sent} held notification${v.sent === 1 ? "" : "s"} sent.` : "Welcome back."); + window.dispatchEvent(new Event("away-changed")); + } catch (err) { + setError(readableError(err)); + } finally { + setBusy(false); + } + } + + const a = view?.away; + const on = a && a.state !== "none"; + + return ( +
+
+

Away

+
+
+

+ Going away? Say until when. Notifications are held while you are gone and sent as one digest when it ends, so a week of warnings is one message to read rather than a buzzing phone. Critical alerts can still come + through. Quiet hours below are for every night; this is for a stretch. +

+ {error &&
{error}
} + {on && a ? ( +
+
{a.state === "planned" ? "Planned" : "Away"} until {formatDateTime(new Date(a.until!))}
+
+ {a.state === "planned" && a.from ? ( + <> + Starts {formatDateTime(new Date(a.from))} ().{" "} + + ) : null} + {a.criticalThrough ? "Critical alerts are still sent." : "Everything is held, critical alerts too."} + {a.note ? ` “${a.note}”` : ""} {a.state === "active" ? `${view!.held} held so far.` : ""} +
+ {canEdit && ( + + )} +
+ ) : null} + {canEdit && ( +
+
+ {presets().map((p) => ( + + ))} +
+
+
+ + setUntil(e.target.value)} /> +
+
+ + setFrom(e.target.value)} /> +
+
+ setNote(e.target.value)} /> + + +
+ )} + {!canEdit && !on &&
Nobody is away. An administrator can set it.
} +
+
+ ); +} diff --git a/web/src/pages/settings/NotificationSettings.tsx b/web/src/pages/settings/NotificationSettings.tsx index 9bb9cd4..88f9149 100644 --- a/web/src/pages/settings/NotificationSettings.tsx +++ b/web/src/pages/settings/NotificationSettings.tsx @@ -1,3 +1,4 @@ +import AwayCard from "./AwayCard"; import { useEffect, useRef, useState, type KeyboardEvent, type ReactNode } from "react"; import { useSearchParams } from "react-router-dom"; import AlertActionsCard from "./AlertActionsCard"; @@ -71,7 +72,7 @@ const DEFAULT_NOTIFICATIONS: NotificationEvents = { integrationFailureAlerts: true, integrationFailureThreshold: 3, }; -const DEFAULT_QUIET_HOURS: QuietHoursSettings = { enabled: false, start: "22:00", end: "07:00" }; +const DEFAULT_QUIET_HOURS: QuietHoursSettings = { enabled: false, start: "22:00", end: "07:00", criticalThrough: false }; const DEFAULT_DIGEST: DigestSettings = { enabled: false, day: 1, time: "08:00" }; // Monday first, as a week reads; the numbers are what the server keeps (0 = Sunday). const DIGEST_DAYS: { value: number; label: string }[] = [ @@ -280,7 +281,7 @@ export default function NotificationSettings() { setRouting(rt); setEscalation(es); setNotifications(s.notifications); - setQuietHours(s.quietHours); + setQuietHours({ ...DEFAULT_QUIET_HOURS, ...s.quietHours }); setHealthChecks(s.healthChecks); const d = s.digest ?? DEFAULT_DIGEST; setDigest(d); @@ -963,6 +964,13 @@ export default function NotificationSettings() {
A start time later than the end time (e.g. 22:00 → 07:00) is treated as spanning midnight.
+ {queuedCount !== null && queuedCount > 0 && (
@@ -978,6 +986,10 @@ export default function NotificationSettings() {
+
+ +
+
diff --git a/web/src/utils/settingsIndex.ts b/web/src/utils/settingsIndex.ts index 7d6605c..51dcd15 100644 --- a/web/src/utils/settingsIndex.ts +++ b/web/src/utils/settingsIndex.ts @@ -20,6 +20,8 @@ export const SETTINGS_INDEX: SettingsEntry[] = [ { title: "Server offline after (minutes)", where: "Notifications › What to send › Servers and disks", to: `${N}?tab=events`, words: "offline stopped reporting silent agent threshold limit minutes" }, { title: "Disk usage alert at (percent)", where: "Notifications › What to send › Servers and disks", to: `${N}?tab=events`, words: "disk full storage percent threshold space" }, { title: "Warn when a disk will fill within (days)", where: "Notifications › What to send › Servers and disks", to: `${N}?tab=events`, words: "disk forecast fill growth trend days" }, + { title: "Away mode: hold notifications while I'm away", where: "Notifications › When", to: `${N}?tab=when`, words: "away holiday vacation travel back hold digest pause mute do not disturb critical" }, + { title: "Let critical alerts through quiet hours", where: "Notifications › When", to: `${N}?tab=when`, words: "quiet hours critical night wake sleep through urgent" }, { title: "Quarterly and annual reports", where: "Notifications › When", to: `${N}?tab=when`, words: "report quarterly annual yearly quarter year send message monthly" }, { title: "Warn when CPU or memory is unusually high for the time", where: "Notifications › What to send › Servers and disks", to: `${N}?tab=events`, words: "baseline usual normal unusual unusually busy high cpu memory load weekday hour history anomaly" }, { title: "Warn when a server starts listening on a new port", where: "Notifications › What to send › Servers and disks", to: `${N}?tab=events`, words: "new port baseline listening tcp monitoring" },