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 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-22 19:14:29 +02:00
1 parent 3b31b16796
commit 16b24f5436
21 files changed
+737 -50

No files matched your search

+2
View File
@@ -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);
+2
View File
@@ -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));
+76
View File
@@ -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 });
}));
+2 -2
View File
@@ -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 });
}));
+61
View File
@@ -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<AwaySettings, "from" | "until">, 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<QuietHoursSettings, "enabled" | "start" | "end">, 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<HoldReason | null> {
const s = await getSettings();
return holdFor({ away: s.away, quietHours: s.quietHours, timezone: s.notifications.timezone }, critical, now);
}
+35
View File
@@ -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<typeof recordAudit>[0]["actor"] }): Promise<number> {
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<boolean> {
const { away } = await getSettings();
if (!away.until || awayState(away, now) !== "none") return false;
await endAway({ automatic: true });
return true;
}
let timer: ReturnType<typeof setInterval> | 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);
}
+5
View File
@@ -42,6 +42,7 @@ const KIND_OF_CATEGORY: Record<string, ChangeKind> = {
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":
+20 -37
View File
@@ -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<void> {
export async function notifyAudience(title: string, message: string, audience: Audience, options: { quietHours?: boolean; actions?: NotifyActions | null; critical?: boolean } = {}): Promise<void> {
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<T>(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<boolean> {
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<void> {
await sendToChannels(title, message);
@@ -259,11 +233,20 @@ export async function enabledChannelCount(): Promise<number> {
/** `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<void> {
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<number> {
/**
* 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<number> {
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<number> {
}
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,
);
}
+20 -1
View File
@@ -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 },
+254
View File
@@ -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<typeof away>, 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<void>((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<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/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");
});
});