Open an osTicket ticket for an alert that lasts

With Settings -> Alert tickets switched on (off by default), every 15 minutes the problems on the
Alerts page are looked at and one that is new and has lasted gets one ticket in osTicket, through
its API (POST api/tickets.json, key in X-API-Key). One problem opens one ticket however many checks
see it; the app remembers what it has seen in a new alert_tickets table (migration 0015).

- Which: critical and warning by default, every kind; severities and kinds are settings.
- A problem must be seen in 2 checks in a row first (1-4, a setting), so a blip that fixes itself,
  like one failed call to an integration, never opens a ticket.
- One ticket per occurrence; a problem that clears and returns within 60 minutes is the same one.
- More than 5 new problems in one check become a single summary ticket.
- Never for alerts under a maintenance window, nor about osTicket itself or its overdue tickets.
- Problems already there when it is switched on are left alone by default (the first check records
  them as a baseline); can be set to ticket them too.
- If osTicket can't be reached nothing is recorded, so the next check retries; if a source couldn't
  be read, a problem isn't treated as gone. Every ticket is audited.

The ticket API address, key (stored encrypted) and self-signed option are optional fields on the
osTicket integration, which otherwise still only reads the database. The settings page can send a
test ticket and run a check now; the Alerts page shows each alert's ticket number, linked to osTicket.

osTicket's API can't close or update a ticket, so a ticket opened here is the end of this app's part
in it. Tested against a stand-in osTicket, not a real one.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-07 23:41:44 +02:00
1 parent f71756b119
commit 467d1a1a06
14 files changed
+3455 -2

No files matched your search

