Compare commits
3
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
aec553f122 | ||
|
|
96c93ef924 | ||
|
|
467d1a1a06 |
No files matched your search
+25
-2
@@ -24,7 +24,7 @@ what the app actually creates.
|
|||||||
| **File** | `DATABASE_PATH`, default `../data/homelab-manager.sqlite` (relative to `server/`; `/app/data/...` in Docker). The folder is created if missing. |
|
| **File** | `DATABASE_PATH`, default `../data/homelab-manager.sqlite` (relative to `server/`; `/app/data/...` in Docker). The folder is created if missing. |
|
||||||
| **Foreign keys** | Switched on for every connection (`PRAGMA foreign_keys = ON`), so the `ON DELETE` rules below are enforced. |
|
| **Foreign keys** | Switched on for every connection (`PRAGMA foreign_keys = ON`), so the `ON DELETE` rules below are enforced. |
|
||||||
| **Migrations** | SQL files in [`server/drizzle/`](server/drizzle) (`0000` … `0014`), applied automatically when the server starts. Which ones have run is recorded in the table `__drizzle_migrations`. |
|
| **Migrations** | SQL files in [`server/drizzle/`](server/drizzle) (`0000` … `0014`), applied automatically when the server starts. Which ones have run is recorded in the table `__drizzle_migrations`. |
|
||||||
| **Tables** | 21 application tables, plus drizzle's own `__drizzle_migrations`. |
|
| **Tables** | 22 application tables, plus drizzle's own `__drizzle_migrations`. |
|
||||||
|
|
||||||
**Not in the database:**
|
**Not in the database:**
|
||||||
|
|
||||||
@@ -58,6 +58,7 @@ erDiagram
|
|||||||
servers ||--o{ server_ports : "cascade"
|
servers ||--o{ server_ports : "cascade"
|
||||||
servers ||--o{ port_forwards : "optional (set null)"
|
servers ||--o{ port_forwards : "optional (set null)"
|
||||||
integrations ||--o{ servers : "proxmox link (app clears it)"
|
integrations ||--o{ servers : "proxmox link (app clears it)"
|
||||||
|
integrations ||--o{ alert_tickets : "osTicket used (set null)"
|
||||||
```
|
```
|
||||||
|
|
||||||
Eight tables stand alone, with no foreign keys: `settings`, `secrets`,
|
Eight tables stand alone, with no foreign keys: `settings`, `secrets`,
|
||||||
@@ -95,7 +96,7 @@ Who changed what. Written by the app on every change (see
|
|||||||
| `id` | integer PK | |
|
| `id` | integer PK | |
|
||||||
| `actor_user_id` | integer → `users.id`, **set null** on delete | Null for automatic actions, and for entries whose user was deleted. |
|
| `actor_user_id` | integer → `users.id`, **set null** on delete | Null for automatic actions, and for entries whose user was deleted. |
|
||||||
| `actor_label` | text | The user's name/email as it was at the time (or `system`), so an entry still reads correctly after the account is gone. |
|
| `actor_label` | text | The user's name/email as it was at the time (or `system`), so an entry still reads correctly after the account is gone. |
|
||||||
| `category` | text NOT NULL | Free text. In use: `server`, `integration`, `dns`, `settings`, `ipam`, `secret`, `domain`, `tag`, `task`, `session`, `network`, `maintenance`, `consistency`, `user`, `privacy`, `diag_log`. |
|
| `category` | text NOT NULL | Free text. In use: `server`, `integration`, `dns`, `settings`, `ipam`, `secret`, `domain`, `tag`, `task`, `session`, `network`, `maintenance`, `consistency`, `user`, `privacy`, `diag_log`, `alert_ticket`. |
|
||||||
| `action` | text NOT NULL | `create`, `update`, `delete`, `start`, `stop`, … — free text. |
|
| `action` | text NOT NULL | `create`, `update`, `delete`, `start`, `stop`, … — free text. |
|
||||||
| `target_type`, `target_id` | text | What it happened to. `target_id` is text so it can hold any kind of ID; there's no foreign key. |
|
| `target_type`, `target_id` | text | What it happened to. `target_id` is text so it can hold any kind of ID; there's no foreign key. |
|
||||||
| `detail` | text | JSON, free-form context (what changed, names, counts). Secrets are never put here. |
|
| `detail` | text | JSON, free-form context (what changed, names, counts). Secrets are never put here. |
|
||||||
@@ -405,6 +406,25 @@ Consistency findings someone looked at and decided are fine.
|
|||||||
| `reason`, `created_by` | text | |
|
| `reason`, `created_by` | text | |
|
||||||
| `created_at` | text NOT NULL | |
|
| `created_at` | text NOT NULL | |
|
||||||
|
|
||||||
|
#### `alert_tickets`
|
||||||
|
|
||||||
|
What the "open an osTicket ticket for an alert" 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 an alert clears and later returns for good, that is a new row.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `alert_key` | text NOT NULL, indexed | The alert's id as the Alerts page shows it (e.g. `disk:server:3:/`). Not a foreign key — alerts aren't stored. |
|
||||||
|
| `status` | text NOT NULL | `pending` (seen, not yet in enough checks in a row), `open` (a ticket was opened), `baseline` (already there when the feature was switched on, left alone). |
|
||||||
|
| `seen_count` | integer NOT NULL, default 1 | Checks in a row it has been seen while pending. |
|
||||||
|
| `integration_id` | integer → `integrations.id`, **set null** | The osTicket integration the ticket went to. |
|
||||||
|
| `ticket_number` | text | osTicket's own number; null unless `open`. |
|
||||||
|
| `grouped` | bool NOT NULL, default 0 | Part of a summary ticket that covers several alerts (they share a number). |
|
||||||
|
| `severity`, `message` | text NOT NULL | What the alert said when it was recorded. |
|
||||||
|
| `first_seen_at`, `last_seen_at` | text NOT NULL | ISO. |
|
||||||
|
| `ticketed_at` | text | ISO; when the ticket was opened. |
|
||||||
|
| `cleared_at` | text | ISO; null while the alert is still active. Rows cleared more than 180 days ago are deleted. |
|
||||||
|
|
||||||
## What's stored inside the JSON columns
|
## What's stored inside the JSON columns
|
||||||
|
|
||||||
| Column | Shape |
|
| Column | Shape |
|
||||||
@@ -446,6 +466,7 @@ that were never changed aren't stored; the app fills in defaults when reading.
|
|||||||
| `display` | `dateFormat`, `timeFormat`, `pageSize`. |
|
| `display` | `dateFormat`, `timeFormat`, `pageSize`. |
|
||||||
| `providerColors`, `integrationColors` | Badge colours, by provider / integration type. |
|
| `providerColors`, `integrationColors` | Badge colours, by provider / integration type. |
|
||||||
| `consistency` | `excludedRanges` — addresses the Consistency and IP Addresses pages ignore. Default `["172.16.0.0/12"]` (Docker's networks). |
|
| `consistency` | `excludedRanges` — addresses the Consistency and IP Addresses pages ignore. Default `["172.16.0.0/12"]` (Docker's networks). |
|
||||||
|
| `alertTickets` | Opening osTicket tickets for alerts: `enabled`, `integrationId`, `severities`, `categories`, `requesterName`/`requesterEmail`, `topicId`, `priorityId`, `notifyStaff`, `existingProblems`, `confirmChecks`, `summaryAbove`, `reopenAfterMinutes`. Edited under Settings → Alert tickets. The API address and key are on the osTicket integration, not here. |
|
||||||
| `nameGenerator` | `themes` — the Generator's server-name lists: `[{ "id", "label", "names": [...], "lastImport"? }]`. Edited under Settings → Names. |
|
| `nameGenerator` | `themes` — the Generator's server-name lists: `[{ "id", "label", "names": [...], "lastImport"? }]`. Edited under Settings → Names. |
|
||||||
|
|
||||||
Rows whose key starts with **`_internal:`** are scheduler bookkeeping, not
|
Rows whose key starts with **`_internal:`** are scheduler bookkeeping, not
|
||||||
@@ -455,6 +476,7 @@ settings, and aren't part of the app's settings object:
|
|||||||
|---|---|
|
|---|---|
|
||||||
| `_internal:secretCheckLastRunDate`, `tailscaleKeyCheckLastRunDate`, `dockerUpdateCheckLastRunDate`, `proxmoxBackupCheckLastRunDate`, `pbsVerificationCheckLastRunDate` | The date a daily check last ran, so a restart doesn't repeat it (or skip it). |
|
| `_internal:secretCheckLastRunDate`, `tailscaleKeyCheckLastRunDate`, `dockerUpdateCheckLastRunDate`, `proxmoxBackupCheckLastRunDate`, `pbsVerificationCheckLastRunDate` | The date a daily check last ran, so a restart doesn't repeat it (or skip it). |
|
||||||
| `_internal:logRetentionLastRunAt` | When the log purge last ran. |
|
| `_internal:logRetentionLastRunAt` | When the log purge last ran. |
|
||||||
|
| `_internal:alertTicketsBaselineDone`, `_internal:alertTicketsLastRun` | Whether the alert-ticket starting line has been recorded since the feature was switched on, and JSON for the last check's result. |
|
||||||
| `_internal:healthActiveConditions`, `_internal:automationActiveConditions` | JSON: the problems currently active, so each is announced once and again when it clears, and survives a restart. |
|
| `_internal:healthActiveConditions`, `_internal:automationActiveConditions` | JSON: the problems currently active, so each is announced once and again when it clears, and survives a restart. |
|
||||||
|
|
||||||
## What happens on delete
|
## What happens on delete
|
||||||
@@ -464,6 +486,7 @@ settings, and aren't part of the app's settings object:
|
|||||||
| a **server** | Its `scheduled_tasks`, `server_links` and `server_ports` are deleted with it. Port forwards that pointed at it stay, with `server_id` cleared. |
|
| a **server** | Its `scheduled_tasks`, `server_links` and `server_ports` are deleted with it. Port forwards that pointed at it stay, with `server_id` cleared. |
|
||||||
| a **DNS provider** | Its cached zones and records are deleted. |
|
| a **DNS provider** | Its cached zones and records are deleted. |
|
||||||
| an **integration** or **DNS provider** | The credential row it used is deleted by the app (not by the database). |
|
| an **integration** or **DNS provider** | The credential row it used is deleted by the app (not by the database). |
|
||||||
|
| an **integration** used for alert tickets | `alert_tickets.integration_id` is cleared; the history stays. |
|
||||||
| an **integration credential** | The integration / provider using it keeps existing, with `credential_id` cleared. |
|
| an **integration credential** | The integration / provider using it keeps existing, with `credential_id` cleared. |
|
||||||
| a **user** | Their audit entries stay; `actor_user_id` is cleared and `actor_label` keeps the name. |
|
| a **user** | Their audit entries stay; `actor_user_id` is cleared and `actor_label` keeps the name. |
|
||||||
| a **Proxmox integration** that servers are linked to | Those servers keep existing and lose their Proxmox link (all four `proxmox_*` columns). The app does this before deleting; the database alone would refuse — see the next section. |
|
| a **Proxmox integration** that servers are linked to | Those servers keep existing and lose their Proxmox link (all four `proxmox_*` columns). The app does this before deleting; the database alone would refuse — see the next section. |
|
||||||
|
|||||||
+21
-2
@@ -116,8 +116,8 @@ the dashboard views themselves load fine.
|
|||||||
reading osTicket's own MySQL/MariaDB database directly, the same way osTicket's own admin panel does internally.
|
reading osTicket's own MySQL/MariaDB database directly, the same way osTicket's own admin panel does internally.
|
||||||
This makes it the only integration in this app that isn't a REST API.
|
This makes it the only integration in this app that isn't a REST API.
|
||||||
- **Actions used:** read-only — a single `SELECT` joining the ticket, status, priority, department, staff, team,
|
- **Actions used:** read-only — a single `SELECT` joining the ticket, status, priority, department, staff, team,
|
||||||
and requester tables for every ticket whose status is in the "open" state. Nothing here can create, update, or
|
and requester tables for every ticket whose status is in the "open" state. Nothing in this part can create,
|
||||||
close a ticket.
|
update, or close a ticket — opening tickets is the separate, optional API described below.
|
||||||
- **Required access:** a MySQL/MariaDB user with **read-only (`SELECT`) access to the osTicket database only** —
|
- **Required access:** a MySQL/MariaDB user with **read-only (`SELECT`) access to the osTicket database only** —
|
||||||
never reuse osTicket's own application database user, which has full read/write access. Create one with
|
never reuse osTicket's own application database user, which has full read/write access. Create one with
|
||||||
something like:
|
something like:
|
||||||
@@ -148,6 +148,25 @@ the dashboard views themselves load fine.
|
|||||||
a field looks wrong, tell us what happened and we'll adjust — this one has had less real-world exposure than
|
a field looks wrong, tell us what happened and we'll adjust — this one has had less real-world exposure than
|
||||||
every other integration listed here.
|
every other integration listed here.
|
||||||
|
|
||||||
|
**Optional: opening tickets for alerts** (Settings → Alert tickets)
|
||||||
|
|
||||||
|
- **Config fields:** Ticket API address (optional), Ticket API key (optional, stored encrypted like the database
|
||||||
|
password), Allow self-signed certificate (ticket API). Leave them empty and the integration works as before.
|
||||||
|
- **Auth:** osTicket's own HTTP API: `POST <address>/api/tickets.json` with the key in an `X-API-Key` header.
|
||||||
|
- **Make the key in osTicket:** Admin Panel → Manage → API Keys → Add. Tie it to the IP address osTicket sees this
|
||||||
|
app's requests come from (behind Docker or a reverse proxy that is the host's or proxy's address, not the
|
||||||
|
container's — check osTicket's log if it refuses) and tick **Can create tickets**. osTicket refuses a key from any
|
||||||
|
other address, which is the most common reason a test ticket fails.
|
||||||
|
- **What is sent:** one ticket per problem — name and email you set under Settings → Alert tickets, a subject, the
|
||||||
|
problem's text and a link back to this app, optionally a help topic and priority id — with `autorespond` off (the
|
||||||
|
"user" is this app, so an acknowledgement would only bounce) and osTicket's own staff alert on or off as you choose.
|
||||||
|
- **What it can't do:** close, reopen, or comment on a ticket — osTicket's API has no such endpoint. A ticket opened
|
||||||
|
here is yours to close in osTicket.
|
||||||
|
- **Not verified against a real osTicket** — built from osTicket's published API documentation and tested against a
|
||||||
|
stand-in server that checks what is sent (the key header, the JSON fields, the message encoding, and how each
|
||||||
|
answer — created, refused key, bad request, redirect — is handled). If osTicket rejects a ticket, "Send a test
|
||||||
|
ticket" shows the reason it gave.
|
||||||
|
|
||||||
### phpIPAM
|
### phpIPAM
|
||||||
|
|
||||||
- **Config fields:** phpIPAM URL, API app ID, App token
|
- **Config fields:** phpIPAM URL, API app ID, App token
|
||||||
|
|||||||
+28
-4
@@ -101,16 +101,40 @@ in three ways:
|
|||||||
failing its last few calls (before the threshold that triggers an "integration down" notification).
|
failing its last few calls (before the threshold that triggers an "integration down" notification).
|
||||||
|
|
||||||
It runs the checks live when opened (a recent result is reused for a minute), and shows what it couldn't read at the top, so a missing section means
|
It runs the checks live when opened (a recent result is reused for a minute), and shows what it couldn't read at the top, so a missing section means
|
||||||
"couldn't check" and not "all clear".
|
"couldn't check" and not "all clear". An alert that has an osTicket ticket (see the next section) shows its ticket number.
|
||||||
|
|
||||||
|
## Tickets in osTicket
|
||||||
|
|
||||||
|
Not a notification, but it acts on the same alerts: with **Settings → Alert tickets** switched on (off by default), a problem on the Alerts page opens a
|
||||||
|
ticket in osTicket. It runs every 15 minutes, starting about a minute and a half after the app starts.
|
||||||
|
|
||||||
|
| Rule | What it means |
|
||||||
|
|---|---|
|
||||||
|
| Which problems | The severities and kinds you choose — **critical and warning, every kind** by default. Info (updates waiting and the like) is off. |
|
||||||
|
| Must last | A problem must be there in **2 checks in a row** (15–30 minutes) before it opens a ticket, so a blip that fixes itself — one failed call to an integration, a monitor that flickers — never does. Can be set from 1 (at once) to 4. |
|
||||||
|
| One ticket per problem | However many checks see it, once. After a ticket is open, the problem isn't ticketed again while it lasts — even if someone closes the ticket in osTicket. |
|
||||||
|
| Comes back | A problem that clears and returns **within 60 minutes** is the same problem (no new ticket). After longer, it is a new one and gets a new ticket. |
|
||||||
|
| Many at once | **More than 5 new problems in one check** become a single summary ticket listing them all, so one outage doesn't fill the queue. Up to 5 get a ticket each. |
|
||||||
|
| Maintenance windows | A problem under one never opens a ticket. If it is still there after the window ends, it does. |
|
||||||
|
| Never about osTicket | Overdue tickets, and osTicket's own calls failing, never open a ticket — it would go to the thing that is down, or add to the pile. |
|
||||||
|
| Already there at switch-on | **Left alone by default**: the first check after switching on records what is wrong as the starting line, and only problems that start after it get a ticket. Can be set to ticket those too. Switching it off and on again starts a new line. |
|
||||||
|
| If osTicket can't be reached | Nothing is recorded as opened; the next check tries again. A refused key, a wrong address and similar are shown on the settings page and in the Diagnostic Log. |
|
||||||
|
| If something can't be read | When a check couldn't read everything (an integration was down), nothing is treated as gone, so a problem isn't called cleared just because its source couldn't be looked at. |
|
||||||
|
|
||||||
|
The ticket says what is wrong, the severity, the kind, where it comes from, when it was first seen, and links back to the problem in this app. osTicket's
|
||||||
|
API can't update or close a ticket, so it isn't touched again: close it in osTicket when the problem is dealt with. Every ticket opened (and every test
|
||||||
|
ticket) is in the Audit Log as `alert_ticket`, and changes to the settings as `settings` / `update_alert_tickets`. "Send a test ticket" and "Check now"
|
||||||
|
on the settings page use the saved settings.
|
||||||
|
|
||||||
## What does *not* send a notification
|
## What does *not* send a notification
|
||||||
|
|
||||||
Worth calling out explicitly, since it's easy to assume everything in
|
Worth calling out explicitly, since it's easy to assume everything in
|
||||||
the app alerts on something:
|
the app alerts on something:
|
||||||
|
|
||||||
- **osTicket** — the integration lists open tickets, but there is no
|
- **osTicket's own tickets** — the integration lists open tickets, but
|
||||||
scheduled check or alert wired up for it (e.g. nothing pings you about
|
there is no notification for it (e.g. nothing pings you about a
|
||||||
a newly-overdue ticket). It's a read-only dashboard/page today.
|
newly-overdue ticket); the page and the Alerts page show them. (The
|
||||||
|
other direction — an alert opening a ticket — is the section above.)
|
||||||
- **phpIPAM sync**, **Uptime Kuma monitor/maintenance import**, and any
|
- **phpIPAM sync**, **Uptime Kuma monitor/maintenance import**, and any
|
||||||
other manual "Sync from X" action — these run when you click the
|
other manual "Sync from X" action — these run when you click the
|
||||||
button and report their result on the page itself, not via a
|
button and report their result on the page itself, not via a
|
||||||
|
|||||||
@@ -308,6 +308,14 @@ It checks live (a recent result is reused for a minute; "Check now" forces a
|
|||||||
fresh one), and anything it couldn't read is called out at the top rather than
|
fresh one), and anything it couldn't read is called out at the top rather than
|
||||||
quietly treated as fine.
|
quietly treated as fine.
|
||||||
|
|
||||||
|
**Alert tickets** (Settings → Alert tickets, admin only) opens a ticket in osTicket for an alert, through osTicket's own API. Every 15 minutes the
|
||||||
|
problems on the Alerts page are looked at, and one that is new and has lasted two checks in a row gets one ticket — never a second for the same problem,
|
||||||
|
and never one for something under a maintenance window or about osTicket itself. You choose which severities and kinds count (critical and warning by
|
||||||
|
default), and the Alerts page shows the ticket number on each alert that has one. If many problems appear at once — a network drop that makes thirty
|
||||||
|
things look down — they become one summary ticket instead of thirty. Problems already there when you switch it on are left alone unless you ask for
|
||||||
|
tickets for them too. osTicket's API can't close or update a ticket, so once it's open it's yours to close. It needs an API key made in osTicket (tied to
|
||||||
|
this server's IP address, allowed to create tickets), entered on the osTicket integration; "Send a test ticket" checks the whole chain.
|
||||||
|
|
||||||
**Maintenance mode** silences alerts about one server, integration, or DNS
|
**Maintenance mode** silences alerts about one server, integration, or DNS
|
||||||
provider while you work on it (server offline / disk, storage and Synology
|
provider while you work on it (server offline / disk, storage and Synology
|
||||||
health, Proxmox backup alerts, Proxmox Backup Server verification alerts, and
|
health, Proxmox backup alerts, Proxmox Backup Server verification alerts, and
|
||||||
|
|||||||
@@ -82,6 +82,10 @@ even further, to admin only:
|
|||||||
- **Generator**: everyone can use it; the name lists it picks server names from
|
- **Generator**: everyone can use it; the name lists it picks server names from
|
||||||
are edited under Settings → Names, which is admin-only (and so is importing
|
are edited under Settings → Names, which is admin-only (and so is importing
|
||||||
names from Skatteverket).
|
names from Skatteverket).
|
||||||
|
- **Alert tickets**: everyone sees which alerts have an osTicket ticket (a
|
||||||
|
badge on the Alerts page, linking to the ticket in osTicket); switching the
|
||||||
|
feature on, choosing what opens a ticket, and sending a test ticket are
|
||||||
|
under Settings → Alert tickets, which is admin-only.
|
||||||
- Everything under **Settings** (notification channels, badge colors,
|
- Everything under **Settings** (notification channels, badge colors,
|
||||||
display prefs, log retention, backup/restore) is admin-only, matching
|
display prefs, log retention, backup/restore) is admin-only, matching
|
||||||
the page itself being admin-only.
|
the page itself being admin-only.
|
||||||
|
|||||||
@@ -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
@@ -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
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
@@ -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
@@ -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)],
|
||||||
|
);
|
||||||
@@ -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}`);
|
||||||
|
|||||||
@@ -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 });
|
||||||
|
}
|
||||||
@@ -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() });
|
||||||
|
}));
|
||||||
@@ -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)`);
|
||||||
|
}
|
||||||
@@ -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",
|
||||||
|
};
|
||||||
|
}
|
||||||
@@ -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)[];
|
||||||
|
|||||||
@@ -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));
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -39,6 +39,7 @@ import CacheSettings from "./pages/settings/CacheSettings";
|
|||||||
import LogSettings from "./pages/settings/LogSettings";
|
import LogSettings from "./pages/settings/LogSettings";
|
||||||
import BackupSettings from "./pages/settings/BackupSettings";
|
import BackupSettings from "./pages/settings/BackupSettings";
|
||||||
import NameSettings from "./pages/settings/NameSettings";
|
import NameSettings from "./pages/settings/NameSettings";
|
||||||
|
import AlertTicketSettings from "./pages/settings/AlertTicketSettings";
|
||||||
import AppShell from "./layout/AppShell";
|
import AppShell from "./layout/AppShell";
|
||||||
import DialogHost from "./components/DialogHost";
|
import DialogHost from "./components/DialogHost";
|
||||||
import { setDateTimeSettings } from "./utils/date";
|
import { setDateTimeSettings } from "./utils/date";
|
||||||
@@ -163,6 +164,7 @@ export default function App() {
|
|||||||
<Route path="display" element={<DisplaySettings />} />
|
<Route path="display" element={<DisplaySettings />} />
|
||||||
<Route path="tags" element={<TagSettings />} />
|
<Route path="tags" element={<TagSettings />} />
|
||||||
<Route path="names" element={<NameSettings />} />
|
<Route path="names" element={<NameSettings />} />
|
||||||
|
<Route path="alert-tickets" element={<AlertTicketSettings />} />
|
||||||
<Route path="cache" element={<CacheSettings />} />
|
<Route path="cache" element={<CacheSettings />} />
|
||||||
<Route path="logs" element={<LogSettings />} />
|
<Route path="logs" element={<LogSettings />} />
|
||||||
<Route path="backup" element={<BackupSettings />} />
|
<Route path="backup" element={<BackupSettings />} />
|
||||||
|
|||||||
@@ -409,6 +409,45 @@ export interface AlertItem {
|
|||||||
link: string | null;
|
link: string | null;
|
||||||
/** Under a maintenance window: still a real problem, but its notifications are held back. */
|
/** Under a maintenance window: still a real problem, but its notifications are held back. */
|
||||||
silenced: boolean;
|
silenced: boolean;
|
||||||
|
/** The osTicket ticket opened for it, if one was. */
|
||||||
|
ticket?: { number: string | null; url: string | null; grouped: boolean; openedAt: string | null } | null;
|
||||||
|
}
|
||||||
|
|
||||||
|
export type AlertTicketSeverity = "critical" | "warning" | "info";
|
||||||
|
|
||||||
|
export interface AlertTicketSettings {
|
||||||
|
enabled: boolean;
|
||||||
|
integrationId: number | null;
|
||||||
|
severities: AlertTicketSeverity[];
|
||||||
|
categories: string[];
|
||||||
|
requesterName: string;
|
||||||
|
requesterEmail: string;
|
||||||
|
topicId: number | null;
|
||||||
|
priorityId: number | null;
|
||||||
|
notifyStaff: boolean;
|
||||||
|
existingProblems: "ignore" | "ticket";
|
||||||
|
confirmChecks: number;
|
||||||
|
summaryAbove: number;
|
||||||
|
reopenAfterMinutes: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface AlertTicketRunSummary {
|
||||||
|
at: string;
|
||||||
|
skipped?: "disabled" | "busy";
|
||||||
|
error?: string;
|
||||||
|
ticketsOpened: number;
|
||||||
|
alertsCovered: number;
|
||||||
|
baseline: number;
|
||||||
|
pending: number;
|
||||||
|
cleared: number;
|
||||||
|
failed: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface AlertTicketOverview {
|
||||||
|
settings: AlertTicketSettings;
|
||||||
|
integrations: { id: number; name: string; enabled: boolean; ticketApiReady: boolean }[];
|
||||||
|
categories: { value: string; label: string }[];
|
||||||
|
status: { lastRun: AlertTicketRunSummary | null; open: number; pending: number; baseline: number; baselinePending: boolean };
|
||||||
}
|
}
|
||||||
|
|
||||||
export interface AlertsReport {
|
export interface AlertsReport {
|
||||||
@@ -1062,6 +1101,12 @@ export const api = {
|
|||||||
alerts: {
|
alerts: {
|
||||||
list: (refresh = false) => request<AlertsReport>(`/api/alerts${refresh ? "?refresh=1" : ""}`),
|
list: (refresh = false) => request<AlertsReport>(`/api/alerts${refresh ? "?refresh=1" : ""}`),
|
||||||
},
|
},
|
||||||
|
alertTickets: {
|
||||||
|
get: () => request<AlertTicketOverview>("/api/alert-tickets"),
|
||||||
|
update: (patch: Partial<AlertTicketSettings>) => request<AlertTicketOverview>("/api/alert-tickets", { method: "PUT", body: JSON.stringify(patch) }),
|
||||||
|
test: () => request<{ ok: boolean; ticketNumber: string | null }>("/api/alert-tickets/test", { method: "POST" }),
|
||||||
|
run: () => request<{ summary: AlertTicketRunSummary; status: AlertTicketOverview["status"] }>("/api/alert-tickets/run", { method: "POST" }),
|
||||||
|
},
|
||||||
ports: {
|
ports: {
|
||||||
agent: () => request<AgentPortsResponse>("/api/ports/agent"),
|
agent: () => request<AgentPortsResponse>("/api/ports/agent"),
|
||||||
forwards: {
|
forwards: {
|
||||||
|
|||||||
@@ -73,8 +73,8 @@ export default function Alerts(_props: { user: CurrentUser }) {
|
|||||||
function exportCsv() {
|
function exportCsv() {
|
||||||
downloadCsv(
|
downloadCsv(
|
||||||
"alerts.csv",
|
"alerts.csv",
|
||||||
["Severity", "Category", "Source", "Alert", "Silenced"],
|
["Severity", "Category", "Source", "Alert", "Silenced", "Ticket"],
|
||||||
(sorted ?? []).map((a) => [SEVERITY[a.severity].label, CATEGORY_LABELS[a.category], a.source, a.message, a.silenced ? "yes" : "no"]),
|
(sorted ?? []).map((a) => [SEVERITY[a.severity].label, CATEGORY_LABELS[a.category], a.source, a.message, a.silenced ? "yes" : "no", a.ticket ? (a.ticket.number ?? "opened") : ""]),
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -222,6 +222,20 @@ export default function Alerts(_props: { user: CurrentUser }) {
|
|||||||
silenced
|
silenced
|
||||||
</span>
|
</span>
|
||||||
)}
|
)}
|
||||||
|
{a.ticket &&
|
||||||
|
(() => {
|
||||||
|
const label = a.ticket.number ? `Ticket #${a.ticket.number}` : "Ticket opened";
|
||||||
|
const title = a.ticket.grouped ? "Part of one ticket that covers several problems that appeared together" : "A ticket was opened for this in osTicket";
|
||||||
|
return a.ticket.url ? (
|
||||||
|
<a className="badge bg-blue-lt text-blue ms-2" href={a.ticket.url} target="_blank" rel="noopener noreferrer" title={title}>
|
||||||
|
{label}
|
||||||
|
</a>
|
||||||
|
) : (
|
||||||
|
<span className="badge bg-blue-lt text-blue ms-2" title={title}>
|
||||||
|
{label}
|
||||||
|
</span>
|
||||||
|
);
|
||||||
|
})()}
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
))}
|
))}
|
||||||
|
|||||||
@@ -226,6 +226,10 @@ export default function Privacy() {
|
|||||||
{outbound && outbound.integrationTypes.length > 0 ? ` (${outbound.integrationTypes.join(", ")})` : ""} — API calls to systems
|
{outbound && outbound.integrationTypes.length > 0 ? ` (${outbound.integrationTypes.join(", ")})` : ""} — API calls to systems
|
||||||
you configured, to read status and, when someone with permission asks, to act (start a VM, run a template…).
|
you configured, to read status and, when someone with permission asks, to act (start a VM, run a template…).
|
||||||
</li>
|
</li>
|
||||||
|
<li className="mb-2">
|
||||||
|
<strong>osTicket tickets</strong> — only if an admin has switched on Settings → Alert tickets: for a problem that has lasted, the text of the alert
|
||||||
|
(which server or integration, what is wrong), a link back to this app, and the requester name and email set there go to your osTicket's API.
|
||||||
|
</li>
|
||||||
<li className="mb-2">
|
<li className="mb-2">
|
||||||
<strong>DNS providers</strong>
|
<strong>DNS providers</strong>
|
||||||
{outbound && outbound.dnsProviderTypes.length > 0 ? ` (${outbound.dnsProviderTypes.join(", ")})` : ""} — zones and records are read
|
{outbound && outbound.dnsProviderTypes.length > 0 ? ` (${outbound.dnsProviderTypes.join(", ")})` : ""} — zones and records are read
|
||||||
|
|||||||
@@ -6,6 +6,7 @@ const SUB_NAV = [
|
|||||||
{ to: "/settings/badges", label: "Badges" },
|
{ to: "/settings/badges", label: "Badges" },
|
||||||
{ to: "/settings/display", label: "Display" },
|
{ to: "/settings/display", label: "Display" },
|
||||||
{ to: "/settings/tags", label: "Tags" },
|
{ to: "/settings/tags", label: "Tags" },
|
||||||
|
{ to: "/settings/alert-tickets", label: "Alert tickets" },
|
||||||
{ to: "/settings/names", label: "Names" },
|
{ to: "/settings/names", label: "Names" },
|
||||||
{ to: "/settings/cache", label: "Cache" },
|
{ to: "/settings/cache", label: "Cache" },
|
||||||
{ to: "/settings/logs", label: "Logs" },
|
{ to: "/settings/logs", label: "Logs" },
|
||||||
|
|||||||
@@ -0,0 +1,304 @@
|
|||||||
|
import { useEffect, useMemo, useState } from "react";
|
||||||
|
import { Link } from "react-router-dom";
|
||||||
|
import { api, type AlertTicketOverview, type AlertTicketRunSummary, type AlertTicketSettings as Settings, type AlertTicketSeverity } from "../../api/client";
|
||||||
|
import { formatDateTime } from "../../utils/date";
|
||||||
|
import { formatAgo } from "../../utils/duration";
|
||||||
|
import { readableError } from "../../utils/errors";
|
||||||
|
|
||||||
|
const SEVERITIES: { value: AlertTicketSeverity; label: string; hint: string }[] = [
|
||||||
|
{ value: "critical", label: "Critical", hint: "A server down, a disk nearly full, a failed backup, something expired" },
|
||||||
|
{ value: "warning", label: "Warning", hint: "Something about to expire, an integration failing" },
|
||||||
|
{ value: "info", label: "Info", hint: "Updates waiting, monitors that can't be matched — rarely worth a ticket" },
|
||||||
|
];
|
||||||
|
|
||||||
|
/** Blank means "not set"; anything else must be a whole number. */
|
||||||
|
function optionalNumber(text: string): number | null {
|
||||||
|
const n = Number(text);
|
||||||
|
return text.trim() === "" || !Number.isInteger(n) || n < 1 ? null : n;
|
||||||
|
}
|
||||||
|
|
||||||
|
function describeRun(run: AlertTicketRunSummary): string {
|
||||||
|
if (run.skipped === "disabled") return "Switched off.";
|
||||||
|
if (run.skipped === "busy") return "A check was already running.";
|
||||||
|
const parts = [`${run.ticketsOpened} ticket${run.ticketsOpened === 1 ? "" : "s"} opened${run.ticketsOpened > 0 ? ` for ${run.alertsCovered} alert${run.alertsCovered === 1 ? "" : "s"}` : ""}`];
|
||||||
|
if (run.pending > 0) parts.push(`${run.pending} waiting to last long enough`);
|
||||||
|
if (run.baseline > 0) parts.push(`${run.baseline} already there, left alone`);
|
||||||
|
if (run.cleared > 0) parts.push(`${run.cleared} cleared`);
|
||||||
|
if (run.failed > 0) parts.push(`${run.failed} couldn't be opened`);
|
||||||
|
return `${parts.join(", ")}.`;
|
||||||
|
}
|
||||||
|
|
||||||
|
export default function AlertTicketSettings() {
|
||||||
|
const [overview, setOverview] = useState<AlertTicketOverview | null>(null);
|
||||||
|
const [draft, setDraft] = useState<Settings | null>(null);
|
||||||
|
const [error, setError] = useState<string | null>(null);
|
||||||
|
const [notice, setNotice] = useState<string | null>(null);
|
||||||
|
const [busy, setBusy] = useState<"save" | "test" | "run" | null>(null);
|
||||||
|
|
||||||
|
function show(next: AlertTicketOverview) {
|
||||||
|
setOverview(next);
|
||||||
|
setDraft(next.settings);
|
||||||
|
}
|
||||||
|
|
||||||
|
useEffect(() => {
|
||||||
|
api.alertTickets
|
||||||
|
.get()
|
||||||
|
.then(show)
|
||||||
|
.catch((err) => setError(readableError(err)));
|
||||||
|
}, []);
|
||||||
|
|
||||||
|
const dirty = useMemo(() => overview !== null && draft !== null && JSON.stringify(overview.settings) !== JSON.stringify(draft), [overview, draft]);
|
||||||
|
|
||||||
|
if (!overview || !draft) {
|
||||||
|
return error ? <div className="alert alert-danger">{error}</div> : <div className="text-secondary">Loading…</div>;
|
||||||
|
}
|
||||||
|
|
||||||
|
const set = (patch: Partial<Settings>) => {
|
||||||
|
setDraft({ ...draft, ...patch });
|
||||||
|
setNotice(null);
|
||||||
|
};
|
||||||
|
const toggle = <T extends string>(list: T[], value: T) => (list.includes(value) ? list.filter((v) => v !== value) : [...list, value]);
|
||||||
|
|
||||||
|
async function save() {
|
||||||
|
setBusy("save");
|
||||||
|
setError(null);
|
||||||
|
setNotice(null);
|
||||||
|
try {
|
||||||
|
show(await api.alertTickets.update(draft!));
|
||||||
|
setNotice("Saved.");
|
||||||
|
} catch (err) {
|
||||||
|
setError(readableError(err));
|
||||||
|
} finally {
|
||||||
|
setBusy(null);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async function sendTest() {
|
||||||
|
setBusy("test");
|
||||||
|
setError(null);
|
||||||
|
setNotice(null);
|
||||||
|
try {
|
||||||
|
const res = await api.alertTickets.test();
|
||||||
|
setNotice(`A test ticket was opened in osTicket${res.ticketNumber ? ` (#${res.ticketNumber})` : ""}. You can close it there.`);
|
||||||
|
} catch (err) {
|
||||||
|
setError(readableError(err));
|
||||||
|
} finally {
|
||||||
|
setBusy(null);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async function checkNow() {
|
||||||
|
setBusy("run");
|
||||||
|
setError(null);
|
||||||
|
setNotice(null);
|
||||||
|
try {
|
||||||
|
const res = await api.alertTickets.run();
|
||||||
|
setOverview({ ...overview!, status: res.status });
|
||||||
|
if (res.summary.error) setError(res.summary.error);
|
||||||
|
setNotice(describeRun(res.summary));
|
||||||
|
} catch (err) {
|
||||||
|
setError(readableError(err));
|
||||||
|
} finally {
|
||||||
|
setBusy(null);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const chosen = overview.integrations.find((i) => i.id === draft.integrationId);
|
||||||
|
const { status } = overview;
|
||||||
|
|
||||||
|
return (
|
||||||
|
<>
|
||||||
|
{error && <div className="alert alert-danger">{error}</div>}
|
||||||
|
{notice && <div className="alert alert-success">{notice}</div>}
|
||||||
|
|
||||||
|
<div className="card mb-3">
|
||||||
|
<div className="card-header">
|
||||||
|
<h3 className="card-title">Open a ticket in osTicket when something goes wrong</h3>
|
||||||
|
<div className="card-actions">
|
||||||
|
<label className="form-check form-switch mb-0">
|
||||||
|
<input type="checkbox" className="form-check-input" checked={draft.enabled} onChange={(e) => set({ enabled: e.target.checked })} />
|
||||||
|
<span className="form-check-label">{draft.enabled ? "On" : "Off"}</span>
|
||||||
|
</label>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div className="card-body">
|
||||||
|
<p className="text-secondary">
|
||||||
|
Every 15 minutes the problems on the <Link to="/alerts">Alerts page</Link> are checked, and one that is new and has lasted gets a ticket. One problem opens
|
||||||
|
one ticket, however many checks see it. Problems under a <Link to="/maintenance">maintenance window</Link> never do. osTicket's API can't close or update a
|
||||||
|
ticket, so the ticket is yours from then on: close it in osTicket when it is dealt with. The Alerts page shows which alerts have one.
|
||||||
|
</p>
|
||||||
|
<div className="alert alert-info">
|
||||||
|
<div>
|
||||||
|
<strong>Set this up in osTicket first.</strong> Under <em>Admin Panel → Manage → API Keys</em> add a key, tie it to this server's IP address (the one osTicket
|
||||||
|
sees requests come from), and tick <em>Can create tickets</em>. Then enter the address and the key on the osTicket integration under{" "}
|
||||||
|
<Link to="/integrations">Integrations</Link>.
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div className="row g-3">
|
||||||
|
<div className="col-md-6">
|
||||||
|
<label className="form-label">osTicket integration</label>
|
||||||
|
<select className="form-select" value={draft.integrationId ?? ""} onChange={(e) => set({ integrationId: e.target.value === "" ? null : Number(e.target.value) })}>
|
||||||
|
<option value="">Choose…</option>
|
||||||
|
{overview.integrations.map((i) => (
|
||||||
|
<option key={i.id} value={i.id} disabled={!i.ticketApiReady}>
|
||||||
|
{i.name}
|
||||||
|
{!i.ticketApiReady ? " — no ticket API address and key yet" : ""}
|
||||||
|
</option>
|
||||||
|
))}
|
||||||
|
</select>
|
||||||
|
{overview.integrations.length === 0 && <div className="form-hint text-warning">There is no osTicket integration yet. Add one under Integrations.</div>}
|
||||||
|
{chosen && !chosen.enabled && <div className="form-hint text-warning">That integration is switched off.</div>}
|
||||||
|
</div>
|
||||||
|
<div className="col-md-6 d-flex align-items-end">
|
||||||
|
<button className="btn btn-outline-secondary" onClick={() => void sendTest()} disabled={busy !== null || dirty || !overview.settings.integrationId} title={dirty ? "Save first — the test uses the saved settings" : undefined}>
|
||||||
|
{busy === "test" ? "Sending…" : "Send a test ticket"}
|
||||||
|
</button>
|
||||||
|
</div>
|
||||||
|
<div className="col-md-4">
|
||||||
|
<label className="form-label">Tickets come from (name)</label>
|
||||||
|
<input className="form-control" maxLength={100} value={draft.requesterName} onChange={(e) => set({ requesterName: e.target.value })} />
|
||||||
|
</div>
|
||||||
|
<div className="col-md-4">
|
||||||
|
<label className="form-label">…and this email</label>
|
||||||
|
<input className="form-control" type="email" maxLength={200} placeholder="homelab@example.com" value={draft.requesterEmail} onChange={(e) => set({ requesterEmail: e.target.value })} />
|
||||||
|
<div className="form-hint">osTicket needs one for every ticket. Replies from staff would go here.</div>
|
||||||
|
</div>
|
||||||
|
<div className="col-md-2">
|
||||||
|
<label className="form-label">Help topic id</label>
|
||||||
|
<input className="form-control" inputMode="numeric" placeholder="default" value={draft.topicId ?? ""} onChange={(e) => set({ topicId: optionalNumber(e.target.value) })} />
|
||||||
|
</div>
|
||||||
|
<div className="col-md-2">
|
||||||
|
<label className="form-label">Priority id</label>
|
||||||
|
<input className="form-control" inputMode="numeric" placeholder="default" value={draft.priorityId ?? ""} onChange={(e) => set({ priorityId: optionalNumber(e.target.value) })} />
|
||||||
|
</div>
|
||||||
|
<div className="col-12">
|
||||||
|
<label className="form-check mb-0">
|
||||||
|
<input type="checkbox" className="form-check-input" checked={draft.notifyStaff} onChange={(e) => set({ notifyStaff: e.target.checked })} />
|
||||||
|
<span className="form-check-label">Let osTicket send its own "new ticket" alert to staff (as set up in osTicket)</span>
|
||||||
|
</label>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div className="card mb-3">
|
||||||
|
<div className="card-header">
|
||||||
|
<h3 className="card-title">Which problems</h3>
|
||||||
|
</div>
|
||||||
|
<div className="card-body">
|
||||||
|
<div className="row g-4">
|
||||||
|
<div className="col-md-6">
|
||||||
|
<div className="form-label">Severity</div>
|
||||||
|
{SEVERITIES.map((s) => (
|
||||||
|
<label className="form-check" key={s.value}>
|
||||||
|
<input type="checkbox" className="form-check-input" checked={draft.severities.includes(s.value)} onChange={() => set({ severities: toggle(draft.severities, s.value) })} />
|
||||||
|
<span className="form-check-label">
|
||||||
|
{s.label} <span className="text-secondary small">— {s.hint}</span>
|
||||||
|
</span>
|
||||||
|
</label>
|
||||||
|
))}
|
||||||
|
</div>
|
||||||
|
<div className="col-md-6">
|
||||||
|
<div className="form-label">Kind</div>
|
||||||
|
<label className="form-check">
|
||||||
|
<input type="checkbox" className="form-check-input" checked={draft.categories.length === 0} onChange={(e) => set({ categories: e.target.checked ? [] : overview.categories.map((c) => c.value) })} />
|
||||||
|
<span className="form-check-label">All kinds</span>
|
||||||
|
</label>
|
||||||
|
{draft.categories.length > 0 && (
|
||||||
|
<div className="ms-3">
|
||||||
|
{overview.categories.map((c) => (
|
||||||
|
<label className="form-check mb-1" key={c.value}>
|
||||||
|
<input type="checkbox" className="form-check-input" checked={draft.categories.includes(c.value)} onChange={() => set({ categories: toggle(draft.categories, c.value) })} />
|
||||||
|
<span className="form-check-label">{c.label}</span>
|
||||||
|
</label>
|
||||||
|
))}
|
||||||
|
</div>
|
||||||
|
)}
|
||||||
|
<div className="form-hint">Problems with osTicket itself never open a ticket — it would go to the thing that is down.</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div className="col-md-4">
|
||||||
|
<label className="form-label">Must last</label>
|
||||||
|
<select className="form-select" value={draft.confirmChecks} onChange={(e) => set({ confirmChecks: Number(e.target.value) })}>
|
||||||
|
<option value={1}>Open a ticket straight away</option>
|
||||||
|
<option value={2}>2 checks in a row (15–30 minutes)</option>
|
||||||
|
<option value={3}>3 checks in a row (30–45 minutes)</option>
|
||||||
|
<option value={4}>4 checks in a row (about an hour)</option>
|
||||||
|
</select>
|
||||||
|
<div className="form-hint">So a blip that fixes itself, like one failed call to an integration, never opens a ticket.</div>
|
||||||
|
</div>
|
||||||
|
<div className="col-md-4">
|
||||||
|
<label className="form-label">Many at once</label>
|
||||||
|
<div className="input-group">
|
||||||
|
<span className="input-group-text">More than</span>
|
||||||
|
<input className="form-control" type="number" min={1} max={50} value={draft.summaryAbove} onChange={(e) => set({ summaryAbove: Math.min(50, Math.max(1, Number(e.target.value) || 1)) })} />
|
||||||
|
<span className="input-group-text">new</span>
|
||||||
|
</div>
|
||||||
|
<div className="form-hint">…in one check become a single ticket listing them all, so one outage doesn't fill the queue.</div>
|
||||||
|
</div>
|
||||||
|
<div className="col-md-4">
|
||||||
|
<label className="form-label">Comes back within</label>
|
||||||
|
<div className="input-group">
|
||||||
|
<input className="form-control" type="number" min={0} max={1440} value={draft.reopenAfterMinutes} onChange={(e) => set({ reopenAfterMinutes: Math.min(1440, Math.max(0, Number(e.target.value) || 0)) })} />
|
||||||
|
<span className="input-group-text">minutes</span>
|
||||||
|
</div>
|
||||||
|
<div className="form-hint">A problem that clears and returns this fast is the same one, not a new ticket. After that, it is.</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div className="col-12">
|
||||||
|
<div className="form-label">Problems already there when this is switched on</div>
|
||||||
|
<label className="form-check">
|
||||||
|
<input type="radio" className="form-check-input" name="existing" checked={draft.existingProblems === "ignore"} onChange={() => set({ existingProblems: "ignore" })} />
|
||||||
|
<span className="form-check-label">
|
||||||
|
Leave them alone <span className="text-secondary small">— only problems that start after this is switched on get a ticket. Recommended.</span>
|
||||||
|
</span>
|
||||||
|
</label>
|
||||||
|
<label className="form-check">
|
||||||
|
<input type="radio" className="form-check-input" name="existing" checked={draft.existingProblems === "ticket"} onChange={() => set({ existingProblems: "ticket" })} />
|
||||||
|
<span className="form-check-label">
|
||||||
|
Open tickets for them too <span className="text-secondary small">— several at once become one summary ticket.</span>
|
||||||
|
</span>
|
||||||
|
</label>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div className="card mb-3">
|
||||||
|
<div className="card-header">
|
||||||
|
<h3 className="card-title">What it has done</h3>
|
||||||
|
<div className="card-actions">
|
||||||
|
<button className="btn btn-outline-secondary btn-sm" onClick={() => void checkNow()} disabled={busy !== null || dirty || !overview.settings.enabled} title={dirty ? "Save first — the check uses the saved settings" : !overview.settings.enabled ? "Switched off" : undefined}>
|
||||||
|
{busy === "run" ? "Checking…" : "Check now"}
|
||||||
|
</button>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div className="card-body">
|
||||||
|
{status.lastRun ? (
|
||||||
|
<div className="mb-2">
|
||||||
|
<span title={formatDateTime(new Date(status.lastRun.at))}>Last check {formatAgo(status.lastRun.at)}</span>: {describeRun(status.lastRun)}
|
||||||
|
{status.lastRun.error && <div className="text-danger small mt-1">{status.lastRun.error}</div>}
|
||||||
|
</div>
|
||||||
|
) : (
|
||||||
|
<div className="text-secondary mb-2">No check has run yet.</div>
|
||||||
|
)}
|
||||||
|
<div className="text-secondary small">
|
||||||
|
Right now: {status.open} problem{status.open === 1 ? "" : "s"} with a ticket, {status.pending} waiting to last long enough, {status.baseline} already there and left alone.
|
||||||
|
{status.baselinePending && " The next check records what is wrong at that point as the starting line, without opening tickets for it."}
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div className="d-flex flex-wrap align-items-center gap-2">
|
||||||
|
<button className="btn btn-primary" onClick={() => void save()} disabled={busy !== null || !dirty}>
|
||||||
|
{busy === "save" ? "Saving…" : "Save changes"}
|
||||||
|
</button>
|
||||||
|
<button className="btn btn-outline-secondary" onClick={() => { setDraft(overview.settings); setError(null); setNotice(null); }} disabled={busy !== null || !dirty}>
|
||||||
|
Discard changes
|
||||||
|
</button>
|
||||||
|
{dirty && <span className="text-secondary small">You have unsaved changes.</span>}
|
||||||
|
</div>
|
||||||
|
</>
|
||||||
|
);
|
||||||
|
}
|
||||||
Reference in new issue
Block a user