@@ -0,0 +1,18 @@
CREATE TABLE `alert_tickets` (
`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
`alert_key` text NOT NULL,
`status` text NOT NULL,
`seen_count` integer DEFAULT 1 NOT NULL,
`integration_id` integer,
`ticket_number` text,
`grouped` integer DEFAULT false NOT NULL,
`severity` text NOT NULL,
`message` text NOT NULL,
`first_seen_at` text NOT NULL,
`last_seen_at` text NOT NULL,
`ticketed_at` text,
`cleared_at` text,
FOREIGN KEY (`integration_id`) REFERENCES `integrations`(`id`) ON UPDATE no action ON DELETE set null
);
--> statement-breakpoint
CREATE INDEX `alert_tickets_key_idx` ON `alert_tickets` (`alert_key`);
File diff suppressed because it is too large. Load diff
+7
View File
@@ -106,6 +106,13 @@
"when": 1790718056783, "when": 1790718056783,
"tag": "0014_empty_gabe_jones", "tag": "0014_empty_gabe_jones",
"breakpoints": true "breakpoints": true
},
{
"idx": 15,
"version": "6",
"when": 1791407868932,
"tag": "0015_yellow_scalphunter",
"breakpoints": true
} }
] ]
} }
+2
View File
@@ -29,6 +29,7 @@ import { tagsRouter } from "./routes/tags.js";
import { portsRouter } from "./routes/ports.js"; import { portsRouter } from "./routes/ports.js";
import { alertsRouter } from "./routes/alerts.js"; import { alertsRouter } from "./routes/alerts.js";
import { generatorRouter } from "./routes/generator.js"; import { generatorRouter } from "./routes/generator.js";
import { alertTicketsRouter } from "./routes/alertTickets.js";
import { apiErrorHandler } from "./utils/apiErrorHandler.js"; import { apiErrorHandler } from "./utils/apiErrorHandler.js";
import { securityHeaders } from "./utils/securityHeaders.js"; import { securityHeaders } from "./utils/securityHeaders.js";
import { sameOriginGuard } from "./utils/sameOriginGuard.js"; import { sameOriginGuard } from "./utils/sameOriginGuard.js";
@@ -101,6 +102,7 @@ export function createApp() {
app.use("/api/ports", portsRouter); app.use("/api/ports", portsRouter);
app.use("/api/alerts", alertsRouter); app.use("/api/alerts", alertsRouter);
app.use("/api/generator", generatorRouter); app.use("/api/generator", generatorRouter);
app.use("/api/alert-tickets", alertTicketsRouter);
if (existsSync(webDist)) { if (existsSync(webDist)) {
app.use(express.static(webDist)); app.use(express.static(webDist));
+32 -1
View File
@@ -1,5 +1,5 @@
import { sql } from "drizzle-orm"; import { sql } from "drizzle-orm";
import { sqliteTable, text, integer, real, uniqueIndex } from "drizzle-orm/sqlite-core"; import { sqliteTable, text, integer, real, uniqueIndex, index } from "drizzle-orm/sqlite-core";
// ─── Users & roles ────────────────────────────────────────────────────────── // ─── Users & roles ──────────────────────────────────────────────────────────
@@ -410,3 +410,34 @@ export const tagDefinitions = sqliteTable("tag_definitions", {
.notNull() .notNull()
.default(sql`(current_timestamp)`), .default(sql`(current_timestamp)`),
}); });
// ─── Tickets opened for alerts ──────────────────────────────────────────────
export const alertTicketStatuses = ["pending", "open", "baseline"] as const;
export type AlertTicketStatus = (typeof alertTicketStatuses)[number];
// What the ticket feature remembers about each problem it has seen, so one problem opens one ticket however many checks see it.
// A row is one *occurrence*: when the alert clears and later returns, that is a new row. Alert ids (e.g. "disk:server:3:/") are the
// stable keys the Alerts page already uses, so they aren't a foreign key to anything.
export const alertTickets = sqliteTable(
"alert_tickets",
{
id: integer("id").primaryKey({ autoIncrement: true }),
alertKey: text("alert_key").notNull(),
// pending = seen, but not yet in enough checks in a row to open a ticket (so a blip that fixes itself never does)
// open = a ticket was opened for it (ticket_number says which)
// baseline = it was already there when the feature was switched on and "existing problems" is set to be left alone
status: text("status").$type<AlertTicketStatus>().notNull(),
seenCount: integer("seen_count").notNull().default(1),
integrationId: integer("integration_id").references(() => integrations.id, { onDelete: "set null" }),
ticketNumber: text("ticket_number"), // osTicket's own ticket number; null unless status is "open"
grouped: integer("grouped", { mode: "boolean" }).notNull().default(false), // part of a summary ticket covering several alerts
severity: text("severity").notNull(),
message: text("message").notNull(), // what the alert said when it was first recorded
firstSeenAt: text("first_seen_at").notNull(), // ISO
lastSeenAt: text("last_seen_at").notNull(), // ISO
ticketedAt: text("ticketed_at"), // ISO; when the ticket was opened
clearedAt: text("cleared_at"), // ISO; null while the alert is still active
},
(t) => [index("alert_tickets_key_idx").on(t.alertKey)],
);
+2
View File
@@ -11,6 +11,7 @@ import { initProxmoxBackupScheduler } from "./services/proxmoxBackupScheduler.js
import { initPbsVerificationScheduler } from "./services/pbsVerificationScheduler.js"; import { initPbsVerificationScheduler } from "./services/pbsVerificationScheduler.js";
import { initQuietHoursScheduler } from "./services/quietHoursScheduler.js"; import { initQuietHoursScheduler } from "./services/quietHoursScheduler.js";
import { initHealthScheduler } from "./services/healthScheduler.js"; import { initHealthScheduler } from "./services/healthScheduler.js";
import { initAlertTicketScheduler } from "./services/alertTicketScheduler.js";
{ {
// Sessions are signed with this secret. Without one, the app would sign them with a value that's in the source code. // Sessions are signed with this secret. Without one, the app would sign them with a value that's in the source code.
@@ -36,6 +37,7 @@ await initProxmoxBackupScheduler();
await initPbsVerificationScheduler(); await initPbsVerificationScheduler();
await initQuietHoursScheduler(); await initQuietHoursScheduler();
await initHealthScheduler(); await initHealthScheduler();
await initAlertTicketScheduler();
createApp().listen(env.port, () => { createApp().listen(env.port, () => {
console.log(`homelab-manager listening on port ${env.port}`); console.log(`homelab-manager listening on port ${env.port}`);
+10
View File
@@ -75,6 +75,16 @@ export const INTEGRATION_FIELDS: Partial<Record<IntegrationType, IntegrationFiel
optional: true, optional: true,
placeholder: "ost_ (osTicket's default, unless changed at install)", placeholder: "ost_ (osTicket's default, unless changed at install)",
}, },
// Only for opening tickets from alerts (Settings → Alert tickets). The rest of this integration reads the database and never writes.
{
key: "apiUrl",
label: "Ticket API address (optional)",
secret: false,
optional: true,
placeholder: "https://osticket.example.lan/ (the folder that contains api/tickets.json)",
},
{ key: "apiKey", label: "Ticket API key (optional)", secret: true, optional: true, type: "password" },
{ key: "apiInsecure", label: "Allow self-signed certificate (ticket API)", secret: false, type: "checkbox" },
], ],
}; };
@@ -0,0 +1,142 @@
/**
* Opens tickets in osTicket through its HTTP API (POST api/tickets.json).
*
* This is separate from the rest of the osTicket integration, which reads the database directly and can't write: here the
* app is a client of osTicket's own API, authenticated with an API key made in osTicket (Admin Panel → Manage → API Keys). That
* key is tied to an IP address — osTicket refuses it from anywhere else — and needs "can create tickets". Both are the most
* common reason this fails, so the error for a refused key says so.
*
* What the API can't do is close, reopen or comment on a ticket, so a ticket opened here is the end of this app's part in it.
*/
import http from "node:http";
import https from "node:https";
import { withDiagLogging } from "../../services/diagLog.js";
export interface OsTicketApiConfig {
apiUrl?: string | boolean;
apiKey?: string | boolean;
apiInsecure?: string | boolean;
}
export interface NewTicket {
name: string;
email: string;
subject: string;
/** Plain text. */
message: string;
/** Let osTicket send its own new-ticket alert to staff. */
alertStaff: boolean;
topicId?: number | null;
priorityId?: number | null;
}
export interface CreatedTicket {
/** osTicket's own ticket number, as it shows it to people. Null if it answered "created" without saying. */
number: string | null;
}
const TIMEOUT_MS = 15_000;
const asString = (v: unknown) => (typeof v === "string" ? v.trim() : "");
/** Whether the integration has what opening tickets needs. */
export function hasTicketApi(config: OsTicketApiConfig): boolean {
return asString(config.apiUrl) !== "" && asString(config.apiKey) !== "";
}
/** The address of api/tickets.json under whatever the admin entered (which may or may not end in a slash, and may sit in a sub-folder). */
export function ticketEndpoint(apiUrl: string): URL {
const base = new URL(apiUrl.trim().endsWith("/") ? apiUrl.trim() : `${apiUrl.trim()}/`);
if (base.protocol !== "http:" && base.protocol !== "https:") throw new Error("The ticket API address must start with http:// or https://");
return new URL("api/tickets.json", base);
}
/** Where a ticket can be opened in osTicket's staff panel, for a link. Null if the address isn't usable. */
export function ticketUrl(apiUrl: string, number: string): string | null {
try {
const base = new URL(apiUrl.trim().endsWith("/") ? apiUrl.trim() : `${apiUrl.trim()}/`);
return new URL(`scp/tickets.php?number=${encodeURIComponent(number)}`, base).href;
} catch {
return null;
}
}
const clean = (text: string, max = 200) => text.replace(/[\u0000-\u001f\u007f]+/g, " ").trim().slice(0, max);
function post(url: URL, headers: Record<string, string>, body: string, insecure: boolean): Promise<{ status: number; location?: string; text: string }> {
return new Promise((resolve, reject) => {
const secure = url.protocol === "https:";
const req = (secure ? https : http).request(
{
hostname: url.hostname,
port: url.port || (secure ? 443 : 80),
path: url.pathname + url.search,
method: "POST",
headers: { ...headers, "Content-Length": String(Buffer.byteLength(body)) },
...(secure ? { rejectUnauthorized: !insecure } : {}),
timeout: TIMEOUT_MS,
},
(res) => {
let text = "";
res.setEncoding("utf8");
res.on("data", (chunk) => {
if (text.length < 5000) text += chunk;
});
res.on("end", () => resolve({ status: res.statusCode ?? 0, location: res.headers.location, text }));
},
);
req.on("timeout", () => req.destroy(new Error(`osTicket didn't answer within ${TIMEOUT_MS / 1000} seconds.`)));
req.on("error", reject);
req.end(body);
});
}
export function createOsTicketTicketApi(config: OsTicketApiConfig) {
async function createTicket(ticket: NewTicket): Promise<CreatedTicket> {
const apiUrl = asString(config.apiUrl);
const apiKey = asString(config.apiKey);
if (!apiUrl || !apiKey) throw new Error("The osTicket integration has no ticket API address and key set.");
const url = ticketEndpoint(apiUrl);
const body = JSON.stringify({
alert: ticket.alertStaff,
// The "user" is this app, not a person: osTicket mailing an acknowledgement to it would only bounce.
autorespond: false,
source: "API",
name: ticket.name,
email: ticket.email,
subject: ticket.subject,
// osTicket reads the type of the message from an RFC 2397 data URL.
message: `data:text/plain;charset=utf-8,${encodeURIComponent(ticket.message)}`,
...(ticket.topicId ? { topicId: ticket.topicId } : {}),
...(ticket.priorityId ? { priority: ticket.priorityId } : {}),
});
const res = await post(url, { "Content-Type": "application/json", Accept: "application/json", "X-API-Key": apiKey, "User-Agent": "homelab-manager" }, body, config.apiInsecure === true || asString(config.apiInsecure) === "true");
if (res.status === 201) {
const text = res.text.trim();
let number: string | null = text;
try {
const parsed = JSON.parse(text);
number = typeof parsed === "string" || typeof parsed === "number" ? String(parsed) : null;
} catch {
// plain text, which is what osTicket normally sends
}
number = number ? clean(number, 32) : null;
return { number: number || null };
}
if (res.status >= 300 && res.status < 400) {
throw new Error(`osTicket redirected to ${clean(res.location ?? "somewhere else", 120)}. Use the address it redirects to (often https instead of http) as the ticket API address.`);
}
if (res.status === 401 || res.status === 403) {
throw new Error("osTicket refused the API key. Check the key, that it is allowed to create tickets, and that this server's IP address is the one the key is tied to.");
}
if (res.status === 404) throw new Error(`There is no osTicket API at ${url.href}. Check the ticket API address.`);
if (res.status === 400) throw new Error(`osTicket rejected the ticket: ${clean(res.text) || "no reason given"}`);
throw new Error(`osTicket answered with an error (HTTP ${res.status})${clean(res.text) ? `: ${clean(res.text)}` : ""}.`);
}
// Through the diagnostic log like every other call out, so a refused key shows up there (and counts toward "integration failing").
return withDiagLogging("osticket", { createTicket });
}
+118
View File
@@ -0,0 +1,118 @@
import { Router } from "express";
import { eq } from "drizzle-orm";
import { z } from "zod";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { db } from "../db/client.js";
import { integrations } from "../db/schema.js";
import { recordAudit } from "../services/audit.js";
import { getAlertTicketStatus, resetBaseline, runAlertTicketCheck, sendTestTicket } from "../services/alertTickets.js";
import { getSettings, updateSettings } from "../services/settingsStore.js";
import { describeSettingsChanges } from "../services/settingsDiff.js";
import { loadIntegrationConfig } from "../integrations/loadIntegration.js";
import { hasTicketApi, type OsTicketApiConfig } from "../integrations/osticket/ticketApi.js";
import { asyncHandler } from "../utils/asyncHandler.js";
export const alertTicketsRouter = Router();
alertTicketsRouter.use(requireAuth, requireRole("admin"));
// What an alert can be about, as the Alerts page names it. "tickets" (osTicket's own overdue tickets) is never offered: a ticket
// about tickets helps nobody.
const CATEGORIES = [
{ value: "offline", label: "Server down" },
{ value: "disk", label: "Disk & storage" },
{ value: "backup", label: "Backups" },
{ value: "updates", label: "Updates" },
{ value: "expiry", label: "Expiry" },
{ value: "automation", label: "Automation" },
{ value: "integration", label: "Integration failing" },
{ value: "monitoring", label: "Monitoring" },
] as const;
async function overview() {
const rows = await db.select({ id: integrations.id, name: integrations.name, enabled: integrations.enabled }).from(integrations).where(eq(integrations.type, "osticket"));
const osticket = [];
for (const row of rows) {
let ready = false;
try {
const loaded = await loadIntegrationConfig(row.id);
ready = loaded ? hasTicketApi(loaded.config as OsTicketApiConfig) : false;
} catch {
ready = false;
}
osticket.push({ id: row.id, name: row.name, enabled: row.enabled, ticketApiReady: ready });
}
return { settings: (await getSettings()).alertTickets, integrations: osticket, categories: CATEGORIES, status: await getAlertTicketStatus() };
}
alertTicketsRouter.get("/", asyncHandler(async (_req, res) => {
res.json(await overview());
}));
const updateSchema = z
.object({
enabled: z.boolean(),
integrationId: z.number().int().positive().nullable(),
severities: z.array(z.enum(["critical", "warning", "info"])).max(3),
categories: z.array(z.enum(CATEGORIES.map((c) => c.value) as [string, ...string[]])).max(20),
requesterName: z.string().max(100),
requesterEmail: z.string().max(200).refine((v) => v === "" || /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v), "That isn't an email address."),
topicId: z.number().int().positive().nullable(),
priorityId: z.number().int().positive().nullable(),
notifyStaff: z.boolean(),
existingProblems: z.enum(["ignore", "ticket"]),
confirmChecks: z.number().int().min(1).max(10),
summaryAbove: z.number().int().min(1).max(50),
reopenAfterMinutes: z.number().int().min(0).max(1440),
})
.partial();
alertTicketsRouter.put("/", asyncHandler(async (req, res) => {
const parsed = updateSchema.safeParse(req.body);
if (!parsed.success) {
const message = parsed.error.issues[0]?.message ?? "Those settings aren't valid.";
return res.status(400).json({ error: "invalid_body", message, details: parsed.error.flatten() });
}
const before = (await getSettings()).alertTickets;
const after = { ...before, ...parsed.data };
// Switching it on needs everything it uses to be there, so it can't be left "on" and silently doing nothing.
if (after.enabled) {
if (!after.integrationId) return res.status(400).json({ error: "invalid_settings", message: "Choose which osTicket integration to open tickets in." });
const [row] = await db.select({ type: integrations.type }).from(integrations).where(eq(integrations.id, after.integrationId)).limit(1);
if (!row || row.type !== "osticket") return res.status(400).json({ error: "invalid_settings", message: "The chosen integration isn't an osTicket integration." });
const loaded = await loadIntegrationConfig(after.integrationId);
if (!loaded || !hasTicketApi(loaded.config as OsTicketApiConfig)) {
return res.status(400).json({ error: "invalid_settings", message: "That osTicket integration has no ticket API address and key yet. Add them under Integrations first." });
}
if (after.severities.length === 0) return res.status(400).json({ error: "invalid_settings", message: "Choose at least one severity." });
if (!after.requesterEmail.trim()) return res.status(400).json({ error: "invalid_settings", message: "Enter the email the tickets should come from — osTicket needs one for every ticket." });
}
await updateSettings({ alertTickets: parsed.data });
// Switched on (or off and on again): what is wrong at that moment is the starting point, not a pile of new tickets.
if (!before.enabled !== !after.enabled || parsed.data.existingProblems !== undefined) await resetBaseline();
await recordAudit({
actor: req.currentUser!,
category: "settings",
action: "update_alert_tickets",
targetType: "settings",
detail: { changes: describeSettingsChanges({ alertTickets: before }, { alertTickets: parsed.data }).alertTickets ?? {} },
});
res.json(await overview());
}));
alertTicketsRouter.post("/test", asyncHandler(async (req, res) => {
try {
const created = await sendTestTicket(req.currentUser!);
res.json({ ok: true, ticketNumber: created.number });
} catch (err) {
res.status(502).json({ error: "ticket_failed", message: err instanceof Error ? err.message : String(err) });
}
}));
alertTicketsRouter.post("/run", asyncHandler(async (req, res) => {
const summary = await runAlertTicketCheck({ actor: req.currentUser! });
res.json({ summary, status: await getAlertTicketStatus() });
}));
+10 -1
View File
@@ -1,6 +1,7 @@
import { Router } from "express"; import { Router } from "express";
import { requireAuth } from "../auth/middleware.js"; import { requireAuth } from "../auth/middleware.js";
import { getAlerts } from "../services/alerts.js"; import { getAlerts } from "../services/alerts.js";
import { ticketsForAlerts, type AlertTicketInfo } from "../services/alertTickets.js";
import { asyncHandler } from "../utils/asyncHandler.js"; import { asyncHandler } from "../utils/asyncHandler.js";
export const alertsRouter = Router(); export const alertsRouter = Router();
@@ -10,5 +11,13 @@ alertsRouter.use(requireAuth);
// Everyone signed in can see it — it's the same server, disk and backup status the other pages already show. // Everyone signed in can see it — it's the same server, disk and backup status the other pages already show.
// `?refresh=1` asks for a fresh check instead of a recent one. // `?refresh=1` asks for a fresh check instead of a recent one.
alertsRouter.get("/", asyncHandler(async (req, res) => { alertsRouter.get("/", asyncHandler(async (req, res) => {
res.json(await getAlerts(req.query.refresh === "1")); const report = await getAlerts(req.query.refresh === "1");
// The ticket opened for each alert, if there is one. Never allowed to stop the page from loading.
let tickets = new Map<string, AlertTicketInfo>();
try {
tickets = await ticketsForAlerts(report.alerts.map((a) => a.id));
} catch (err) {
console.error("[alerts] couldn't look up tickets:", err);
}
res.json({ ...report, alerts: report.alerts.map((a) => ({ ...a, ticket: tickets.get(a.id) ?? null })) });
})); }));
@@ -0,0 +1,33 @@
import { runAlertTicketCheck } from "./alertTickets.js";
// The same 15 minutes the health checks use, and for the same reason: agents report on that rhythm, so a check never judges a
// server on figures that are merely waiting for the next report. An alert must also last two checks before it opens a ticket.
const INTERVAL_MS = 15 * 60 * 1000;
// Not at once after a start: the health check makes its own first round of calls to every integration then, and the alerts check would
// repeat them. (Alerts about servers are also held back for a while after a restart, since agents haven't reported yet.)
const FIRST_CHECK_DELAY_MS = 90 * 1000;
let timer: ReturnType<typeof setInterval> | null = null;
async function pass(): Promise<void> {
try {
const result = await runAlertTicketCheck();
if (result.skipped) return;
if (result.ticketsOpened > 0 || result.failed > 0 || result.error) {
console.log(
`[alertTickets] opened ${result.ticketsOpened} ticket${result.ticketsOpened === 1 ? "" : "s"} for ${result.alertsCovered} alert${result.alertsCovered === 1 ? "" : "s"}` +
(result.failed > 0 ? `, ${result.failed} failed` : "") +
(result.error ? ` — ${result.error}` : ""),
);
}
} catch (err) {
console.error("[alertTickets] check failed:", err);
}
}
export async function initAlertTicketScheduler(): Promise<void> {
if (timer) return;
timer = setInterval(() => void pass(), INTERVAL_MS);
setTimeout(() => void pass(), FIRST_CHECK_DELAY_MS);
console.log(`[alertTickets] checking for alerts that need an osTicket ticket every ${INTERVAL_MS / 60000} minutes (does nothing until enabled in Settings)`);
}
+440
View File
@@ -0,0 +1,440 @@
/**
* Opening an osTicket ticket for an alert.
*
* The Alerts page already works out everything that is wrong right now. This looks at that list every 15 minutes and, for a
* problem that is new and has lasted, opens one ticket — then remembers it, so the same problem never opens a second one however
* many checks see it. What it deliberately does not do: close, reopen or comment on a ticket (osTicket's API can't), or open one
* for something under a maintenance window.
*
* planTicketRun() is the decision, a pure function of "the alerts now", "what was remembered" and the settings. Everything else
* here is the doing: reading and writing that memory and calling osTicket.
*/
import { and, desc, eq, inArray, isNull, lt, or, gte } from "drizzle-orm";
import { db } from "../db/client.js";
import { alertTickets, integrations, users } from "../db/schema.js";
import { env } from "../env.js";
import { getAlerts } from "./alerts.js";
import type { Alert, AlertCategory } from "./alertTypes.js";
import { recordAudit } from "./audit.js";
import { getInternalFlag, getSettings, setInternalFlag, type AlertTicketSettings } from "./settingsStore.js";
import { loadIntegrationConfig } from "../integrations/loadIntegration.js";
import { createOsTicketTicketApi, hasTicketApi, ticketUrl, type CreatedTicket, type NewTicket, type OsTicketApiConfig } from "../integrations/osticket/ticketApi.js";
type CurrentUser = typeof users.$inferSelect;
export type TicketRow = typeof alertTickets.$inferSelect;
type Report = Awaited<ReturnType<typeof getAlerts>>;
const BASELINE_FLAG = "alertTicketsBaselineDone";
const LAST_RUN_FLAG = "alertTicketsLastRun";
/** How long a cleared problem is remembered after it cleared. */
const KEEP_CLEARED_DAYS = 180;
// ─── Deciding ───────────────────────────────────────────────────────────────
/** What the ticket feature never opens a ticket about, whatever the settings: the ticketing system itself. */
function isAboutTicketing(alert: Alert): boolean {
// A ticket about osTicket being down, or about overdue tickets, can't help: it would go to the very thing that is down (or add to the pile).
return alert.category === "tickets" || alert.id === "integration:failing:osticket";
}
export function qualifies(alert: Alert, settings: AlertTicketSettings): boolean {
if (alert.silenced) return false; // under a maintenance window: expected, not a reason to wake anyone
if (isAboutTicketing(alert)) return false;
if (!settings.severities.includes(alert.severity)) return false;
return settings.categories.length === 0 || settings.categories.includes(alert.category);
}
export type Op =
| { kind: "insertPending"; alert: Alert }
| { kind: "insertBaseline"; alert: Alert }
| { kind: "bump"; row: TicketRow; alert: Alert } // another check in a row, not yet enough
| { kind: "touch"; row: TicketRow } // still there; nothing else to do
| { kind: "reactivate"; row: TicketRow } // cleared a moment ago and is back: the same problem
| { kind: "clear"; row: TicketRow } // gone
| { kind: "dropPending"; row: TicketRow }; // a blip that went away before it lasted
export interface Candidate {
alert: Alert;
/** The pending row to turn into a ticketed one, or null for a problem with no row yet (confirmChecks of 1). */
row: TicketRow | null;
}
export interface Plan {
ops: Op[];
/** Alerts that have now lasted long enough and should open a ticket. */
toTicket: Candidate[];
}
export function planTicketRun(input: {
alerts: Alert[];
/** The latest row for each alert id that has one. */
rows: TicketRow[];
settings: AlertTicketSettings;
now: Date;
/** The first check since this was switched on: record what is already wrong without opening anything for it. */
baseline: boolean;
/** Everything could be read. Only then does "not in the list" mean "gone" — otherwise it may just mean "couldn't look". */
complete: boolean;
}): Plan {
const { alerts, rows, settings, now, baseline, complete } = input;
const byKey = new Map(rows.map((r) => [r.alertKey, r]));
const present = new Set(alerts.map((a) => a.id));
const ops: Op[] = [];
const toTicket: Candidate[] = [];
for (const alert of alerts) {
const row = byKey.get(alert.id);
const wanted = qualifies(alert, settings);
if (row && !row.clearedAt) {
if (row.status !== "pending") {
ops.push({ kind: "touch", row });
} else if (!wanted) {
ops.push({ kind: "touch", row }); // there, but silenced or filtered out right now: wait, don't count it
} else if (row.seenCount + 1 >= settings.confirmChecks) {
toTicket.push({ alert, row });
} else {
ops.push({ kind: "bump", row, alert });
}
continue;
}
if (!wanted) continue;
if (row?.clearedAt && now.getTime() - Date.parse(row.clearedAt) < settings.reopenAfterMinutes * 60_000) {
ops.push({ kind: "reactivate", row }); // flapping: the same problem, not a new one
continue;
}
// A new occurrence.
if (baseline) ops.push({ kind: "insertBaseline", alert });
else if (settings.confirmChecks <= 1) toTicket.push({ alert, row: null });
else ops.push({ kind: "insertPending", alert });
}
if (complete) {
for (const row of rows) {
if (row.clearedAt || present.has(row.alertKey)) continue;
ops.push({ kind: row.status === "pending" ? "dropPending" : "clear", row });
}
}
return { ops, toTicket };
}
// ─── Writing the ticket ─────────────────────────────────────────────────────
const CATEGORY_LABELS: Record<AlertCategory, string> = {
offline: "Server down",
disk: "Disk & storage",
backup: "Backups",
updates: "Updates",
expiry: "Expiry",
automation: "Automation",
integration: "Integration failing",
monitoring: "Monitoring",
tickets: "Tickets",
};
const SEVERITY_LABELS = { critical: "Critical", warning: "Warning", info: "Info" } as const;
const stamp = (iso: string) => `${iso.slice(0, 16).replace("T", " ")} UTC`;
const absolute = (path: string) => `${env.appBaseUrl.replace(/\/+$/, "")}${path}`;
const oneLine = (text: string, max: number) => (text.replace(/\s+/g, " ").trim().length > max ? `${text.replace(/\s+/g, " ").trim().slice(0, max - 1)}…` : text.replace(/\s+/g, " ").trim());
export function buildTicket(alert: Alert, firstSeenAt: string): { subject: string; message: string } {
const lines = [
"Homelab Manager found a problem.",
"",
`Severity: ${SEVERITY_LABELS[alert.severity]}`,
`Kind: ${CATEGORY_LABELS[alert.category] ?? alert.category}`,
`Source: ${alert.source}`,
`Problem: ${alert.message}`,
`First seen: ${stamp(firstSeenAt)} (it checks every 15 minutes)`,
"",
...(alert.link ? [`Details: ${absolute(alert.link)}`] : []),
`Everything that is wrong right now: ${absolute("/alerts")}`,
"",
`Opened automatically by Homelab Manager (alert ${alert.id}). It is not updated or closed automatically — close it here when it is dealt with.`,
];
return { subject: oneLine(`[Homelab] ${SEVERITY_LABELS[alert.severity]}: ${alert.message}`, 200), message: lines.join("\n") };
}
export function buildSummaryTicket(alerts: { alert: Alert; firstSeenAt: string }[]): { subject: string; message: string } {
const lines = [
`Homelab Manager found ${alerts.length} problems at once. They are in one ticket so a single outage doesn't fill the queue with dozens.`,
"",
...alerts.map(({ alert }) => `- [${SEVERITY_LABELS[alert.severity]}] ${alert.source}: ${alert.message}`),
"",
`Everything that is wrong right now: ${absolute("/alerts")}`,
"",
"Opened automatically by Homelab Manager. It is not updated or closed automatically — close it here when it is dealt with.",
];
return { subject: `[Homelab] ${alerts.length} problems detected`, message: lines.join("\n") };
}
// ─── Doing ──────────────────────────────────────────────────────────────────
export interface RunSummary {
at: string;
skipped?: "disabled" | "busy";
/** Why nothing could be done (missing setup, osTicket refusing). */
error?: string;
/** Tickets opened in osTicket (a summary ticket counts as one). */
ticketsOpened: number;
/** Alerts those tickets cover. */
alertsCovered: number;
/** Problems recorded without a ticket because they were already there when this was switched on. */
baseline: number;
/** Problems seen but not yet in enough checks in a row. */
pending: number;
cleared: number;
/** Tickets that couldn't be opened this time; they are tried again at the next check. */
failed: number;
}
export interface RunDeps {
getReport(): Promise<Report>;
createTicket(ticket: NewTicket): Promise<CreatedTicket>;
now(): Date;
}
let running = false;
const empty = (now: Date): RunSummary => ({ at: now.toISOString(), ticketsOpened: 0, alertsCovered: 0, baseline: 0, pending: 0, cleared: 0, failed: 0 });
/** The osTicket integration to use, with what it needs to open tickets. Throws a sentence an admin can act on. */
async function ticketClient(settings: AlertTicketSettings) {
if (!settings.integrationId) throw new Error("No osTicket integration is chosen for tickets.");
const loaded = await loadIntegrationConfig(settings.integrationId);
if (!loaded || loaded.integration.type !== "osticket") throw new Error("The chosen osTicket integration no longer exists.");
if (!loaded.integration.enabled) throw new Error("The chosen osTicket integration is switched off.");
const config = loaded.config as OsTicketApiConfig;
if (!hasTicketApi(config)) throw new Error("The osTicket integration has no ticket API address and key. Edit it under Integrations and fill them in.");
if (!settings.requesterEmail.trim()) throw new Error("No requester email is set — osTicket needs one for every ticket.");
return createOsTicketTicketApi(config);
}
async function latestRows(now: Date, reopenAfterMinutes: number): Promise<TicketRow[]> {
const since = new Date(now.getTime() - Math.max(reopenAfterMinutes, 60) * 60_000).toISOString();
const rows = await db
.select()
.from(alertTickets)
.where(or(isNull(alertTickets.clearedAt), gte(alertTickets.clearedAt, since)))
.orderBy(desc(alertTickets.id));
const latest = new Map<string, TicketRow>();
for (const row of rows) if (!latest.has(row.alertKey)) latest.set(row.alertKey, row);
return [...latest.values()];
}
export async function runAlertTicketCheck(options: { actor?: CurrentUser; deps?: Partial<RunDeps> } = {}): Promise<RunSummary> {
const nowFn = options.deps?.now ?? (() => new Date());
const now = nowFn();
const summary = empty(now);
const { alertTickets: settings } = await getSettings();
if (!settings.enabled) {
// Switched off: the next time it's switched on counts as a fresh start, so what's wrong by then is the baseline.
await setInternalFlag(BASELINE_FLAG, "");
return { ...summary, skipped: "disabled" };
}
if (running) return { ...summary, skipped: "busy" };
running = true;
try {
let client: { createTicket(ticket: NewTicket): Promise<CreatedTicket> };
try {
client = options.deps?.createTicket ? { createTicket: options.deps.createTicket } : await ticketClient(settings);
} catch (err) {
summary.error = err instanceof Error ? err.message : String(err);
await setInternalFlag(LAST_RUN_FLAG, JSON.stringify(summary));
return summary;
}
const report = await (options.deps?.getReport ?? (() => getAlerts(true)))();
const complete = report.couldntCheck.length === 0;
const baseline = settings.existingProblems === "ignore" && (await getInternalFlag(BASELINE_FLAG)) !== "1";
const rows = await latestRows(now, settings.reopenAfterMinutes);
const plan = planTicketRun({ alerts: report.alerts, rows, settings, now, baseline, complete });
const iso = now.toISOString();
for (const op of plan.ops) {
switch (op.kind) {
case "insertPending":
case "insertBaseline":
await db.insert(alertTickets).values({
alertKey: op.alert.id,
status: op.kind === "insertPending" ? "pending" : "baseline",
seenCount: 1,
integrationId: settings.integrationId,
severity: op.alert.severity,
message: op.alert.message,
firstSeenAt: iso,
lastSeenAt: iso,
});
if (op.kind === "insertPending") summary.pending++;
else summary.baseline++;
break;
case "bump":
await db.update(alertTickets).set({ seenCount: op.row.seenCount + 1, lastSeenAt: iso, severity: op.alert.severity, message: op.alert.message }).where(eq(alertTickets.id, op.row.id));
summary.pending++;
break;
case "touch":
await db.update(alertTickets).set({ lastSeenAt: iso }).where(eq(alertTickets.id, op.row.id));
if (op.row.status === "pending") summary.pending++;
break;
case "reactivate":
await db.update(alertTickets).set({ clearedAt: null, lastSeenAt: iso }).where(eq(alertTickets.id, op.row.id));
break;
case "clear":
await db.update(alertTickets).set({ clearedAt: iso }).where(eq(alertTickets.id, op.row.id));
summary.cleared++;
break;
case "dropPending":
await db.delete(alertTickets).where(eq(alertTickets.id, op.row.id));
break;
}
}
// Open the tickets: one each, or — when a lot appear at once — one for all of them.
const requester = { name: settings.requesterName.trim() || "Homelab Manager", email: settings.requesterEmail.trim() };
const common = { ...requester, alertStaff: settings.notifyStaff, topicId: settings.topicId, priorityId: settings.priorityId };
const firstSeen = (c: Candidate) => c.row?.firstSeenAt ?? iso;
const groups: Candidate[][] = plan.toTicket.length > settings.summaryAbove ? [plan.toTicket] : plan.toTicket.map((c) => [c]);
for (const group of groups) {
const content =
group.length === 1 ? buildTicket(group[0].alert, firstSeen(group[0])) : buildSummaryTicket(group.map((c) => ({ alert: c.alert, firstSeenAt: firstSeen(c) })));
let created: CreatedTicket;
try {
created = await client.createTicket({ ...common, ...content });
} catch (err) {
summary.failed += group.length;
summary.error ??= err instanceof Error ? err.message : String(err);
console.error("[alertTickets] couldn't open a ticket:", err instanceof Error ? err.message : err);
continue; // nothing was recorded, so the next check tries again
}
const grouped = group.length > 1;
for (const c of group) {
const values = { status: "open" as const, ticketNumber: created.number, grouped, ticketedAt: iso, lastSeenAt: iso, severity: c.alert.severity, message: c.alert.message, integrationId: settings.integrationId };
if (c.row) await db.update(alertTickets).set(values).where(eq(alertTickets.id, c.row.id));
else await db.insert(alertTickets).values({ alertKey: c.alert.id, seenCount: 1, firstSeenAt: iso, ...values });
await recordAudit({
actor: options.actor,
category: "alert_ticket",
action: "create",
targetType: "alert",
targetId: c.alert.id,
detail: { ticket: created.number, severity: c.alert.severity, ...(grouped ? { summaryOf: group.length } : {}), integrationId: settings.integrationId },
});
}
summary.ticketsOpened++;
summary.alertsCovered += group.length;
}
// The baseline is only complete if everything could be read: a source that was down would otherwise hide problems that then
// look "new" — and get tickets — once it comes back.
if (baseline && complete) await setInternalFlag(BASELINE_FLAG, "1");
await db.delete(alertTickets).where(and(lt(alertTickets.clearedAt, new Date(now.getTime() - KEEP_CLEARED_DAYS * 86_400_000).toISOString())));
await setInternalFlag(LAST_RUN_FLAG, JSON.stringify(summary));
return summary;
} finally {
running = false;
}
}
/** The next check starts afresh: it records what is wrong at that moment as the baseline instead of opening tickets for it. */
export async function resetBaseline(): Promise<void> {
await setInternalFlag(BASELINE_FLAG, "");
}
/** A ticket that says it is a test, to check the address, the key and where tickets land — without waiting for a real problem. */
export async function sendTestTicket(actor: CurrentUser): Promise<CreatedTicket> {
const { alertTickets: settings } = await getSettings();
const client = await ticketClient(settings);
const created = await client.createTicket({
name: settings.requesterName.trim() || "Homelab Manager",
email: settings.requesterEmail.trim(),
alertStaff: settings.notifyStaff,
topicId: settings.topicId,
priorityId: settings.priorityId,
subject: "[Homelab] Test ticket from Homelab Manager",
message: `This is a test. ${actor.name ?? actor.email ?? "An administrator"} asked Homelab Manager to open it from Settings → Alert tickets, to check that tickets can be created here.\n\nNothing is wrong. You can close this ticket.\n\n${absolute("/settings/alert-tickets")}`,
});
await recordAudit({ actor, category: "alert_ticket", action: "test", targetType: "integration", targetId: settings.integrationId ?? undefined, detail: { ticket: created.number } });
return created;
}
// ─── What the pages show ────────────────────────────────────────────────────
export interface AlertTicketInfo {
number: string | null;
/** The ticket in osTicket's staff panel, when the address is known. */
url: string | null;
/** Part of a summary ticket that covers several alerts. */
grouped: boolean;
openedAt: string | null;
}
/** The ticket opened for each of these alerts that has one and is still active, by alert id. */
export async function ticketsForAlerts(alertIds: string[]): Promise<Map<string, AlertTicketInfo>> {
const result = new Map<string, AlertTicketInfo>();
if (alertIds.length === 0) return result;
const rows = await db
.select()
.from(alertTickets)
.where(and(inArray(alertTickets.alertKey, alertIds), eq(alertTickets.status, "open"), isNull(alertTickets.clearedAt)))
.orderBy(desc(alertTickets.id));
const apiUrls = new Map<number, string | null>();
async function apiUrlOf(integrationId: number | null): Promise<string | null> {
if (integrationId === null) return null;
if (!apiUrls.has(integrationId)) {
const [row] = await db.select({ config: integrations.config }).from(integrations).where(eq(integrations.id, integrationId)).limit(1);
let url: string | null = null;
try {
const parsed = row?.config ? (JSON.parse(row.config) as { apiUrl?: unknown }) : {};
url = typeof parsed.apiUrl === "string" && parsed.apiUrl.trim() ? parsed.apiUrl : null;
} catch {
url = null;
}
apiUrls.set(integrationId, url);
}
return apiUrls.get(integrationId) ?? null;
}
for (const row of rows) {
if (result.has(row.alertKey)) continue;
const base = await apiUrlOf(row.integrationId);
result.set(row.alertKey, { number: row.ticketNumber, url: base && row.ticketNumber ? ticketUrl(base, row.ticketNumber) : null, grouped: row.grouped, openedAt: row.ticketedAt });
}
return result;
}
export interface AlertTicketStatus {
lastRun: RunSummary | null;
/** Active problems with a ticket / waiting to last long enough / already there when this was switched on. */
open: number;
pending: number;
baseline: number;
/** The next check will record what's wrong as the baseline instead of opening tickets for it. */
baselinePending: boolean;
}
export async function getAlertTicketStatus(): Promise<AlertTicketStatus> {
const active = await db.select({ status: alertTickets.status }).from(alertTickets).where(isNull(alertTickets.clearedAt));
let lastRun: RunSummary | null = null;
try {
const raw = await getInternalFlag(LAST_RUN_FLAG);
lastRun = raw ? (JSON.parse(raw) as RunSummary) : null;
} catch {
lastRun = null;
}
const { alertTickets: settings } = await getSettings();
return {
lastRun,
open: active.filter((r) => r.status === "open").length,
pending: active.filter((r) => r.status === "pending").length,
baseline: active.filter((r) => r.status === "baseline").length,
baselinePending: settings.enabled && settings.existingProblems === "ignore" && (await getInternalFlag(BASELINE_FLAG)) !== "1",
};
}
+45
View File
@@ -107,6 +107,35 @@ export interface NameGeneratorSettings {
themes: NameTheme[]; themes: NameTheme[];
} }
export type AlertTicketSeverity = "critical" | "warning" | "info";
/** Opening an osTicket ticket for an alert. Off until an admin sets it up under Settings → Alert tickets. */
export interface AlertTicketSettings {
enabled: boolean;
/** The osTicket integration whose API (address and key) is used. */
integrationId: number | null;
/** Which severities open a ticket. */
severities: AlertTicketSeverity[];
/** Which kinds of alert (the categories on the Alerts page). Empty means every kind. */
categories: string[];
/** Who the tickets appear to be from. osTicket needs both; the email is where staff replies would go. */
requesterName: string;
requesterEmail: string;
/** osTicket help topic and priority ids, if tickets should land somewhere other than its defaults. */
topicId: number | null;
priorityId: number | null;
/** Let osTicket send its own "new ticket" alert to staff, per its own settings. */
notifyStaff: boolean;
/** Problems already present when this is switched on: left alone ("ignore") or given tickets too ("ticket"). */
existingProblems: "ignore" | "ticket";
/** An alert must be there in this many checks in a row (15 minutes apart) before it opens a ticket, so a blip that fixes itself never does. */
confirmChecks: number;
/** More new alerts than this in one check become a single summary ticket instead of one each. */
summaryAbove: number;
/** An alert that clears and comes back within this many minutes is still the same problem, not a new ticket. */
reopenAfterMinutes: number;
}
export interface AppSettings { export interface AppSettings {
gotify: GotifySettings; gotify: GotifySettings;
ntfy: NtfySettings; ntfy: NtfySettings;
@@ -121,6 +150,7 @@ export interface AppSettings {
healthChecks: HealthCheckSettings; healthChecks: HealthCheckSettings;
consistency: ConsistencySettings; consistency: ConsistencySettings;
nameGenerator: NameGeneratorSettings; nameGenerator: NameGeneratorSettings;
alertTickets: AlertTicketSettings;
} }
const DEFAULTS: AppSettings = { const DEFAULTS: AppSettings = {
@@ -155,6 +185,21 @@ const DEFAULTS: AppSettings = {
// Docker host repeats them. Shown on the Consistency page, where it can be removed if 172.16/12 is used as a real LAN. // Docker host repeats them. Shown on the Consistency page, where it can be removed if 172.16/12 is used as a real LAN.
consistency: { excludedRanges: ["172.16.0.0/12"] }, consistency: { excludedRanges: ["172.16.0.0/12"] },
nameGenerator: { themes: defaultThemes() }, nameGenerator: { themes: defaultThemes() },
alertTickets: {
enabled: false,
integrationId: null,
severities: ["critical", "warning"],
categories: [],
requesterName: "Homelab Manager",
requesterEmail: "",
topicId: null,
priorityId: null,
notifyStaff: true,
existingProblems: "ignore",
confirmChecks: 2,
summaryAbove: 5,
reopenAfterMinutes: 60,
},
}; };
const KEYS = Object.keys(DEFAULTS) as (keyof AppSettings)[]; const KEYS = Object.keys(DEFAULTS) as (keyof AppSettings)[];
+776
View File
@@ -0,0 +1,776 @@
/**
* Opening osTicket tickets for alerts: the decision (planTicketRun), the osTicket API client (against a fake osTicket), the runner
* over several simulated checks, and the admin routes.
*
* Run with: npm test --workspace server
*/
import { test, describe, before, after, beforeEach } from "node:test";
import assert from "node:assert/strict";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import http from "node:http";
const dir = mkdtempSync(join(tmpdir(), "hm-alert-tickets-"));
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.APP_BASE_URL = "https://hm.example.lan";
const svc = await import("../src/services/alertTickets.js");
const { qualifies, planTicketRun, buildTicket, buildSummaryTicket, runAlertTicketCheck, ticketsForAlerts, getAlertTicketStatus } = svc;
const { createOsTicketTicketApi, hasTicketApi, ticketEndpoint, ticketUrl } = await import("../src/integrations/osticket/ticketApi.js");
const { getSettings, updateSettings, setInternalFlag } = await import("../src/services/settingsStore.js");
const { runMigrations } = await import("../src/db/migrate.js");
const { db } = await import("../src/db/client.js");
const tables = await import("../src/db/schema.js");
await runMigrations();
type Alert = import("../src/services/alertTypes.js").Alert;
type Settings = import("../src/services/settingsStore.js").AlertTicketSettings;
type Row = import("../src/services/alertTickets.js").TicketRow;
type NewTicket = import("../src/integrations/osticket/ticketApi.js").NewTicket;
const alert = (id: string, over: Partial<Alert> = {}): Alert => ({ id, severity: "critical", category: "offline", source: "Server", message: `Problem ${id}`, link: "/servers/1", silenced: false, ...over });
const settings = (over: Partial<Settings> = {}): Settings => ({ ...(structuredClone((require_defaults())) as Settings), enabled: true, integrationId: 1, requesterEmail: "hm@example.test", ...over });
function require_defaults(): Settings {
return { enabled: false, integrationId: null, severities: ["critical", "warning"], categories: [], requesterName: "Homelab Manager", requesterEmail: "", topicId: null, priorityId: null, notifyStaff: true, existingProblems: "ignore", confirmChecks: 2, summaryAbove: 5, reopenAfterMinutes: 60 };
}
const T0 = new Date("2026-10-07T10:00:00.000Z");
const at = (minutes: number) => new Date(T0.getTime() + minutes * 60_000);
const row = (over: Partial<Row>): Row => ({ id: 1, alertKey: "a", status: "open", seenCount: 1, integrationId: 1, ticketNumber: "1001", grouped: false, severity: "critical", message: "m", firstSeenAt: T0.toISOString(), lastSeenAt: T0.toISOString(), ticketedAt: T0.toISOString(), clearedAt: null, ...over });
const plan = (over: Partial<Parameters<typeof planTicketRun>[0]> & { alerts: Alert[] }) => planTicketRun({ rows: [], settings: settings(), now: at(0), baseline: false, complete: true, ...over });
const kinds = (p: ReturnType<typeof planTicketRun>) => p.ops.map((o) => o.kind);
// ─── which alerts count ─────────────────────────────────────────────────────
describe("which alerts open a ticket", () => {
test("by severity and by kind", () => {
const s = settings({ severities: ["critical"], categories: ["disk", "offline"] });
assert.equal(qualifies(alert("a", { severity: "critical", category: "disk" }), s), true);
assert.equal(qualifies(alert("a", { severity: "warning", category: "disk" }), s), false, "warnings weren't asked for");
assert.equal(qualifies(alert("a", { severity: "critical", category: "backup" }), s), false, "backups weren't asked for");
assert.equal(qualifies(alert("a", { severity: "info", category: "disk" }), settings({ severities: ["critical", "warning", "info"] })), true);
assert.equal(qualifies(alert("a", { category: "backup" }), settings({ categories: [] })), true, "no kinds chosen means every kind");
});
test("never one under a maintenance window", () => {
assert.equal(qualifies(alert("a", { silenced: true }), settings()), false);
});
test("never one about the ticketing system itself", () => {
assert.equal(qualifies(alert("tickets:osticket:1", { category: "tickets" }), settings({ severities: ["critical", "warning", "info"] })), false, "overdue tickets");
assert.equal(qualifies(alert("integration:failing:osticket", { category: "integration" }), settings()), false, "osTicket failing: a ticket would go to the thing that is down");
assert.equal(qualifies(alert("integration:failing:proxmox", { category: "integration" }), settings()), true, "another integration failing is fair game");
});
});
// ─── the decision ───────────────────────────────────────────────────────────
describe("planTicketRun", () => {
test("a new problem waits for a second check before it opens a ticket", () => {
const p = plan({ alerts: [alert("a")] });
assert.deepEqual(kinds(p), ["insertPending"]);
assert.equal(p.toTicket.length, 0);
});
test("…and opens one at the second", () => {
const p = plan({ alerts: [alert("a")], rows: [row({ alertKey: "a", status: "pending", ticketNumber: null, seenCount: 1 })] });
assert.equal(p.toTicket.length, 1);
assert.equal(p.toTicket[0].row?.status, "pending");
});
test("a setting of 3 checks needs three", () => {
const s = settings({ confirmChecks: 3 });
const second = plan({ alerts: [alert("a")], settings: s, rows: [row({ alertKey: "a", status: "pending", ticketNumber: null, seenCount: 1 })] });
assert.deepEqual(kinds(second), ["bump"]);
const third = plan({ alerts: [alert("a")], settings: s, rows: [row({ alertKey: "a", status: "pending", ticketNumber: null, seenCount: 2 })] });
assert.equal(third.toTicket.length, 1);
});
test("a setting of 1 opens at once", () => {
const p = plan({ alerts: [alert("a")], settings: settings({ confirmChecks: 1 }) });
assert.equal(p.toTicket.length, 1);
assert.equal(p.toTicket[0].row, null);
assert.deepEqual(kinds(p), []);
});
test("a blip that goes away before it lasted is forgotten, never ticketed", () => {
const p = plan({ alerts: [], rows: [row({ alertKey: "a", status: "pending", ticketNumber: null })] });
assert.deepEqual(kinds(p), ["dropPending"]);
assert.equal(p.toTicket.length, 0);
});
test("a problem with a ticket that is still there is only noted", () => {
const p = plan({ alerts: [alert("a")], rows: [row({ alertKey: "a" })] });
assert.deepEqual(kinds(p), ["touch"]);
assert.equal(p.toTicket.length, 0, "a second ticket for the same problem");
});
test("a problem that is gone is marked cleared", () => {
assert.deepEqual(kinds(plan({ alerts: [], rows: [row({ alertKey: "a" })] })), ["clear"]);
});
test("when something couldn't be read, 'not in the list' is not taken to mean 'gone'", () => {
const p = plan({ alerts: [], rows: [row({ alertKey: "a" }), row({ id: 2, alertKey: "b", status: "pending", ticketNumber: null })], complete: false });
assert.deepEqual(kinds(p), []);
});
test("a problem that clears and comes straight back is the same problem", () => {
const cleared = row({ alertKey: "a", clearedAt: at(-10).toISOString() });
const p = plan({ alerts: [alert("a")], rows: [cleared] });
assert.deepEqual(kinds(p), ["reactivate"]);
assert.equal(p.toTicket.length, 0);
});
test("one that comes back after the reopen window is a new occurrence", () => {
const cleared = row({ alertKey: "a", clearedAt: at(-120).toISOString() });
assert.deepEqual(kinds(plan({ alerts: [alert("a")], rows: [cleared] })), ["insertPending"]);
assert.equal(plan({ alerts: [alert("a")], rows: [cleared], settings: settings({ confirmChecks: 1 }) }).toTicket.length, 1);
});
test("a reopen window of 0 makes every return a new occurrence", () => {
const cleared = row({ alertKey: "a", clearedAt: at(-1).toISOString() });
assert.deepEqual(kinds(plan({ alerts: [alert("a")], rows: [cleared], settings: settings({ reopenAfterMinutes: 0 }) })), ["insertPending"]);
});
test("a pending problem that is silenced for now waits without counting", () => {
const p = plan({ alerts: [alert("a", { silenced: true })], rows: [row({ alertKey: "a", status: "pending", ticketNumber: null, seenCount: 1 })] });
assert.deepEqual(kinds(p), ["touch"]);
assert.equal(p.toTicket.length, 0);
});
test("the first check after switching on records what's already wrong and opens nothing", () => {
const p = plan({ alerts: [alert("a"), alert("b", { severity: "info" })], baseline: true });
assert.deepEqual(kinds(p), ["insertBaseline"], "only what qualifies is recorded");
assert.equal(p.toTicket.length, 0);
});
test("alerts that don't qualify leave no trace", () => {
const p = plan({ alerts: [alert("a", { severity: "info" }), alert("b", { silenced: true })] });
assert.deepEqual(kinds(p), []);
});
});
// ─── what the ticket says ───────────────────────────────────────────────────
describe("the ticket text", () => {
test("a single ticket says what, where, since when and how to look further", () => {
const t = buildTicket(alert("offline:server:3", { message: "Server nas has not reported for 3h", source: "Server", link: "/servers/3" }), "2026-10-07T10:05:00.000Z");
assert.equal(t.subject, "[Homelab] Critical: Server nas has not reported for 3h");
assert.match(t.message, /Severity: Critical/);
assert.match(t.message, /Kind: Server down/);
assert.match(t.message, /Source: Server/);
assert.match(t.message, /First seen: 2026-10-07 10:05 UTC/);
assert.match(t.message, /Details: https:\/\/hm\.example\.lan\/servers\/3/);
assert.match(t.message, /https:\/\/hm\.example\.lan\/alerts/);
assert.match(t.message, /alert offline:server:3/);
assert.match(t.message, /not updated or closed automatically/);
});
test("a very long message makes a subject osTicket will take", () => {
assert.ok(buildTicket(alert("a", { message: "x ".repeat(500) }), T0.toISOString()).subject.length <= 200);
});
test("a summary lists every alert", () => {
const t = buildSummaryTicket([1, 2, 3].map((n) => ({ alert: alert(`a${n}`, { message: `Thing ${n} is down` }), firstSeenAt: T0.toISOString() })));
assert.equal(t.subject, "[Homelab] 3 problems detected");
for (const n of [1, 2, 3]) assert.match(t.message, new RegExp(`Thing ${n} is down`));
});
});
// ─── the osTicket API ───────────────────────────────────────────────────────
describe("osTicket API client", () => {
type Seen = { method: string; url: string; headers: http.IncomingHttpHeaders; body: any };
let server: http.Server;
let port = 0;
let seen: Seen[] = [];
let respond: (req: http.IncomingMessage, res: http.ServerResponse) => void = (_req, res) => res.writeHead(201).end("123456");
before(async () => {
server = http.createServer((req, res) => {
let raw = "";
req.on("data", (c) => (raw += c));
req.on("end", () => {
let body: unknown = raw;
try {
body = JSON.parse(raw);
} catch {
// keep the text
}
seen.push({ method: req.method ?? "", url: req.url ?? "", headers: req.headers, body });
respond(req, res);
});
});
await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
port = (server.address() as { port: number }).port;
});
after(() => server.close());
beforeEach(() => {
seen = [];
respond = (_req, res) => res.writeHead(201).end("123456");
});
const client = (over: Record<string, unknown> = {}) => createOsTicketTicketApi({ apiUrl: `http://127.0.0.1:${port}/`, apiKey: "KEY-SECRET-123", ...over } as never);
const ticket = (over: Partial<NewTicket> = {}): NewTicket => ({ name: "Homelab Manager", email: "hm@example.test", subject: "S", message: "M", alertStaff: true, ...over });
test("posts JSON to api/tickets.json with the key in X-API-Key, and returns the ticket number", async () => {
const r = await client().createTicket(ticket({ subject: "Disk full", message: "Line one\nLine two — åäö ✓" }));
assert.equal(r.number, "123456");
const s = seen[0];
assert.equal(s.method, "POST");
assert.equal(s.url, "/api/tickets.json");
assert.equal(s.headers["x-api-key"], "KEY-SECRET-123");
assert.match(String(s.headers["content-type"]), /application\/json/);
assert.equal(s.body.subject, "Disk full");
assert.equal(s.body.name, "Homelab Manager");
assert.equal(s.body.email, "hm@example.test");
assert.equal(s.body.source, "API");
assert.equal(s.body.alert, true);
assert.equal(s.body.autorespond, false, "an acknowledgement to the app's own address would only bounce");
// osTicket reads a message's type from an RFC 2397 data URL; decoded it must be exactly what was written
assert.match(s.body.message, /^data:text\/plain;charset=utf-8,/);
assert.equal(decodeURIComponent(s.body.message.replace(/^data:text\/plain;charset=utf-8,/, "")), "Line one\nLine two — åäö ✓");
});
test("topic and priority are sent only when set; staff alerts can be switched off", async () => {
await client().createTicket(ticket());
assert.equal("topicId" in seen[0].body, false);
assert.equal("priority" in seen[0].body, false);
await client().createTicket(ticket({ topicId: 12, priorityId: 3, alertStaff: false }));
assert.equal(seen[1].body.topicId, 12);
assert.equal(seen[1].body.priority, 3);
assert.equal(seen[1].body.alert, false);
});
test("works from an address with or without a trailing slash, or in a sub-folder", async () => {
await client({ apiUrl: `http://127.0.0.1:${port}/support` }).createTicket(ticket());
await client({ apiUrl: `http://127.0.0.1:${port}/support/` }).createTicket(ticket());
assert.deepEqual(seen.map((s) => s.url), ["/support/api/tickets.json", "/support/api/tickets.json"]);
assert.equal(ticketEndpoint("https://t.example.lan").href, "https://t.example.lan/api/tickets.json");
assert.throws(() => ticketEndpoint("ftp://t.example.lan"), /http/);
});
test("understands the ways a ticket number can come back", async () => {
for (const [body, expected] of [["123456", "123456"], ['"987654"', "987654"], [" 555\n", "555"], ["", null], ["{}", null]] as const) {
respond = (_req, res) => res.writeHead(201).end(body);
assert.equal((await client().createTicket(ticket())).number, expected, JSON.stringify(body));
}
});
test("a refused key says what to check, and never repeats the key", async () => {
respond = (_req, res) => res.writeHead(401).end("Valid API key required");
const err = await client().createTicket(ticket()).then(() => null, (e: Error) => e);
assert.ok(err);
assert.match(err.message, /refused the API key/);
assert.match(err.message, /IP address/);
assert.doesNotMatch(err.message, /KEY-SECRET-123/);
respond = (_req, res) => res.writeHead(403).end("");
await assert.rejects(() => client().createTicket(ticket()), /refused the API key/);
});
test("other failures are explained", async () => {
respond = (_req, res) => res.writeHead(404).end("nope");
await assert.rejects(() => client().createTicket(ticket()), /no osTicket API at/i);
respond = (_req, res) => res.writeHead(400).end("Unable to create new ticket: validation errors exist\n\u0000");
await assert.rejects(() => client().createTicket(ticket()), /rejected the ticket: Unable to create new ticket/);
respond = (_req, res) => res.writeHead(500).end("boom");
await assert.rejects(() => client().createTicket(ticket()), /HTTP 500/);
respond = (_req, res) => res.writeHead(301, { location: "https://tickets.example.lan/api/tickets.json" }).end("");
await assert.rejects(() => client().createTicket(ticket()), /redirected to https:\/\/tickets\.example\.lan/);
});
test("missing setup is a clear error, and nothing is sent", async () => {
await assert.rejects(() => createOsTicketTicketApi({ apiUrl: "", apiKey: "" } as never).createTicket(ticket()), /no ticket API address and key/);
assert.equal(seen.length, 0);
assert.equal(hasTicketApi({ apiUrl: "https://x", apiKey: "k" }), true);
assert.equal(hasTicketApi({ apiUrl: "https://x" }), false);
assert.equal(hasTicketApi({ apiKey: "k" }), false);
assert.equal(hasTicketApi({ apiUrl: " ", apiKey: "k" }), false);
});
test("an unreachable osTicket is an error, not a hang", async () => {
await assert.rejects(() => createOsTicketTicketApi({ apiUrl: "http://127.0.0.1:1/", apiKey: "k" } as never).createTicket(ticket()), /ECONNREFUSED|connect/i);
});
test("a link to the ticket in the staff panel", () => {
assert.equal(ticketUrl("https://t.example.lan", "123456"), "https://t.example.lan/scp/tickets.php?number=123456");
assert.equal(ticketUrl("https://t.example.lan/support/", "98 7"), "https://t.example.lan/support/scp/tickets.php?number=98%207");
assert.equal(ticketUrl("not a url", "1"), null);
});
});
// ─── the runner, over several checks ────────────────────────────────────────
describe("runAlertTicketCheck", () => {
let sent: NewTicket[] = [];
let failNext = 0;
const create = async (t: NewTicket) => {
if (failNext > 0) {
failNext--;
throw new Error("osTicket refused the API key.");
}
sent.push(t);
return { number: String(1000 + sent.length) };
};
const report = (alerts: Alert[], incomplete = false) => ({
alerts,
counts: { critical: 0, warning: 0, info: 0, silenced: 0 },
couldntCheck: incomplete ? [{ name: "Proxmox", error: "down", affects: ["backup"] }] : [],
notes: [],
generatedAt: T0.toISOString(),
cached: false,
});
const check = (minutes: number, alerts: Alert[], opts: { incomplete?: boolean } = {}) =>
runAlertTicketCheck({ deps: { getReport: async () => report(alerts, opts.incomplete), createTicket: create, now: () => at(minutes) } });
const rows = () => db.select().from(tables.alertTickets);
let osTicketId = 0;
const configure = (over: Partial<Settings> = {}) => updateSettings({ alertTickets: { ...settings(), integrationId: osTicketId, existingProblems: "ticket", ...over } });
before(async () => {
// The rows the runner writes point at an integration, so there has to be one.
await db.delete(tables.integrations);
osTicketId = (await db.insert(tables.integrations).values({ type: "osticket", name: "osT", baseUrl: "", config: "{}" }).returning())[0].id;
});
beforeEach(async () => {
sent = [];
failNext = 0;
await db.delete(tables.alertTickets);
await db.delete(tables.auditLog);
await setInternalFlag("alertTicketsBaselineDone", "");
await setInternalFlag("alertTicketsLastRun", "");
await configure();
});
test("does nothing while switched off", async () => {
await configure({ enabled: false });
const r = await check(0, [alert("a")]);
assert.equal(r.skipped, "disabled");
assert.equal(sent.length, 0);
assert.equal((await rows()).length, 0);
});
test("one ticket for a problem that lasts, however many checks see it", async () => {
assert.equal((await check(0, [alert("a")])).ticketsOpened, 0);
assert.equal((await rows())[0].status, "pending");
const second = await check(15, [alert("a")]);
assert.equal(second.ticketsOpened, 1);
for (const m of [30, 45, 60, 75]) assert.equal((await check(m, [alert("a")])).ticketsOpened, 0);
assert.equal(sent.length, 1, "more than one ticket for one problem");
const [only] = await rows();
assert.equal(only.status, "open");
assert.equal(only.ticketNumber, "1001");
assert.equal(only.ticketedAt, at(15).toISOString());
});
test("the ticket carries the settings and the alert's text", async () => {
await configure({ requesterName: "HM", requesterEmail: "alerts@example.test", topicId: 4, priorityId: 2, notifyStaff: false });
await check(0, [alert("a", { message: "Disk / on nas is 97% full" })]);
await check(15, [alert("a", { message: "Disk / on nas is 97% full" })]);
assert.equal(sent.length, 1);
assert.equal(sent[0].name, "HM");
assert.equal(sent[0].email, "alerts@example.test");
assert.equal(sent[0].topicId, 4);
assert.equal(sent[0].priorityId, 2);
assert.equal(sent[0].alertStaff, false);
assert.match(sent[0].subject, /Disk \/ on nas is 97% full/);
assert.match(sent[0].message, /First seen: 2026-10-07 10:00 UTC/, "the time it was first seen, not the time of the second check");
});
test("a blip that fixes itself never opens one", async () => {
await check(0, [alert("a")]);
await check(15, []);
await check(30, [alert("a")]);
await check(45, []);
assert.equal(sent.length, 0);
assert.equal((await rows()).length, 0);
});
test("a problem that clears and returns quickly is the same ticket; much later it is a new one", async () => {
await check(0, [alert("a")]);
await check(15, [alert("a")]);
assert.equal(sent.length, 1);
await check(30, []);
assert.ok((await rows())[0].clearedAt, "should be marked cleared");
await check(45, [alert("a")]); // back within the hour
assert.equal(sent.length, 1, "a flap opened a second ticket");
assert.equal((await rows())[0].clearedAt, null);
await check(60, []);
await check(200, [alert("a")]); // back much later: pending again…
assert.equal(sent.length, 1);
await check(215, [alert("a")]); // …and now a new ticket
assert.equal(sent.length, 2);
assert.equal((await rows()).length, 2, "one row per occurrence");
});
test("something under a maintenance window gets no ticket, and gets one if it is still there after", async () => {
await check(0, [alert("a", { silenced: true })]);
await check(15, [alert("a", { silenced: true })]);
assert.equal(sent.length, 0);
assert.equal((await rows()).length, 0);
await check(30, [alert("a")]);
await check(45, [alert("a")]);
assert.equal(sent.length, 1);
});
test("when something couldn't be read, an open problem isn't called cleared", async () => {
await check(0, [alert("a")]);
await check(15, [alert("a")]);
await check(30, [], { incomplete: true });
assert.equal((await rows())[0].clearedAt, null);
await check(45, [], {});
assert.ok((await rows())[0].clearedAt);
});
test("many new problems at once become one summary ticket", async () => {
const many = Array.from({ length: 8 }, (_, i) => alert(`a${i}`));
await check(0, many);
const r = await check(15, many);
assert.equal(sent.length, 1, "should be a single ticket");
assert.equal(r.ticketsOpened, 1);
assert.equal(r.alertsCovered, 8);
assert.match(sent[0].subject, /8 problems detected/);
for (let i = 0; i < 8; i++) assert.match(sent[0].message, new RegExp(`Problem a${i}`));
const all = await rows();
assert.equal(all.length, 8);
assert.ok(all.every((x) => x.status === "open" && x.grouped && x.ticketNumber === "1001"));
assert.equal((await check(30, many)).ticketsOpened, 0, "the covered alerts open nothing more");
});
test("a few at once each get their own", async () => {
const few = [alert("a"), alert("b"), alert("c")];
await check(0, few);
await check(15, few);
assert.equal(sent.length, 3);
assert.ok((await rows()).every((x) => !x.grouped));
assert.deepEqual(new Set((await rows()).map((x) => x.ticketNumber)).size, 3);
});
test("a ticket that couldn't be opened is tried again at the next check, and nothing is claimed meanwhile", async () => {
await check(0, [alert("a")]);
failNext = 1;
const r = await check(15, [alert("a")]);
assert.equal(r.failed, 1);
assert.match(r.error ?? "", /refused the API key/);
assert.equal((await rows())[0].status, "pending");
assert.equal(sent.length, 0);
const again = await check(30, [alert("a")]);
assert.equal(again.ticketsOpened, 1);
assert.equal(sent.length, 1);
});
test("problems already there when it is switched on get no ticket (unless asked), but a new one does", async () => {
await configure({ existingProblems: "ignore" });
const first = await check(0, [alert("old")]);
assert.equal(first.baseline, 1);
assert.equal((await rows())[0].status, "baseline");
await check(15, [alert("old")]);
await check(30, [alert("old"), alert("new")]);
await check(45, [alert("old"), alert("new")]);
assert.equal(sent.length, 1);
assert.match(sent[0].subject, /Problem new/);
assert.equal(sent.some((t) => /Problem old/.test(t.subject)), false);
});
test("a baseline problem that clears and later returns is a new problem", async () => {
await configure({ existingProblems: "ignore" });
await check(0, [alert("old")]);
await check(15, []);
await check(200, [alert("old")]);
await check(215, [alert("old")]);
assert.equal(sent.length, 1);
});
test("switching it off and on again starts from a new baseline", async () => {
await configure({ existingProblems: "ignore" });
await check(0, [alert("old")]);
await configure({ enabled: false, existingProblems: "ignore" });
await check(15, [alert("old")]);
await configure({ enabled: true, existingProblems: "ignore" });
await db.delete(tables.alertTickets);
const r = await check(30, [alert("old")]);
assert.equal(r.baseline, 1, "should record the baseline again");
assert.equal(sent.length, 0);
});
test("the baseline isn't called complete while a source couldn't be read", async () => {
await configure({ existingProblems: "ignore" });
await check(0, [alert("old")], { incomplete: true });
assert.equal((await getAlertTicketStatus()).baselinePending, true);
await check(15, [alert("old")]);
assert.equal((await getAlertTicketStatus()).baselinePending, false);
});
test("it never opens a ticket about osTicket", async () => {
const own = [alert("integration:failing:osticket", { category: "integration" }), alert("tickets:osticket:1", { category: "tickets" })];
await check(0, own);
await check(15, own);
assert.equal(sent.length, 0);
});
test("each ticket is in the audit log, with the ticket number and no secrets", async () => {
await check(0, [alert("a")]);
await check(15, [alert("a")]);
const entries = (await db.select().from(tables.auditLog)).filter((e) => e.category === "alert_ticket");
assert.equal(entries.length, 1);
assert.equal(entries[0].action, "create");
assert.equal(entries[0].targetId, "a");
assert.equal(JSON.parse(entries[0].detail!).ticket, "1001");
assert.equal(entries[0].actorLabel, "system");
});
test("it reports missing setup instead of failing silently", async () => {
await configure({ integrationId: null });
const r = await runAlertTicketCheck({ deps: { getReport: async () => report([alert("a")]), now: () => at(0) } });
assert.match(r.error ?? "", /No osTicket integration is chosen/);
await configure({ integrationId: 999 });
assert.match((await runAlertTicketCheck({ deps: { getReport: async () => report([]), now: () => at(0) } })).error ?? "", /no longer exists/);
});
test("the status says how many are open, waiting and baselined", async () => {
await configure({ existingProblems: "ignore" });
await check(0, [alert("old")]);
await check(15, [alert("old"), alert("a")]);
await check(30, [alert("old"), alert("a")]);
const s = await getAlertTicketStatus();
assert.equal(s.baseline, 1);
assert.equal(s.open, 1);
assert.equal(s.pending, 0);
assert.equal(s.lastRun?.ticketsOpened, 1);
});
test("old cleared records are removed, recent ones kept", async () => {
const old = new Date(T0.getTime() - 200 * 86_400_000).toISOString();
await db.insert(tables.alertTickets).values({ alertKey: "ancient", status: "open", severity: "critical", message: "m", firstSeenAt: old, lastSeenAt: old, clearedAt: old });
await db.insert(tables.alertTickets).values({ alertKey: "recent", status: "open", severity: "critical", message: "m", firstSeenAt: T0.toISOString(), lastSeenAt: T0.toISOString(), clearedAt: T0.toISOString() });
await check(0, []);
assert.deepEqual((await rows()).map((r) => r.alertKey), ["recent"]);
});
test("ticketsForAlerts links an active ticket to osTicket's staff panel", async () => {
await db.delete(tables.integrations);
const [integration] = await db.insert(tables.integrations).values({ type: "osticket", name: "osT", baseUrl: "", config: JSON.stringify({ apiUrl: "https://tickets.example.lan/" }) }).returning();
await db.insert(tables.alertTickets).values([
{ alertKey: "a", status: "open", ticketNumber: "4321", integrationId: integration.id, severity: "critical", message: "m", firstSeenAt: T0.toISOString(), lastSeenAt: T0.toISOString(), ticketedAt: T0.toISOString() },
{ alertKey: "b", status: "pending", integrationId: integration.id, severity: "critical", message: "m", firstSeenAt: T0.toISOString(), lastSeenAt: T0.toISOString() },
{ alertKey: "c", status: "open", ticketNumber: "1", integrationId: integration.id, severity: "critical", message: "m", firstSeenAt: T0.toISOString(), lastSeenAt: T0.toISOString(), clearedAt: T0.toISOString() },
]);
const found = await ticketsForAlerts(["a", "b", "c", "d"]);
assert.deepEqual([...found.keys()], ["a"], "only a ticketed, still-active problem shows one");
assert.equal(found.get("a")!.number, "4321");
assert.equal(found.get("a")!.url, "https://tickets.example.lan/scp/tickets.php?number=4321");
assert.equal((await ticketsForAlerts([])).size, 0);
});
});
// ─── the settings and routes ────────────────────────────────────────────────
describe("admin routes", () => {
let appServer: http.Server;
let appPort = 0;
let fake: http.Server;
let fakePort = 0;
let fakeResponse: (res: http.ServerResponse) => void = (res) => res.writeHead(201).end("424242");
const fakeSeen: { key?: string; body: any }[] = [];
let admin = "";
let operator = "";
let viewer = "";
let integrationId = 0;
let plainIntegrationId = 0;
let last = { status: 0, text: "" };
function send(cookie: string | undefined, method: string, path: string, body?: object): Promise<number> {
return new Promise((resolve, reject) => {
const payload = body ? JSON.stringify(body) : undefined;
const headers: Record<string, string> = {};
if (cookie) headers.cookie = cookie;
if (payload) {
headers["content-type"] = "application/json";
headers["content-length"] = String(Buffer.byteLength(payload));
}
const req = http.request({ host: "127.0.0.1", port: appPort, method, path, headers }, (res) => {
let text = "";
res.on("data", (c) => (text += c));
res.on("end", () => {
last = { status: res.statusCode ?? 0, text };
resolve(res.statusCode ?? 0);
});
});
req.on("error", reject);
if (payload) req.write(payload);
req.end();
});
}
const json = () => JSON.parse(last.text);
before(async () => {
const express = (await import("express")).default;
const session = (await import("express-session")).default;
const { alertTicketsRouter } = await import("../src/routes/alertTickets.js");
const { integrationsRouter } = await import("../src/routes/integrations.js");
fake = http.createServer((req, res) => {
let raw = "";
req.on("data", (c) => (raw += c));
req.on("end", () => {
fakeSeen.push({ key: req.headers["x-api-key"] as string | undefined, body: JSON.parse(raw || "{}") });
fakeResponse(res);
});
});
await new Promise<void>((r) => fake.listen(0, "127.0.0.1", r));
fakePort = (fake.address() as { port: number }).port;
await db.delete(tables.integrations);
await db.delete(tables.users);
await db.insert(tables.users).values([
{ oidcSub: "ad", email: "ad@x", name: "Admin", role: "admin" },
{ oidcSub: "op", email: "op@x", name: "Operator", role: "operator" },
{ oidcSub: "vw", email: "vw@x", name: "Viewer", role: "viewer" },
]);
const app = express();
app.use(express.json());
app.use(session({ secret: "t", resave: false, saveUninitialized: true }));
app.post("/login/:sub", (req, res) => {
req.session.user = { sub: req.params.sub } as never;
res.json({});
});
app.use("/api/alert-tickets", alertTicketsRouter);
app.use("/api/integrations", integrationsRouter);
appServer = app.listen(0);
appPort = (appServer.address() as { port: number }).port;
const login = async (sub: string) => ((await fetch(`http://127.0.0.1:${appPort}/login/${sub}`, { method: "POST" })).headers.get("set-cookie") as string).split(";")[0];
admin = await login("ad");
operator = await login("op");
viewer = await login("vw");
// Two osTicket integrations, made through the real route: one with the ticket API filled in, one without.
const db_ = { host: "db.example.lan", database: "osticket", username: "ro", password: "pw" };
assert.equal(await send(admin, "POST", "/api/integrations", { type: "osticket", name: "osTicket (API)", config: { ...db_, apiUrl: `http://127.0.0.1:${fakePort}/`, apiKey: "THE-API-KEY" } }), 201, last.text);
integrationId = json().integration.id;
assert.equal(await send(admin, "POST", "/api/integrations", { type: "osticket", name: "osTicket (read-only)", config: db_ }), 201, "the ticket API fields must stay optional");
plainIntegrationId = json().integration.id;
});
after(() => {
appServer?.close();
fake?.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows keeps the SQLite file locked until the process exits.
}
});
beforeEach(async () => {
fakeSeen.length = 0;
fakeResponse = (res) => res.writeHead(201).end("424242");
await db.delete(tables.auditLog);
await updateSettings({ alertTickets: require_defaults() });
});
test("only an administrator can read or change any of it", async () => {
for (const [cookie, label] of [[undefined, "signed out"], [viewer, "viewer"], [operator, "operator"]] as const) {
const want = cookie ? 403 : 401;
assert.equal(await send(cookie, "GET", "/api/alert-tickets"), want, `GET as ${label}`);
assert.equal(await send(cookie, "PUT", "/api/alert-tickets", { enabled: false }), want, `PUT as ${label}`);
assert.equal(await send(cookie, "POST", "/api/alert-tickets/test"), want, `test as ${label}`);
assert.equal(await send(cookie, "POST", "/api/alert-tickets/run"), want, `run as ${label}`);
}
assert.equal(fakeSeen.length, 0, "a ticket was opened for someone who may not");
});
test("the overview lists the osTicket integrations and whether each can open tickets", async () => {
assert.equal(await send(admin, "GET", "/api/alert-tickets"), 200);
const o = json();
assert.equal(o.settings.enabled, false);
assert.deepEqual(o.integrations.map((i: { name: string; ticketApiReady: boolean }) => [i.name, i.ticketApiReady]).sort(), [["osTicket (API)", true], ["osTicket (read-only)", false]]);
assert.ok(o.categories.length >= 8);
assert.equal(o.categories.some((c: { value: string }) => c.value === "tickets"), false, "tickets about tickets aren't offered");
assert.doesNotMatch(last.text, /THE-API-KEY/, "the API key must never be sent to the browser");
});
test("it can't be switched on without what it needs", async () => {
const complete = { enabled: true, integrationId, requesterEmail: "hm@example.test" };
assert.equal(await send(admin, "PUT", "/api/alert-tickets", { enabled: true }), 400);
assert.match(json().message, /Choose which osTicket integration/);
assert.equal(await send(admin, "PUT", "/api/alert-tickets", { ...complete, integrationId: plainIntegrationId }), 400);
assert.match(json().message, /no ticket API address and key/);
assert.equal(await send(admin, "PUT", "/api/alert-tickets", { ...complete, integrationId: 9999 }), 400);
assert.equal(await send(admin, "PUT", "/api/alert-tickets", { ...complete, requesterEmail: "" }), 400);
assert.match(json().message, /email/i);
assert.equal(await send(admin, "PUT", "/api/alert-tickets", { ...complete, severities: [] }), 400);
assert.match(json().message, /severity/i);
assert.equal((await getSettings()).alertTickets.enabled, false, "a refused change must change nothing");
assert.equal(await send(admin, "PUT", "/api/alert-tickets", complete), 200, last.text);
assert.equal((await getSettings()).alertTickets.enabled, true);
});
test("values are checked", async () => {
for (const bad of [{ requesterEmail: "not an email" }, { confirmChecks: 0 }, { confirmChecks: 11 }, { summaryAbove: 0 }, { reopenAfterMinutes: -1 }, { severities: ["urgent"] }, { categories: ["tickets"] }, { topicId: 0 }, { existingProblems: "maybe" }]) {
assert.equal(await send(admin, "PUT", "/api/alert-tickets", bad), 400, JSON.stringify(bad));
}
assert.equal(await send(admin, "PUT", "/api/alert-tickets", { confirmChecks: 1, summaryAbove: 3, reopenAfterMinutes: 0, topicId: 7, priorityId: null, categories: ["disk", "offline"], severities: ["critical"] }), 200, last.text);
const s = (await getSettings()).alertTickets;
assert.deepEqual([s.confirmChecks, s.summaryAbove, s.reopenAfterMinutes, s.topicId, s.priorityId, s.categories, s.severities], [1, 3, 0, 7, null, ["disk", "offline"], ["critical"]]);
});
test("a change is in the audit log, with what changed", async () => {
await send(admin, "PUT", "/api/alert-tickets", { enabled: true, integrationId, requesterEmail: "hm@example.test", confirmChecks: 3 });
const entry = (await db.select().from(tables.auditLog)).find((e) => e.action === "update_alert_tickets");
assert.ok(entry);
const changes = JSON.parse(entry.detail!).changes;
assert.deepEqual(changes.confirmChecks, { from: 2, to: 3 });
assert.deepEqual(changes.enabled, { from: false, to: true });
assert.doesNotMatch(entry.detail!, /THE-API-KEY/);
});
test("the test ticket reaches osTicket with the key, and says it's a test", async () => {
await send(admin, "PUT", "/api/alert-tickets", { enabled: true, integrationId, requesterEmail: "hm@example.test", requesterName: "HM", topicId: 5 });
assert.equal(await send(admin, "POST", "/api/alert-tickets/test"), 200, last.text);
assert.equal(json().ticketNumber, "424242");
assert.equal(fakeSeen.length, 1);
assert.equal(fakeSeen[0].key, "THE-API-KEY");
assert.match(fakeSeen[0].body.subject, /Test ticket/);
assert.equal(fakeSeen[0].body.topicId, 5);
assert.equal(fakeSeen[0].body.email, "hm@example.test");
assert.ok((await db.select().from(tables.auditLog)).some((e) => e.category === "alert_ticket" && e.action === "test"));
});
test("a refused key shows up as a readable failure on the test ticket", async () => {
await send(admin, "PUT", "/api/alert-tickets", { enabled: true, integrationId, requesterEmail: "hm@example.test" });
fakeResponse = (res) => res.writeHead(401).end("Valid API key required");
assert.equal(await send(admin, "POST", "/api/alert-tickets/test"), 502);
assert.match(json().message, /refused the API key/);
assert.doesNotMatch(last.text, /THE-API-KEY/);
});
test("a test ticket needs the setup too", async () => {
assert.equal(await send(admin, "POST", "/api/alert-tickets/test"), 502);
assert.match(json().message, /No osTicket integration is chosen/);
});
test("'check now' on a switched-off feature does nothing", async () => {
assert.equal(await send(admin, "POST", "/api/alert-tickets/run"), 200);
assert.equal(json().summary.skipped, "disabled");
assert.equal(fakeSeen.length, 0);
});
});
describe("osTicket integration fields", () => {
test("the ticket API settings are optional, the key is secret, and the certificate option is a checkbox", async () => {
const { INTEGRATION_FIELDS, validateIntegrationConfig, splitIntegrationConfig } = await import("../src/integrations/fieldSchemas.js");
const fields = INTEGRATION_FIELDS.osticket!;
const byKey = Object.fromEntries(fields.map((f) => [f.key, f]));
assert.equal(byKey.apiUrl.optional, true);
assert.equal(byKey.apiKey.optional, true);
assert.equal(byKey.apiKey.secret, true);
assert.equal(byKey.apiInsecure.type, "checkbox");
const db_ = { host: "h", database: "d", username: "u", password: "p" };
assert.deepEqual(validateIntegrationConfig("osticket", db_), [], "an integration with only the database fields is still valid");
const split = splitIntegrationConfig("osticket", { ...db_, apiUrl: "https://t", apiKey: "k", apiInsecure: true });
assert.deepEqual(Object.keys(split.secretFields).sort(), ["apiKey", "password"]);
assert.ok("apiUrl" in split.nonSecretFields && !("apiKey" in split.nonSecretFields));
});
});