A year of history, one chart, and a read API with personal tokens

History: server load, memory and disks are also kept as hourly (four months) and
daily (over two years) averages with lowest and highest; endpoint answers as
hourly (four months) beside the daily figures. Charts ask for 24 hours to a year
and are drawn from whichever is fine enough. A disk that two weeks call flat is
looked at again over ninety days for the forecast. Built once from what is kept.

One chart: TimeChart replaces the sparkline and the multi-line chart: hover and
arrow-key readout, a lowest/highest band, gaps shown as gaps, the same ranges
everywhere and the choice remembered. Used for server trends, comparing servers,
a check's availability and answer times (Endpoints > History) and a server's
availability.

Read API: /api/v1 (servers, metrics, alerts, incidents, inventory, network,
endpoints and their history, maintenance) with personal read-only tokens made
under the user menu: shown once, hashed, 30/90/365 days or none, ten at most,
removed with their owner. GET only. Documented in API.md.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-20 20:22:58 +02:00
1 parent 5e26e77340
commit 68b41b5586
47 files changed
+12360 -247

No files matched your search

+46
View File
@@ -3,6 +3,7 @@
Ways for other systems to work with Homelab Manager: Ways for other systems to work with Homelab Manager:
- a read-only **`/metrics`** address for Prometheus, and **event webhooks** that are sent a signed message when something happens — both set up by an administrator under **Settings → API and webhooks** (the first two sections below); - a read-only **`/metrics`** address for Prometheus, and **event webhooks** that are sent a signed message when something happens — both set up by an administrator under **Settings → API and webhooks** (the first two sections below);
- a **read API** (`/api/v1`) with a personal, read-only token for each person, for scripts, Home Assistant and dashboards (the section after `/metrics`);
- **heartbeats**: a cron job or script calls an address when it finishes, and the app speaks up when it doesn't (further down); - **heartbeats**: a cron job or script calls an address when it finishes, and the app speaks up when it doesn't (further down);
- a **calendar feed** of what is coming up, for a phone's calendar to subscribe to (at the end). - a **calendar feed** of what is coming up, for a phone's calendar to subscribe to (at the end).
@@ -85,6 +86,51 @@ All gauges. Labels are escaped as Prometheus requires.
Some alerting ideas: `homelab_server_up == 0`, `homelab_server_disk_used_percent > 90`, Some alerting ideas: `homelab_server_up == 0`, `homelab_server_disk_used_percent > 90`,
`homelab_secret_expiry_days < 14`, `homelab_server_disk_days_to_full < 7`, `homelab_alerts{severity="critical"} > 0`, `time() - homelab_selfbackup_last_success_timestamp_seconds > 2 * 86400`. `homelab_secret_expiry_days < 14`, `homelab_server_disk_days_to_full < 7`, `homelab_alerts{severity="critical"} > 0`, `time() - homelab_selfbackup_last_success_timestamp_seconds > 2 * 86400`.
## The read API — `/api/v1`
JSON about servers, alerts, incidents, inventory, network equipment, endpoint checks and maintenance — for a script, Home Assistant, a dashboard. It only reads.
```
GET /api/v1/alerts
Authorization: Bearer hlm_p_…
```
- **A personal token**, made by whoever is going to use it under the user menu → **API tokens** (everyone signed in can, whatever their role). It is shown once, only its SHA-256 is kept, and it is that person's own: they see
and remove theirs, nobody else's. It can last 30, 90 or 365 days or until removed, a person may have ten, and it stops working at once when removed — and when the person is.
- The token goes in the `Authorization` header **only**. A token in the address is not accepted (addresses end up in logs). No token, a wrong one, an expired one and a removed one all get the same `401` with a JSON body.
- **Only `GET`** (and `HEAD`). Any other verb is `405`, with a token or without: there is nothing here that changes anything.
- A token sees what its owner sees on the pages — no secrets, no settings, no passwords, no tokens of servers. Requests are limited to 300 a minute from one address. Answers are `Cache-Control: no-store`.
- Dates are ISO 8601 in UTC, sizes are bytes, percentages are 0–100. An address inside the app (`url`) is a full address, built from `APP_BASE_URL`.
| Address | What it answers |
|---|---|
| `GET /api/v1` | The list of these addresses. |
| `GET /api/v1/me` | Whose token this is: the person's name and role, and the token's name and end. |
| `GET /api/v1/servers` | Every server: `status` (`online`, `offline`, `unknown`), `lastSeenAt`, `tags`, `ipAddresses`, `cpu`, `memory`, `disks` (with `usedPercent`), `updates`, `hardware`, `url`. Filter with `?tag=` and `?status=`. |
| `GET /api/v1/servers/:id` | One server, the same shape. |
| `GET /api/v1/servers/:id/metrics?days=` | Its load, memory and disks as lines of points, 1 to 365 days (7 by default). Points over more than 35 days are hours' or days' averages, with `lo` and `hi`. Disks also carry a `trend` and, when rising steadily, `daysToFull`. |
| `GET /api/v1/alerts` | What is wrong now: `needingAttention` (critical, warning, acknowledged), `counts`, `couldntCheck`, and `alerts` with `severity`, `category`, `message`, `silenced`, `flapping`, `target`, `causedBy`, `acknowledgement` (who, when, note, until) and `url`. Filter with `?severity=`, `?category=`, `?acknowledged=true|false`, `?silenced=true|false`. |
| `GET /api/v1/incidents?status=&limit=` | The record of alerts that began and ended: `open` or `resolved`, newest first, up to 500 (100 by default). |
| `GET /api/v1/incidents/:id` | One incident with its timeline. |
| `GET /api/v1/inventory` | The hardware: maker, model, serial, where, bought, warranty, end of support, power. |
| `GET /api/v1/network` | Switches, access points and gateways read from UniFi (state, address, uptime, firmware, uplink), the networks and Wi-Fi names, and which server is plugged into which device. |
| `GET /api/v1/endpoints` | The checks: `status` (`up`, `down`, `unknown`, `paused`), last answer, certificate end, 24-hour and 7-day uptime. |
| `GET /api/v1/endpoints/:id/history?days=` | A check's availability and answer times over 1 to 365 days, as points, from each answer (up to 2 days), the hourly figures (up to 120) or the daily ones. |
| `GET /api/v1/maintenance` | What is under maintenance now (`active`) and what is coming (`upcoming`). |
```json
{ "generatedAt": "2026-10-20T09:14:02.511Z",
"needingAttention": { "critical": 1, "warning": 0, "acknowledged": 1 },
"alerts": [
{ "id": "offline:offline:server:3", "severity": "critical", "category": "offline", "source": "Server",
"message": "anna hasn't reported for 9 h", "silenced": false, "flapping": false,
"target": { "type": "server", "id": 3, "name": "anna" }, "causedBy": null, "affects": [],
"acknowledgement": { "by": "Ada", "at": "2026-10-20T08:01:00.000Z", "note": "On it", "until": "2026-10-20T12:01:00.000Z", "assignee": "Ada" },
"url": "https://hm.example.lan/servers/3" } ] }
```
Errors are JSON too: `{ "error": "unauthorized" | "read_only" | "not_found" | "invalid_id", "message": … }`. In Home Assistant, a `rest` sensor with the token in `headers:` and `value_template: "{{ value_json.needingAttention.critical }}"` is enough for a count of what needs attention.
## A Grafana dashboard ## A Grafana dashboard
Settings → API and webhooks → **Download the dashboard** (administrators) gives `homelab-manager-dashboard.json`; the same file is at Settings → API and webhooks → **Download the dashboard** (administrators) gives `homelab-manager-dashboard.json`; the same file is at
+17
View File
@@ -55,6 +55,9 @@ erDiagram
endpoint_checks ||--o{ endpoint_results : "cascade" endpoint_checks ||--o{ endpoint_results : "cascade"
heartbeats ||--o{ heartbeat_pings : "cascade" heartbeats ||--o{ heartbeat_pings : "cascade"
integration_credentials ||--o{ integrations : "credential (set null)" integration_credentials ||--o{ integrations : "credential (set null)"
users ||--o{ api_tokens : "cascade"
servers ||--o{ server_metrics_rollup : "cascade"
endpoint_checks ||--o{ endpoint_hourly : "cascade"
integrations ||--o{ network_devices : "cascade" integrations ||--o{ network_devices : "cascade"
integrations ||--o{ network_segments : "cascade" integrations ||--o{ network_segments : "cascade"
integrations ||--o{ network_server_links : "cascade" integrations ||--o{ network_server_links : "cascade"
@@ -283,6 +286,12 @@ removed whenever a new sample is stored).
| `value` | real NOT NULL | Percent, 0–100, one decimal. | | `value` | real NOT NULL | Percent, 0–100, one decimal. |
| `recorded_at` | text NOT NULL | ISO. | | `recorded_at` | text NOT NULL | ISO. |
#### `server_metrics_rollup`
The same figures kept coarser and longer, so charts reach back a year: one row per server, figure and hour (`grain` `h`, kept 120 days) or day (`d`, kept 800 days). `at` is the start of the hour or day (ISO); `sum` and `n` give the average (and are added to as
samples arrive), `min` and `max` the lowest and highest. Written with each sample (see `server_metrics`); built once from the samples already kept when it was added (internal flag `metricsRollupBackfilled`). Primary key (`server_id`, `metric`, `grain`, `at`); deleted with its server.
A chart over up to 35 days is drawn from the samples, up to 120 from the hours, longer from the days.
Index **`server_metrics_lookup_idx`** on (`server_id`, `metric`, `recorded_at`). Index **`server_metrics_lookup_idx`** on (`server_id`, `metric`, `recorded_at`).
#### `server_ports` #### `server_ports`
@@ -590,6 +599,14 @@ One time a plan ran, and how it went for each server.
One row per endpoint check per UTC day: `total` times asked, `ok` of them answered, `ms_sum`/`ms_count` for the average answer time. Kept about two years (`endpoint_results` keeps two weeks); started from the results that existed when it was added. The monthly report's endpoint availability is worked from it. Primary key (`check_id`, `day`); deleted with its check. One row per endpoint check per UTC day: `total` times asked, `ok` of them answered, `ms_sum`/`ms_count` for the average answer time. Kept about two years (`endpoint_results` keeps two weeks); started from the results that existed when it was added. The monthly report's endpoint availability is worked from it. Primary key (`check_id`, `day`); deleted with its check.
#### `endpoint_hourly`
One row per endpoint check per UTC hour (`hour`, ISO): `total`, `ok`, `ms_sum`, `ms_count` and `ms_max` (the slowest good answer). Kept 120 days — between the results (two weeks) and the daily figures (years) — so an answer-time chart can reach back beyond two weeks. Built once from the results already kept when it was added (internal flag `endpointHourlyBackfilled`). Primary key (`check_id`, `hour`); deleted with its check.
#### `api_tokens`
A person's personal read-only API tokens (see API.md): `user_id` (→ `users.id`, **cascade**: they go with the person), `label`, `token_hash` (SHA-256, unique — the secret itself is shown once and not kept), `token_prefix` (its first twelve characters, to tell tokens apart), `created_at`, `last_used_at` (written at most once a minute) and `expires_at` (null = until removed).
#### `renewals` #### `renewals`
A certificate, domain registration or secret whose expiry moved at least 20 days later when the app re-read it: `kind` (`certificate`, `domain`, `secret`), `subject` (its name as it was), `at`, `from_date`, `to_date`. Written once per renewal; read by the monthly report. A certificate, domain registration or secret whose expiry moved at least 20 days later when the app re-read it: `kind` (`certificate`, `domain`, `secret`), `subject` (its name as it was), `at`, `from_date`, `to_date`. Written once per renewal; read by the monthly report.
+13 -3
View File
@@ -88,8 +88,8 @@ All modules from the original plan are built:
read straight from the host; a QEMU VM's actual mounts via its guest read straight from the host; a QEMU VM's actual mounts via its guest
agent, alongside the allocated size Proxmox already knew about without agent, alongside the allocated size Proxmox already knew about without
one). Servers that report through the agent also get a **Trends** card: small one). Servers that report through the agent also get a **Trends** card: small
lines for CPU load, memory and each disk over the last 24 hours, 7 or 30 days lines for CPU load, memory and each disk over the last 24 hours, 7, 30 or 90 days or a year
(a sample is kept about every ten minutes, for 35 days), and for a disk that is (a sample is kept about every ten minutes, for 35 days; hours and days beyond that, up to a year), and for a disk that is
filling, its rate of growth and roughly how many days until it is full — shown filling, its rate of growth and roughly how many days until it is full — shown
only with at least a day of history. Proxmox-linked servers also get only with at least a day of history. Proxmox-linked servers also get
start/stop/restart buttons right on the detail page. The detail page also has an **Admin Links** section start/stop/restart buttons right on the detail page. The detail page also has an **Admin Links** section
@@ -580,7 +580,7 @@ its expiry is watched either way. A check that has **failed several times in a r
another when it answers again; a certificate within its warning time (14 days by default; critical in the last three) is an *Expiry* alert. A check can be linked to a another when it answers again; a certificate within its warning time (14 days by default; critical in the last three) is an *Expiry* alert. A check can be linked to a
server, so maintenance on it silences the check's alerts and the server's tags can route them. Everyone can look; administrators set checks up (each one makes this server, so maintenance on it silences the check's alerts and the server's tags can route them. Everyone can look; administrators set checks up (each one makes this
server connect somewhere — never to itself or the cloud metadata address, though your own network is fine) and operators can ask *Check now*. They also appear on the server connect somewhere — never to itself or the cloud metadata address, though your own network is fine) and operators can ask *Check now*. They also appear on the
dashboard and in `/metrics`. Results are kept for two weeks. dashboard and in `/metrics`. Results are kept for two weeks, then as hours (four months) and days (years); "History…" on a check draws them.
**Suggested checks** (on the Endpoints page, administrators). From what the app already knows it offers checks you could add with a click: a **web port a server's agent **Suggested checks** (on the Endpoints page, administrators). From what the app already knows it offers checks you could add with a click: a **web port a server's agent
sees open** (80, 443, 8080, 8443 — when a server has both the plain and the secure one, the secure one, since it also reads the certificate), under the name DNS gives that sees open** (80, 443, 8080, 8443 — when a server has both the plain and the secure one, the secure one, since it also reads the certificate), under the name DNS gives that
@@ -804,6 +804,16 @@ nobody has noted is a warning on the Alerts page (kind *Monitoring*) and a notif
(where programs pick a free one) and anything bound to localhost only are left out. The port's row on the server's **Ports** card says *New* and has **Mark as expected**, which notes it and ends the alert; so does a label or comment you write on (where programs pick a free one) and anything bound to localhost only are left out. The port's row on the server's **Ports** card says *New* and has **Mark as expected**, which notes it and ends the alert; so does a label or comment you write on
it yourself. It also ends when the port stops listening, and maintenance on the server holds it back like its other alerts. It can be switched off under Settings → Notifications (*Servers and disks*); servers get their baseline from their next report after an upgrade, so nothing alerts for what was already there. it yourself. It also ends when the port stops listening, and maintenance on the server holds it back like its other alerts. It can be switched off under Settings → Notifications (*Servers and disks*); servers get their baseline from their next report after an upgrade, so nothing alerts for what was already there.
**A year of history.** The figures behind the trend lines and the answer-time charts used to reach back two weeks or five. A server's load, memory and disks are still kept as a sample every ten minutes for 35 days, and now also as an hour's and a day's average, lowest and highest (hours for four
months, days for over two years); a check's answers are kept as hours for four months and, as before, days for years. A chart asks for 24 hours, 7, 30 or 90 days or a year and is drawn from whichever is fine enough. A disk that two weeks call flat is looked at again over ninety days, so a slow, steady climb is forecast too
(on the Alerts page, the weekly digest and in `/metrics`). The first start after the upgrade builds the hours and days from the samples already kept, once.
**One chart.** Server trends, comparing servers, a check's availability and answer times, and a server's availability all use the same chart and the same ranges: hover (or press the arrow keys once it has focus) to read the values at any moment, a shaded band shows the lowest and highest where a point
stands for an hour or a day, a gap in the data is a gap in the line, and the range you pick is remembered for the next chart. **Endpoints → History…** opens a check's charts; a server's **History** section has its availability (30 days to a year) above its trends.
**API tokens.** The user menu → **API tokens** (for everyone signed in): make a read-only token for a script, Home Assistant or a dashboard — shown once, 30, 90 or 365 days or no end, ten at most, removed at once on request and with the person — and use it with `GET /api/v1/…` for
servers, alerts, incidents, inventory, network equipment, endpoint checks and maintenance. The addresses, what each answers and an example are in [API.md](API.md).
**UniFi network equipment.** Add a UniFi controller under Integrations (an API key, or a read-only local account; see INTEGRATIONS.md) and **Network → Network devices** lists its switches, access points and **UniFi network equipment.** Add a UniFi controller under Integrations (an API key, or a read-only local account; see INTEGRATIONS.md) and **Network → Network devices** lists its switches, access points and
gateways: whether each is up (and since when it was not), IP and MAC address, uptime, firmware (with *update available*), the device it is connected through, how many things depend on it, and — on the *Networks & Wi-Fi* tab — gateways: whether each is up (and since when it was not), IP and MAC address, uptime, firmware (with *update available*), the device it is connected through, how many things depend on it, and — on the *Networks & Wi-Fi* tab —
its networks (VLAN, address range) and Wi-Fi names (security, which network). It is read every five minutes and on **Read now**; nothing is ever written to the controller, and Wi-Fi passphrases are never read. The devices its networks (VLAN, address range) and Wi-Fi names (security, which network). It is read every five minutes and on **Read now**; nothing is ever written to the controller, and Wi-Fi passphrases are never read. The devices
+1
View File
@@ -99,6 +99,7 @@ even further, to admin only:
operator, and so does *Refresh from agent*; the price of power used for the running cost is admin-only. operator, and so does *Refresh from agent*; the price of power used for the running cost is admin-only.
- **Bulk actions** (the bar that appears when rows are ticked) need the same role as the single action: operator to acknowledge, silence, tag, change hardware and undo any of those; administrator for *Runs on…* on several servers - **Bulk actions** (the bar that appears when rows are ticked) need the same role as the single action: operator to acknowledge, silence, tag, change hardware and undo any of those; administrator for *Runs on…* on several servers
(and its undo). Viewers do not see the tick boxes. The **Noise** tab of Alerts is for everyone signed in. (and its undo). Viewers do not see the tick boxes. The **Noise** tab of Alerts is for everyone signed in.
- **API tokens** (user menu): anyone signed in makes, sees and removes their own, and nobody else's; a token can only read (`GET /api/v1`), sees what its owner sees, and is removed with its owner. The chart ranges and history are for everyone signed in.
- **My work** is shown to operators and administrators and only ever lists their own alerts, maintenance and update runs; the buttons on it (change an acknowledgement, extend or end a window) need operator, like the pages they come from. - **My work** is shown to operators and administrators and only ever lists their own alerts, maintenance and update runs; the buttons on it (change an acknowledgement, extend or end a window) need operator, like the pages they come from.
**Settings search** is part of Settings, which is administrators'. **Settings search** is part of Settings, which is administrators'.
- **Network devices** (Network → Network devices): everyone can see the devices, networks and Wi-Fi names read from UniFi controllers; **Read now** and putting a device under maintenance need operator; adding the UniFi - **Network devices** (Network → Network devices): everyone can see the devices, networks and Wi-Fi names read from UniFi controllers; **Read now** and putting a device under maintenance need operator; adding the UniFi
@@ -0,0 +1,24 @@
CREATE TABLE `endpoint_hourly` (
`check_id` integer NOT NULL,
`hour` text NOT NULL,
`total` integer DEFAULT 0 NOT NULL,
`ok` integer DEFAULT 0 NOT NULL,
`ms_sum` integer DEFAULT 0 NOT NULL,
`ms_count` integer DEFAULT 0 NOT NULL,
`ms_max` integer DEFAULT 0 NOT NULL,
PRIMARY KEY(`check_id`, `hour`),
FOREIGN KEY (`check_id`) REFERENCES `endpoint_checks`(`id`) ON UPDATE no action ON DELETE cascade
);
--> statement-breakpoint
CREATE TABLE `server_metrics_rollup` (
`server_id` integer NOT NULL,
`metric` text NOT NULL,
`grain` text NOT NULL,
`at` text NOT NULL,
`sum` real NOT NULL,
`n` integer NOT NULL,
`min` real NOT NULL,
`max` real NOT NULL,
PRIMARY KEY(`server_id`, `metric`, `grain`, `at`),
FOREIGN KEY (`server_id`) REFERENCES `servers`(`id`) ON UPDATE no action ON DELETE cascade
);
+13
View File
@@ -0,0 +1,13 @@
CREATE TABLE `api_tokens` (
`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
`user_id` integer NOT NULL,
`label` text NOT NULL,
`token_hash` text NOT NULL,
`token_prefix` text NOT NULL,
`created_at` text DEFAULT (current_timestamp) NOT NULL,
`last_used_at` text,
`expires_at` text,
FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE cascade
);
--> statement-breakpoint
CREATE UNIQUE INDEX `api_tokens_token_hash_unique` ON `api_tokens` (`token_hash`);
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
+14
View File
@@ -323,6 +323,20 @@
"when": 1792516305790, "when": 1792516305790,
"tag": "0045_military_exodus", "tag": "0045_military_exodus",
"breakpoints": true "breakpoints": true
},
{
"idx": 46,
"version": "6",
"when": 1792518508025,
"tag": "0046_tough_living_tribunal",
"breakpoints": true
},
{
"idx": 47,
"version": "6",
"when": 1792519188097,
"tag": "0047_eager_dorian_gray",
"breakpoints": true
} }
] ]
} }
+5
View File
@@ -47,6 +47,8 @@ import { alertsRouter } from "./routes/alerts.js";
import { mapRouter } from "./routes/map.js"; import { mapRouter } from "./routes/map.js";
import { networkRouter } from "./routes/network.js"; import { networkRouter } from "./routes/network.js";
import { myWorkRouter } from "./routes/myWork.js"; import { myWorkRouter } from "./routes/myWork.js";
import { apiTokensRouter } from "./routes/apiTokens.js";
import { publicApiRouter } from "./routes/publicApi.js";
import { generatorRouter } from "./routes/generator.js"; import { generatorRouter } from "./routes/generator.js";
import { alertTicketsRouter } from "./routes/alertTickets.js"; import { alertTicketsRouter } from "./routes/alertTickets.js";
import { avatarsRouter } from "./routes/avatars.js"; import { avatarsRouter } from "./routes/avatars.js";
@@ -83,6 +85,8 @@ export function createApp() {
app.use("/api/agent/report", agentReportRouter); app.use("/api/agent/report", agentReportRouter);
// A job reporting that it ran: a token in the address, no session, and no browser to be checked for where it came from. // A job reporting that it ran: a token in the address, no session, and no browser to be checked for where it came from.
app.use("/api/heartbeat", heartbeatPingRouter); app.use("/api/heartbeat", heartbeatPingRouter);
// The read API: a personal token in a header, GET only, no session and nothing for the same-origin check to protect.
app.use("/api/v1", publicApiRouter);
// Everything after this is reached with a session cookie, so a request that came from another origin is refused here. // Everything after this is reached with a session cookie, so a request that came from another origin is refused here.
app.use(sameOriginGuard); app.use(sameOriginGuard);
app.use(express.json()); app.use(express.json());
@@ -114,6 +118,7 @@ export function createApp() {
} }
app.use("/auth", authRouter); app.use("/auth", authRouter);
app.use("/api/me/tokens", apiTokensRouter);
app.use("/api/me", meRouter); app.use("/api/me", meRouter);
app.use("/api/avatars", avatarsRouter); app.use("/api/avatars", avatarsRouter);
app.use("/api/heartbeats", heartbeatsRouter); app.use("/api/heartbeats", heartbeatsRouter);
+57
View File
@@ -263,6 +263,26 @@ export const serverMetrics = sqliteTable(
(table) => [index("server_metrics_lookup_idx").on(table.serverId, table.metric, table.recordedAt)], (table) => [index("server_metrics_lookup_idx").on(table.serverId, table.metric, table.recordedAt)],
); );
// The same figures, kept longer and coarser: one row per server, figure and hour (grain "h", kept a few months) or day (grain "d", kept for years), with what is
// needed to draw them — the sum and count (so the average can be worked out as more samples arrive), and the lowest and highest. `at` is the start of the hour
// or day, as ISO. Written as each sample is recorded; see services/serverMetrics.ts.
export const serverMetricsRollup = sqliteTable(
"server_metrics_rollup",
{
serverId: integer("server_id")
.notNull()
.references(() => servers.id, { onDelete: "cascade" }),
metric: text("metric").notNull(),
grain: text("grain").$type<"h" | "d">().notNull(),
at: text("at").notNull(),
sum: real("sum").notNull(),
n: integer("n").notNull(),
min: real("min").notNull(),
max: real("max").notNull(),
},
(t) => [primaryKey({ columns: [t.serverId, t.metric, t.grain, t.at] })],
);
// ─── Settings (key/value) ─────────────────────────────────────────────────── // ─── Settings (key/value) ───────────────────────────────────────────────────
export const settings = sqliteTable("settings", { export const settings = sqliteTable("settings", {
@@ -993,6 +1013,24 @@ export const endpointDaily = sqliteTable(
(t) => [primaryKey({ columns: [t.checkId, t.day] })], (t) => [primaryKey({ columns: [t.checkId, t.day] })],
); );
// The same, by the hour: how many times a check was asked in that hour, how many answered, and the answer times — kept a few months, between the individual
// results (two weeks) and the daily figures (years), so an answer-time chart can reach back beyond two weeks without a point for every check.
export const endpointHourly = sqliteTable(
"endpoint_hourly",
{
checkId: integer("check_id")
.notNull()
.references(() => endpointChecks.id, { onDelete: "cascade" }),
hour: text("hour").notNull(), // ISO, the start of the hour (UTC)
total: integer("total").notNull().default(0),
ok: integer("ok").notNull().default(0),
msSum: integer("ms_sum").notNull().default(0),
msCount: integer("ms_count").notNull().default(0),
msMax: integer("ms_max").notNull().default(0),
},
(t) => [primaryKey({ columns: [t.checkId, t.hour] })],
);
// A certificate, domain registration or secret whose expiry moved later: it was renewed. Written when the app sees it happen, so it only goes back // A certificate, domain registration or secret whose expiry moved later: it was renewed. Written when the app sees it happen, so it only goes back
// as far as the version that began watching (services/renewals.ts). // as far as the version that began watching (services/renewals.ts).
export const renewals = sqliteTable( export const renewals = sqliteTable(
@@ -1050,6 +1088,25 @@ export const metricsTokens = sqliteTable("metrics_tokens", {
lastUsedAt: text("last_used_at"), // ISO lastUsedAt: text("last_used_at"), // ISO
}); });
// ─── Personal API tokens: read-only access to /api/v1 for scripts and Home Assistant ─────
// One person's own: made by them, shown to them once, and gone when they are. Only a hash of the secret is kept. A token only ever reads (the API has no other verbs),
// and sees what any signed-in person sees.
export const apiTokens = sqliteTable("api_tokens", {
id: integer("id").primaryKey({ autoIncrement: true }),
userId: integer("user_id")
.notNull()
.references(() => users.id, { onDelete: "cascade" }),
label: text("label").notNull(), // e.g. "Home Assistant"
tokenHash: text("token_hash").notNull().unique(),
tokenPrefix: text("token_prefix").notNull(),
createdAt: text("created_at")
.notNull()
.default(sql`(current_timestamp)`),
lastUsedAt: text("last_used_at"), // ISO
expiresAt: text("expires_at"), // ISO; null = until removed
});
// ─── Event webhooks: tell another system when something happens ───────────── // ─── Event webhooks: tell another system when something happens ─────────────
export const webhookEvents = ["alert.opened", "alert.resolved", "maintenance.started", "maintenance.ended"] as const; export const webhookEvents = ["alert.opened", "alert.resolved", "maintenance.started", "maintenance.ended"] as const;
+4
View File
@@ -25,6 +25,8 @@ import { initEndpointMonitor } from "./services/endpointMonitor.js";
import { initPatchPlans } from "./services/patchPlans.js"; import { initPatchPlans } from "./services/patchPlans.js";
import { initFlapMonitor } from "./services/flapMonitor.js"; import { initFlapMonitor } from "./services/flapMonitor.js";
import { initUnifiSync } from "./services/unifiSync.js"; import { initUnifiSync } from "./services/unifiSync.js";
import { backfillMetricRollups } from "./services/serverMetrics.js";
import { backfillEndpointHourly } from "./services/endpointChecks.js";
import { initSelfBackupScheduler } from "./services/selfBackupScheduler.js"; import { initSelfBackupScheduler } from "./services/selfBackupScheduler.js";
import { initIncidentRecorder } from "./services/incidents.js"; import { initIncidentRecorder } from "./services/incidents.js";
import { getAlerts } from "./services/alerts.js"; import { getAlerts } from "./services/alerts.js";
@@ -69,6 +71,8 @@ initEndpointMonitor();
initPatchPlans(); initPatchPlans();
initFlapMonitor(); initFlapMonitor();
initUnifiSync(); initUnifiSync();
// The hourly and daily figures are built from what is already kept, once, the first time after they were added (in the background: nothing waits for it).
void Promise.all([backfillMetricRollups(), backfillEndpointHourly()]).catch((err) => console.error("[history] couldn't build the hourly and daily figures:", err));
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}`);
+46
View File
@@ -0,0 +1,46 @@
import { Router } from "express";
import { z } from "zod";
import { requireAuth } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { createApiToken, EXPIRY_CHOICES, listApiTokens, MAX_TOKENS_PER_PERSON, publicApiToken, removeApiToken, TokenLimitError } from "../services/apiTokens.js";
import { asyncHandler } from "../utils/asyncHandler.js";
/** A person's own API tokens: anyone signed in makes, sees and removes theirs — never anybody else's. */
export const apiTokensRouter = Router();
apiTokensRouter.use(requireAuth);
const createSchema = z.object({
label: z.string().trim().min(1).max(60),
// Days until it stops working; null (or left out) for until it is removed.
expiresInDays: z.union([z.literal(30), z.literal(90), z.literal(365)]).nullable().optional(),
});
apiTokensRouter.get("/", asyncHandler(async (req, res) => {
const rows = await listApiTokens(req.currentUser!.id);
res.json({ tokens: rows.map((r) => publicApiToken(r)), max: MAX_TOKENS_PER_PERSON, expiryChoices: EXPIRY_CHOICES });
}));
// The secret is in this answer and nowhere else, ever.
apiTokensRouter.post("/", asyncHandler(async (req, res) => {
const parsed = createSchema.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: "invalid_body", message: "Give the token a name, like Home Assistant, and choose 30, 90 or 365 days or no end." });
const actor = req.currentUser!;
try {
const { row, token } = await createApiToken({ userId: actor.id, label: parsed.data.label, expiresInDays: parsed.data.expiresInDays ?? null });
await recordAudit({ actor, category: "api_token", action: "create", targetType: "api_token", targetId: row.id, detail: { label: row.label, expiresAt: row.expiresAt } });
res.status(201).json({ token: publicApiToken(row), secret: token });
} catch (err) {
if (err instanceof TokenLimitError) return res.status(400).json({ error: "too_many", message: err.message });
throw err;
}
}));
apiTokensRouter.delete("/:id", asyncHandler(async (req, res) => {
const id = /^\d+$/.test(req.params.id) ? Number(req.params.id) : NaN;
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const actor = req.currentUser!;
const removed = await removeApiToken(actor.id, id);
if (!removed) return res.status(404).json({ error: "not_found" });
await recordAudit({ actor, category: "api_token", action: "delete", targetType: "api_token", targetId: id, detail: { label: removed.label } });
res.status(204).end();
}));
+12 -1
View File
@@ -6,7 +6,7 @@ import { endpointChecks, servers } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js"; import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js"; import { recordAudit } from "../services/audit.js";
import { invalidateAlertsCache } from "../services/alerts.js"; import { invalidateAlertsCache } from "../services/alerts.js";
import { CHECK_KINDS, isStatusSpec, loadStats, runCheck } from "../services/endpointChecks.js"; import { CHECK_KINDS, getEndpointHistory, isStatusSpec, loadStats, runCheck } from "../services/endpointChecks.js";
import { loadDismissed, loadSuggestions, saveDismissed } from "../services/endpointSuggestions.js"; import { loadDismissed, loadSuggestions, saveDismissed } from "../services/endpointSuggestions.js";
import { asyncHandler } from "../utils/asyncHandler.js"; import { asyncHandler } from "../utils/asyncHandler.js";
@@ -63,6 +63,17 @@ endpointsRouter.get("/", asyncHandler(async (_req, res) => {
}); });
})); }));
// How one check has done over a day, a week, a month, three months or a year: availability and answer times, for the chart on its page.
endpointsRouter.get("/:id/history", asyncHandler(async (req, res) => {
const id = /^\d+$/.test(req.params.id) ? Number(req.params.id) : NaN;
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const [check] = await db.select({ id: endpointChecks.id, name: endpointChecks.name }).from(endpointChecks).where(eq(endpointChecks.id, id)).limit(1);
if (!check) return res.status(404).json({ error: "not_found" });
const requested = Number(req.query.days);
const days = Number.isFinite(requested) ? Math.min(365, Math.max(1, Math.round(requested))) : 7;
res.json({ check, ...(await getEndpointHistory(id, days)) });
}));
function valuesOf(d: z.infer<typeof checkSchema>) { function valuesOf(d: z.infer<typeof checkSchema>) {
return { return {
name: d.name, name: d.name,
+4 -63
View File
@@ -2,12 +2,11 @@ import { Router } from "express";
import { eq } from "drizzle-orm"; import { eq } from "drizzle-orm";
import { z } from "zod"; import { z } from "zod";
import { db } from "../db/client.js"; import { db } from "../db/client.js";
import { integrations, networkDevices, networkSegments, networkServerLinks, servers } from "../db/schema.js"; import { integrations } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js"; import { requireAuth, requireRole } from "../auth/middleware.js";
import { invalidateAlertsCache } from "../services/alerts.js"; import { invalidateAlertsCache } from "../services/alerts.js";
import { dependentsOf, loadGraph, needsOfNode, nodeKey } from "../services/dependencies.js"; import { buildNetworkOverview } from "../services/networkOverview.js";
import { activeSubjects } from "../services/maintenance.js"; import { syncAllUnifi, syncUnifiIntegration } from "../services/unifiSync.js";
import { syncAllUnifi, syncStatuses, syncUnifiIntegration } from "../services/unifiSync.js";
import { asyncHandler } from "../utils/asyncHandler.js"; import { asyncHandler } from "../utils/asyncHandler.js";
export const networkRouter = Router(); export const networkRouter = Router();
@@ -19,65 +18,7 @@ networkRouter.use(requireAuth);
* names. Everyone signed in can see it (it is the same picture the dependency map and the alerts draw on); only starting a fresh read needs more. * names. Everyone signed in can see it (it is the same picture the dependency map and the alerts draw on); only starting a fresh read needs more.
*/ */
networkRouter.get("/", asyncHandler(async (_req, res) => { networkRouter.get("/", asyncHandler(async (_req, res) => {
const [intRows, devices, segments, statuses, graph, silenced, linkRows, serverRows] = await Promise.all([ res.json(await buildNetworkOverview());
db.select({ id: integrations.id, name: integrations.name, enabled: integrations.enabled }).from(integrations).where(eq(integrations.type, "unifi")),
db.select().from(networkDevices),
db.select().from(networkSegments),
syncStatuses(),
loadGraph(),
activeSubjects(),
db.select().from(networkServerLinks),
db.select({ id: servers.id, name: servers.name }).from(servers),
]);
const serverName = new Map(serverRows.map((s) => [s.id, s.name]));
const intName = new Map(intRows.map((i) => [i.id, i.name]));
const byExternal = new Map(devices.map((d) => [`${d.integrationId}:${d.externalId}`, d]));
// The servers plugged into each device, by what the controller says is connected (see unifiSync.matchClientsToServers).
const plugged = new Map<number, { serverId: number; serverName: string; port: number | null; wired: boolean }[]>();
const serverLinks: { serverId: number; serverName: string; deviceId: number; deviceName: string; port: number | null; wired: boolean }[] = [];
for (const l of linkRows) {
const device = byExternal.get(`${l.integrationId}:${l.deviceExternalId}`);
const name = serverName.get(l.serverId);
if (!device || !name) continue;
plugged.set(device.id, [...(plugged.get(device.id) ?? []), { serverId: l.serverId, serverName: name, port: l.port, wired: l.wired }]);
serverLinks.push({ serverId: l.serverId, serverName: name, deviceId: device.id, deviceName: device.name, port: l.port, wired: l.wired });
}
res.json({
serverLinks,
integrations: intRows.map((i) => ({ id: i.id, name: i.name, enabled: i.enabled, status: statuses[i.id] ?? null })),
devices: devices
.map((d) => {
const key = nodeKey("device", d.id);
const uplink = d.uplinkExternalId ? byExternal.get(`${d.integrationId}:${d.uplinkExternalId}`) : undefined;
return {
id: d.id,
integrationId: d.integrationId,
integrationName: intName.get(d.integrationId) ?? "UniFi",
siteName: d.siteName,
name: d.name,
model: d.model,
kind: d.kind,
ip: d.ip,
mac: d.mac,
state: d.state,
uptimeSeconds: d.uptimeSeconds,
firmware: d.firmware,
firmwareUpdatable: d.firmwareUpdatable,
uplink: uplink ? { id: uplink.id, name: uplink.name } : null,
offlineSince: d.offlineSince,
lastOnlineAt: d.lastOnlineAt,
updatedAt: d.updatedAt,
// How many things depend on it (directly or through others), and how many it needs: what the dependency map says about it.
dependents: dependentsOf(graph.edges, key).length,
needs: needsOfNode(graph.edges, key).length,
inMaintenance: silenced.has(key),
servers: (plugged.get(d.id) ?? []).sort((a, b) => a.serverName.localeCompare(b.serverName)),
};
})
.sort((a, b) => a.name.localeCompare(b.name)),
networks: segments.filter((s) => s.kind === "network").map(({ kind: _k, ...s }) => ({ ...s, integrationName: intName.get(s.integrationId) ?? "UniFi" })).sort((a, b) => (a.vlanId ?? 0) - (b.vlanId ?? 0) || a.name.localeCompare(b.name)),
ssids: segments.filter((s) => s.kind === "ssid").map(({ kind: _k, ...s }) => ({ ...s, integrationName: intName.get(s.integrationId) ?? "UniFi" })).sort((a, b) => a.name.localeCompare(b.name)),
});
})); }));
const syncSchema = z.object({ integrationId: z.number().int().positive().optional() }); const syncSchema = z.object({ integrationId: z.number().int().positive().optional() });
+165
View File
@@ -0,0 +1,165 @@
import { Router, type NextFunction, type Request, type Response } from "express";
import { eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { endpointChecks, servers } from "../db/schema.js";
import { resolveApiToken, type ApiTokenRow, type ApiTokenUser } from "../services/apiTokens.js";
import { getEndpointHistory } from "../services/endpointChecks.js";
import { getIncident, listIncidents } from "../services/incidents.js";
import { buildNetworkOverview } from "../services/networkOverview.js";
import { alertsV1, endpointsV1, inventoryV1, maintenanceV1, oneServerV1, serversV1 } from "../services/publicApi.js";
import { getServerMetrics, MAX_RANGE_DAYS } from "../services/serverMetrics.js";
import { asyncHandler } from "../utils/asyncHandler.js";
import { rateLimit } from "../utils/rateLimit.js";
/**
* The read API: JSON about servers, alerts, incidents, inventory, network equipment, endpoint checks and maintenance, for scripts and things like Home Assistant.
* A personal token in the Authorization header (never the address, which ends up in logs); GET only; and nothing here writes anything.
*/
export const publicApiRouter = Router();
declare module "express-serve-static-core" {
interface Request {
apiToken?: { token: ApiTokenRow; user: ApiTokenUser };
}
}
const limiter = rateLimit({ windowMs: 60_000, max: 300, message: "Too many requests." });
publicApiRouter.use(limiter);
publicApiRouter.use((req: Request, res: Response, next: NextFunction) => {
res.setHeader("Cache-Control", "no-store");
if (req.method !== "GET" && req.method !== "HEAD") {
res.setHeader("Allow", "GET, HEAD");
return res.status(405).json({ error: "read_only", message: "This API only reads. It has no way to change anything." });
}
next();
});
publicApiRouter.use(
asyncHandler(async (req, res, next) => {
const match = /^Bearer\s+(\S+)$/i.exec(req.get("authorization") ?? "");
const found = match ? await resolveApiToken(match[1]) : null;
if (!found) {
// The same answer for no token, a wrong one, an expired one and a removed one.
res.setHeader("WWW-Authenticate", 'Bearer realm="homelab-manager"');
return res.status(401).json({ error: "unauthorized", message: "A token is needed: send it as 'Authorization: Bearer <token>'. Make one from the user menu → API tokens." });
}
req.apiToken = found;
next();
}),
);
const idOf = (v: string) => (/^\d+$/.test(v) ? Number(v) : NaN);
const daysOf = (v: unknown, fallback: number) => {
const n = Number(v);
return Number.isFinite(n) ? Math.min(MAX_RANGE_DAYS, Math.max(1, Math.round(n))) : fallback;
};
publicApiRouter.get("/", (_req, res) => {
res.json({
name: "Homelab Manager read API",
version: 1,
endpoints: [
"GET /api/v1/me",
"GET /api/v1/servers?tag=&status=",
"GET /api/v1/servers/:id",
"GET /api/v1/servers/:id/metrics?days=",
"GET /api/v1/alerts?severity=&category=&acknowledged=&silenced=",
"GET /api/v1/incidents?status=&limit=",
"GET /api/v1/incidents/:id",
"GET /api/v1/inventory",
"GET /api/v1/network",
"GET /api/v1/endpoints",
"GET /api/v1/endpoints/:id/history?days=",
"GET /api/v1/maintenance",
],
});
});
publicApiRouter.get("/me", (req, res) => {
const { token, user } = req.apiToken!;
res.json({ user: { id: user.id, name: user.name, email: user.email, role: user.role }, token: { id: token.id, label: token.label, expiresAt: token.expiresAt } });
});
publicApiRouter.get("/servers", asyncHandler(async (req, res) => {
let list = await serversV1();
if (typeof req.query.tag === "string" && req.query.tag) {
const tag = req.query.tag.toLowerCase();
list = list.filter((s) => s.tags.includes(tag));
}
if (req.query.status === "online" || req.query.status === "offline" || req.query.status === "unknown") list = list.filter((s) => s.status === req.query.status);
res.json({ servers: list });
}));
publicApiRouter.get("/servers/:id", asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const server = await oneServerV1(id);
if (!server) return res.status(404).json({ error: "not_found" });
res.json({ server });
}));
publicApiRouter.get("/servers/:id/metrics", asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const [row] = await db.select({ id: servers.id }).from(servers).where(eq(servers.id, id)).limit(1);
if (!row) return res.status(404).json({ error: "not_found" });
const days = daysOf(req.query.days, 7);
res.json({ days, series: await getServerMetrics(id, days) });
}));
publicApiRouter.get("/alerts", asyncHandler(async (req, res) => {
const report = await alertsV1();
let alerts = report.alerts;
const q = req.query;
if (typeof q.severity === "string") alerts = alerts.filter((a) => a.severity === q.severity);
if (typeof q.category === "string") alerts = alerts.filter((a) => a.category === q.category);
if (q.acknowledged === "true" || q.acknowledged === "false") alerts = alerts.filter((a) => (a.acknowledgement !== null) === (q.acknowledged === "true"));
if (q.silenced === "true" || q.silenced === "false") alerts = alerts.filter((a) => a.silenced === (q.silenced === "true"));
res.json({ ...report, alerts });
}));
publicApiRouter.get("/incidents", asyncHandler(async (req, res) => {
const limit = Math.min(500, Math.max(1, Math.round(Number(req.query.limit)) || 100));
let list = await listIncidents({ limit });
if (req.query.status === "open") list = list.filter((i) => i.open);
else if (req.query.status === "resolved") list = list.filter((i) => !i.open);
res.json({ incidents: list });
}));
publicApiRouter.get("/incidents/:id", asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const detail = await getIncident(id);
if (!detail) return res.status(404).json({ error: "not_found" });
res.json(detail);
}));
publicApiRouter.get("/inventory", asyncHandler(async (_req, res) => {
res.json({ assets: await inventoryV1() });
}));
publicApiRouter.get("/network", asyncHandler(async (_req, res) => {
const overview = await buildNetworkOverview();
res.json({ devices: overview.devices, networks: overview.networks, ssids: overview.ssids, serverLinks: overview.serverLinks });
}));
publicApiRouter.get("/endpoints", asyncHandler(async (_req, res) => {
res.json({ endpoints: await endpointsV1() });
}));
publicApiRouter.get("/endpoints/:id/history", asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const [check] = await db.select({ id: endpointChecks.id, name: endpointChecks.name }).from(endpointChecks).where(eq(endpointChecks.id, id)).limit(1);
if (!check) return res.status(404).json({ error: "not_found" });
res.json({ check, ...(await getEndpointHistory(id, daysOf(req.query.days, 7))) });
}));
publicApiRouter.get("/maintenance", asyncHandler(async (_req, res) => {
res.json(await maintenanceV1());
}));
publicApiRouter.use((_req, res) => {
res.status(404).json({ error: "not_found", message: "No such address. GET /api/v1 lists them." });
});
+2 -2
View File
@@ -12,7 +12,7 @@ import { markIgnoredServices, parseHostHealth } from "../services/hostHealth.js"
import { describeDiagnostics, parseDiagnostics } from "../services/agentDiagnostics.js"; import { describeDiagnostics, parseDiagnostics } from "../services/agentDiagnostics.js";
import { checkThresholds, parseThresholds } from "../services/serverThresholds.js"; import { checkThresholds, parseThresholds } from "../services/serverThresholds.js";
import { latestAgentVersions } from "../services/agentVersions.js"; import { latestAgentVersions } from "../services/agentVersions.js";
import { getServerMetrics, RETENTION_DAYS } from "../services/serverMetrics.js"; import { getServerMetrics, MAX_RANGE_DAYS } from "../services/serverMetrics.js";
import { getServerActivity } from "../services/serverActivity.js"; import { getServerActivity } from "../services/serverActivity.js";
import { asyncHandler } from "../utils/asyncHandler.js"; import { asyncHandler } from "../utils/asyncHandler.js";
import { ID_PATTERNS } from "../utils/pathSegment.js"; import { ID_PATTERNS } from "../utils/pathSegment.js";
@@ -272,7 +272,7 @@ serversRouter.get("/:id/metrics", asyncHandler(async (req, res) => {
const [server] = await db.select({ id: servers.id }).from(servers).where(eq(servers.id, id)).limit(1); const [server] = await db.select({ id: servers.id }).from(servers).where(eq(servers.id, id)).limit(1);
if (!server) return res.status(404).json({ error: "not_found" }); if (!server) return res.status(404).json({ error: "not_found" });
const requested = Number(req.query.days); const requested = Number(req.query.days);
const days = Number.isFinite(requested) ? Math.min(RETENTION_DAYS, Math.max(1, Math.round(requested))) : 7; const days = Number.isFinite(requested) ? Math.min(MAX_RANGE_DAYS, Math.max(1, Math.round(requested))) : 7;
res.json({ days, series: await getServerMetrics(id, days) }); res.json({ days, series: await getServerMetrics(id, days) });
})); }));
+5 -2
View File
@@ -6,6 +6,9 @@ import { getUptime } from "../services/uptimeHistory.js";
export const uptimeRouter = Router(); export const uptimeRouter = Router();
// Anyone signed in who can see the server and integration lists can see how those have been doing. // Anyone signed in who can see the server and integration lists can see how those have been doing.
uptimeRouter.get("/", requireAuth, asyncHandler(async (_req, res) => { // `?days=` is 30 by default and at most a year (as far back as the audit log it is worked out from goes).
res.json(await getUptime()); uptimeRouter.get("/", requireAuth, asyncHandler(async (req, res) => {
const requested = Number(req.query.days);
const days = Number.isFinite(requested) ? Math.min(365, Math.max(1, Math.round(requested))) : undefined;
res.json(await getUptime(new Date(), days));
})); }));
+2 -2
View File
@@ -12,7 +12,7 @@
import { eq } from "drizzle-orm"; import { eq } from "drizzle-orm";
import { db } from "../db/client.js"; import { db } from "../db/client.js";
import { endpointChecks, heartbeats, integrations, networkDevices, secrets, servers } from "../db/schema.js"; import { endpointChecks, heartbeats, integrations, networkDevices, secrets, servers } from "../db/schema.js";
import { disksFillingSoon, getServerMetrics } from "./serverMetrics.js"; import { disksFillingSoon, getForecastSeries } from "./serverMetrics.js";
import { diskLimit, effectiveThresholds, parseThresholds } from "./serverThresholds.js"; import { diskLimit, effectiveThresholds, parseThresholds } from "./serverThresholds.js";
import { getBackupCoverage, staleBackups } from "./backupCoverage.js"; import { getBackupCoverage, staleBackups } from "./backupCoverage.js";
import { recordFromReport } from "./incidents.js"; import { recordFromReport } from "./incidents.js";
@@ -499,7 +499,7 @@ export async function collectAlerts(): Promise<AlertsReport> {
const own = parseThresholds(s.thresholds); const own = parseThresholds(s.thresholds);
const forecastDays = effectiveThresholds(healthChecks, own).diskForecastDays; const forecastDays = effectiveThresholds(healthChecks, own).diskForecastDays;
if (!(forecastDays > 0)) continue; if (!(forecastDays > 0)) continue;
const series = await getServerMetrics(s.id, 14); const series = await getForecastSeries(s.id);
for (const f of disksFillingSoon(series, forecastDays, (mount) => diskLimit(own, mount, healthChecks.diskUsagePercent))) { for (const f of disksFillingSoon(series, forecastDays, (mount) => diskLimit(own, mount, healthChecks.diskUsagePercent))) {
push({ push({
category: "disk", category: "disk",
+74
View File
@@ -0,0 +1,74 @@
/**
* Personal API tokens: read-only access to /api/v1 for scripts, Home Assistant and the like. Each belongs to the person who made it — they see and remove their own —
* and goes when they do. Like an agent token or a share link, the secret is shown once, when it is made, and only its SHA-256 is kept.
*/
import { createHash, randomBytes } from "node:crypto";
import { and, eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { apiTokens, users } from "../db/schema.js";
export type ApiTokenRow = typeof apiTokens.$inferSelect;
export type ApiTokenUser = typeof users.$inferSelect;
const hash = (token: string) => createHash("sha256").update(token).digest("hex");
/** Most tokens one person may have: one for each thing that reads, and a spare. */
export const MAX_TOKENS_PER_PERSON = 10;
/** How long a token may be asked to last, in days (or never). */
export const EXPIRY_CHOICES = [30, 90, 365] as const;
/** Use is not recorded more than once in this time, so a script that reads every few seconds doesn't write the database each time. */
const USED_WRITE_GAP_MS = 60_000;
export class TokenLimitError extends Error {}
export async function createApiToken(params: { userId: number; label: string; expiresInDays: number | null }, now: Date = new Date()): Promise<{ row: ApiTokenRow; token: string }> {
const existing = await db.select({ id: apiTokens.id }).from(apiTokens).where(eq(apiTokens.userId, params.userId));
if (existing.length >= MAX_TOKENS_PER_PERSON) throw new TokenLimitError(`There are already ${MAX_TOKENS_PER_PERSON} tokens. Remove one you don't use first.`);
const token = `hlm_p_${randomBytes(24).toString("base64url")}`;
const expiresAt = params.expiresInDays === null ? null : new Date(now.getTime() + params.expiresInDays * 86_400_000).toISOString();
const [row] = await db.insert(apiTokens).values({ userId: params.userId, label: params.label, tokenHash: hash(token), tokenPrefix: token.slice(0, 12), expiresAt }).returning();
return { row, token };
}
/** The token a secret belongs to and whose it is, if it is one that still works; notes that it was used. */
export async function resolveApiToken(secret: string, now: Date = new Date()): Promise<{ token: ApiTokenRow; user: ApiTokenUser } | null> {
if (typeof secret !== "string" || secret.length < 20 || secret.length > 128) return null;
const [found] = await db
.select({ token: apiTokens, user: users })
.from(apiTokens)
.innerJoin(users, eq(users.id, apiTokens.userId))
.where(eq(apiTokens.tokenHash, hash(secret)))
.limit(1);
if (!found) return null;
if (found.token.expiresAt && Date.parse(found.token.expiresAt) <= now.getTime()) return null;
if (!found.token.lastUsedAt || now.getTime() - Date.parse(found.token.lastUsedAt) >= USED_WRITE_GAP_MS) {
await db.update(apiTokens).set({ lastUsedAt: now.toISOString() }).where(eq(apiTokens.id, found.token.id));
}
return found;
}
/** A token as its owner's list shows it: everything but the hash. */
export function publicApiToken(row: ApiTokenRow, now: Date = new Date()) {
return {
id: row.id,
label: row.label,
tokenPrefix: row.tokenPrefix,
createdAt: row.createdAt,
lastUsedAt: row.lastUsedAt,
expiresAt: row.expiresAt,
expired: row.expiresAt !== null && Date.parse(row.expiresAt) <= now.getTime(),
};
}
export async function listApiTokens(userId: number) {
return db.select().from(apiTokens).where(eq(apiTokens.userId, userId)).orderBy(apiTokens.createdAt);
}
/** Removes one of a person's own tokens. Returns whether there was one. */
export async function removeApiToken(userId: number, id: number): Promise<ApiTokenRow | null> {
const [row] = await db.select().from(apiTokens).where(and(eq(apiTokens.id, id), eq(apiTokens.userId, userId))).limit(1);
if (!row) return null;
await db.delete(apiTokens).where(eq(apiTokens.id, id));
return row;
}
+1
View File
@@ -39,6 +39,7 @@ const KIND_OF_CATEGORY: Record<string, ChangeKind> = {
push: "settings", push: "settings",
share_link: "settings", share_link: "settings",
metrics_token: "settings", metrics_token: "settings",
api_token: "settings",
webhook: "settings", webhook: "settings",
integration: "integrations", integration: "integrations",
dns: "integrations", dns: "integrations",
+147 -1
View File
@@ -14,7 +14,8 @@ import tls from "node:tls";
import type { TLSSocket } from "node:tls"; import type { TLSSocket } from "node:tls";
import { and, asc, eq, gte, inArray, lt, sql } from "drizzle-orm"; import { and, asc, eq, gte, inArray, lt, sql } from "drizzle-orm";
import { db } from "../db/client.js"; import { db } from "../db/client.js";
import { endpointChecks, endpointDaily, endpointResults } from "../db/schema.js"; import { endpointChecks, endpointDaily, endpointHourly, endpointResults } from "../db/schema.js";
import { getInternalFlag, setInternalFlag } from "./settingsStore.js";
import { noteRenewal } from "./renewals.js"; import { noteRenewal } from "./renewals.js";
import { resolveTarget } from "../utils/networkGuard.js"; import { resolveTarget } from "../utils/networkGuard.js";
@@ -246,6 +247,7 @@ export async function runCheck(c: CheckRow, now: Date = new Date(), probeFn: (c:
.where(eq(endpointChecks.id, c.id)); .where(eq(endpointChecks.id, c.id));
await db.insert(endpointResults).values({ checkId: c.id, at: iso, ok: result.ok, ms: result.ms, message: result.message.slice(0, 300) }); await db.insert(endpointResults).values({ checkId: c.id, at: iso, ok: result.ok, ms: result.ms, message: result.message.slice(0, 300) });
await addToDaily(c.id, iso, result); await addToDaily(c.id, iso, result);
await addToHourly(c.id, iso, result);
// A certificate that is now good for much longer than it was has been renewed. // A certificate that is now good for much longer than it was has been renewed.
if (result.certExpiresAt) await noteRenewal("certificate", c.name, c.certExpiresAt, result.certExpiresAt, now); if (result.certExpiresAt) await noteRenewal("certificate", c.name, c.certExpiresAt, result.certExpiresAt, now);
return result; return result;
@@ -272,6 +274,45 @@ async function addToDaily(checkId: number, atIso: string, result: ProbeResult):
} }
} }
/** How long the hourly figures are kept: between the individual results (two weeks) and the daily figures (years). */
export const KEEP_HOURLY_DAYS = 120;
/** Adds one result to its hour, so an answer-time chart can reach back beyond two weeks with a point an hour rather than one for every check. */
async function addToHourly(checkId: number, atIso: string, result: ProbeResult): Promise<void> {
const timed = result.ok && result.ms !== null;
const ok = result.ok ? 1 : 0;
const ms = timed ? (result.ms as number) : 0;
const hour = `${atIso.slice(0, 13)}:00:00.000Z`;
try {
await db
.insert(endpointHourly)
.values({ checkId, hour, total: 1, ok, msSum: ms, msCount: timed ? 1 : 0, msMax: ms })
.onConflictDoUpdate({
target: [endpointHourly.checkId, endpointHourly.hour],
set: { total: sql`${endpointHourly.total} + 1`, ok: sql`${endpointHourly.ok} + ${ok}`, msSum: sql`${endpointHourly.msSum} + ${ms}`, msCount: sql`${endpointHourly.msCount} + ${timed ? 1 : 0}`, msMax: sql`max(${endpointHourly.msMax}, ${ms})` },
});
} catch (err) {
console.error("[endpoints] couldn't add to the hourly figures:", err);
}
}
const HOURLY_BACKFILL_FLAG = "endpointHourlyBackfilled";
/** The first time after the hourly figures were added, builds them from the results still kept (two weeks). Done once. */
export async function backfillEndpointHourly(): Promise<boolean> {
if (await getInternalFlag(HOURLY_BACKFILL_FLAG)) return false;
await db.run(sql`
INSERT INTO endpoint_hourly (check_id, hour, total, ok, ms_sum, ms_count, ms_max)
SELECT check_id, substr(at, 1, 13) || ':00:00.000Z', count(*), sum(ok), sum(CASE WHEN ok = 1 AND ms IS NOT NULL THEN ms ELSE 0 END),
sum(CASE WHEN ok = 1 AND ms IS NOT NULL THEN 1 ELSE 0 END), coalesce(max(CASE WHEN ok = 1 AND ms IS NOT NULL THEN ms END), 0)
FROM endpoint_results
GROUP BY check_id, substr(at, 1, 13)
ON CONFLICT (check_id, hour) DO UPDATE SET total = excluded.total, ok = excluded.ok, ms_sum = excluded.ms_sum, ms_count = excluded.ms_count, ms_max = excluded.ms_max
`);
await setInternalFlag(HOURLY_BACKFILL_FLAG, new Date().toISOString());
return true;
}
/** Runs every enabled check that is due, a few at a time. Returns how many it asked. */ /** Runs every enabled check that is due, a few at a time. Returns how many it asked. */
export async function runDueChecks(now: Date = new Date(), probeFn?: (c: CheckRow) => Promise<ProbeResult>): Promise<number> { export async function runDueChecks(now: Date = new Date(), probeFn?: (c: CheckRow) => Promise<ProbeResult>): Promise<number> {
const rows = await db.select().from(endpointChecks).where(eq(endpointChecks.enabled, true)).orderBy(asc(endpointChecks.id)); const rows = await db.select().from(endpointChecks).where(eq(endpointChecks.enabled, true)).orderBy(asc(endpointChecks.id));
@@ -290,6 +331,111 @@ export async function runDueChecks(now: Date = new Date(), probeFn?: (c: CheckRo
export async function pruneResults(now: Date = new Date()): Promise<void> { export async function pruneResults(now: Date = new Date()): Promise<void> {
await db.delete(endpointResults).where(lt(endpointResults.at, new Date(now.getTime() - KEEP_RESULT_DAYS * 86_400_000).toISOString())); await db.delete(endpointResults).where(lt(endpointResults.at, new Date(now.getTime() - KEEP_RESULT_DAYS * 86_400_000).toISOString()));
await db.delete(endpointDaily).where(lt(endpointDaily.day, new Date(now.getTime() - KEEP_DAILY_DAYS * 86_400_000).toISOString().slice(0, 10))); await db.delete(endpointDaily).where(lt(endpointDaily.day, new Date(now.getTime() - KEEP_DAILY_DAYS * 86_400_000).toISOString().slice(0, 10)));
await db.delete(endpointHourly).where(lt(endpointHourly.hour, new Date(now.getTime() - KEEP_HOURLY_DAYS * 86_400_000).toISOString()));
}
// ─── How a check has done over a long time ─────────────────────────────────
/** A row of figures for some stretch of time (one result, one hour or one day), with the moment it starts at as epoch ms. */
export interface HistoryRow {
t: number;
total: number;
ok: number;
msSum: number;
msCount: number;
msMax: number;
}
export interface HistoryPoint {
/** ISO. */
t: string;
/** Share of the checks in this stretch that answered, 0–100. */
availability: number | null;
/** Average and longest answer time of the good, timed answers; null when there were none. */
avgMs: number | null;
maxMs: number | null;
/** How many checks it stands for. */
checks: number;
}
/** Rows into at most `maxPoints` equal slices of [from, to]: figures are added up per slice, so a slice is as true as the checks in it. */
export function bucketHistory(rows: HistoryRow[], from: number, to: number, maxPoints: number): HistoryPoint[] {
if (rows.length === 0 || to <= from) return [];
const size = Math.max((to - from) / maxPoints, 1);
const buckets = new Map<number, { total: number; ok: number; msSum: number; msCount: number; msMax: number; tSum: number; rows: number }>();
for (const r of rows) {
if (r.t < from || r.t > to || r.total <= 0) continue;
const key = Math.min(maxPoints - 1, Math.floor((r.t - from) / size));
const b = buckets.get(key) ?? { total: 0, ok: 0, msSum: 0, msCount: 0, msMax: 0, tSum: 0, rows: 0 };
b.total += r.total;
b.ok += r.ok;
b.msSum += r.msSum;
b.msCount += r.msCount;
b.msMax = Math.max(b.msMax, r.msMax);
b.tSum += r.t;
b.rows += 1;
buckets.set(key, b);
}
return [...buckets.entries()]
.sort((a, b) => a[0] - b[0])
.map(([, b]) => ({
t: new Date(b.tSum / b.rows).toISOString(),
availability: Math.round((b.ok / b.total) * 1000) / 10,
avgMs: b.msCount > 0 ? Math.round(b.msSum / b.msCount) : null,
maxMs: b.msCount > 0 ? b.msMax : null,
checks: b.total,
}));
}
export interface EndpointHistory {
days: number;
/** Which figures it was drawn from: the results themselves (a day or two), the hourly figures, or the daily ones. */
source: "results" | "hourly" | "daily";
points: HistoryPoint[];
/** Over the whole stretch. */
availability: number | null;
avgMs: number | null;
checks: number;
}
/** How a check did over the last `days` (up to a year): availability and answer times, from the finest figures that reach back that far. */
export async function getEndpointHistory(checkId: number, days: number, now: Date = new Date()): Promise<EndpointHistory> {
days = Math.min(365, Math.max(1, Math.round(days)));
const to = now.getTime();
const from = to - days * 86_400_000;
let rows: HistoryRow[];
let source: EndpointHistory["source"];
if (days <= 2) {
source = "results";
const found = await db
.select({ at: endpointResults.at, ok: endpointResults.ok, ms: endpointResults.ms })
.from(endpointResults)
.where(and(eq(endpointResults.checkId, checkId), gte(endpointResults.at, new Date(from).toISOString())));
rows = found.map((r) => {
const timed = r.ok && r.ms !== null;
return { t: Date.parse(r.at), total: 1, ok: r.ok ? 1 : 0, msSum: timed ? (r.ms as number) : 0, msCount: timed ? 1 : 0, msMax: timed ? (r.ms as number) : 0 };
});
} else if (days <= KEEP_HOURLY_DAYS) {
source = "hourly";
const found = await db.select().from(endpointHourly).where(and(eq(endpointHourly.checkId, checkId), gte(endpointHourly.hour, new Date(from).toISOString())));
rows = found.map((r) => ({ t: Date.parse(r.hour), total: r.total, ok: r.ok, msSum: r.msSum, msCount: r.msCount, msMax: r.msMax }));
} else {
source = "daily";
const found = await db.select().from(endpointDaily).where(and(eq(endpointDaily.checkId, checkId), gte(endpointDaily.day, new Date(from).toISOString().slice(0, 10))));
// A day has no record of its slowest answer; its average stands in for it.
rows = found.map((r) => ({ t: Date.parse(`${r.day}T00:00:00.000Z`), total: r.total, ok: r.ok, msSum: r.msSum, msCount: r.msCount, msMax: r.msCount > 0 ? Math.round(r.msSum / r.msCount) : 0 }));
}
const checks = rows.reduce((n, r) => n + r.total, 0);
const okCount = rows.reduce((n, r) => n + r.ok, 0);
const msCount = rows.reduce((n, r) => n + r.msCount, 0);
return {
days,
source,
points: bucketHistory(rows, from, to, days <= 2 ? 96 : days <= KEEP_HOURLY_DAYS ? 200 : 370),
availability: checks === 0 ? null : Math.round((okCount / checks) * 1000) / 10,
avgMs: msCount === 0 ? null : Math.round(rows.reduce((n, r) => n + r.msSum, 0) / msCount),
checks,
};
} }
// ─── What the history says ───────────────────────────────────────────────── // ─── What the history says ─────────────────────────────────────────────────
+2 -2
View File
@@ -19,7 +19,7 @@ import { getCachedBackupCoverage } from "./backupCoverage.js";
import { lastAttempt as lastSelfBackup, listSnapshots } from "./selfBackup.js"; import { lastAttempt as lastSelfBackup, listSnapshots } from "./selfBackup.js";
import { loadAcks, attentionCounts } from "./alertAcks.js"; import { loadAcks, attentionCounts } from "./alertAcks.js";
import { listIncidents } from "./incidents.js"; import { listIncidents } from "./incidents.js";
import { disksFillingSoon, getServerMetrics } from "./serverMetrics.js"; import { disksFillingSoon, getForecastSeries } from "./serverMetrics.js";
import { computeSecretStatus } from "./secretStatus.js"; import { computeSecretStatus } from "./secretStatus.js";
import { getSettings } from "./settingsStore.js"; import { getSettings } from "./settingsStore.js";
import { getUptime } from "./uptimeHistory.js"; import { getUptime } from "./uptimeHistory.js";
@@ -132,7 +132,7 @@ export async function buildMetrics(now: Date = new Date()): Promise<string> {
// Disks on a steady climb, from each server's own history: days until full at the present rate (left out where there is no steady trend). // Disks on a steady climb, from each server's own history: days until full at the present rate (left out where there is no steady trend).
try { try {
for (const s of serverRows) { for (const s of serverRows) {
for (const f of disksFillingSoon(await getServerMetrics(s.id, 14, now), 3650, 101)) { for (const f of disksFillingSoon(await getForecastSeries(s.id, now), 3650, 101)) {
out.add("homelab_server_disk_days_to_full", "gauge", "Days until a disk is full at its present rate of filling; only for disks with a steady climb.", f.daysToFull, { server: s.name, mount: f.mount }); out.add("homelab_server_disk_days_to_full", "gauge", "Days until a disk is full at its present rate of filling; only for disks with a steady climb.", f.daysToFull, { server: s.name, mount: f.mount });
} }
} }
+72
View File
@@ -0,0 +1,72 @@
/**
* The network equipment read from UniFi controllers: devices with their state, address, uptime and what they are connected through, the networks and the Wi-Fi
* names, and which servers are plugged into which device. Shared by the Network devices page and the read API.
*/
import { eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { integrations, networkDevices, networkSegments, networkServerLinks, servers } from "../db/schema.js";
import { dependentsOf, loadGraph, needsOfNode, nodeKey } from "./dependencies.js";
import { activeSubjects } from "./maintenance.js";
import { syncStatuses } from "./unifiSync.js";
export async function buildNetworkOverview() {
const [intRows, devices, segments, statuses, graph, silenced, linkRows, serverRows] = await Promise.all([
db.select({ id: integrations.id, name: integrations.name, enabled: integrations.enabled }).from(integrations).where(eq(integrations.type, "unifi")),
db.select().from(networkDevices),
db.select().from(networkSegments),
syncStatuses(),
loadGraph(),
activeSubjects(),
db.select().from(networkServerLinks),
db.select({ id: servers.id, name: servers.name }).from(servers),
]);
const serverName = new Map(serverRows.map((s) => [s.id, s.name]));
const intName = new Map(intRows.map((i) => [i.id, i.name]));
const byExternal = new Map(devices.map((d) => [`${d.integrationId}:${d.externalId}`, d]));
// The servers plugged into each device, by what the controller says is connected (see unifiSync.matchClientsToServers).
const plugged = new Map<number, { serverId: number; serverName: string; port: number | null; wired: boolean }[]>();
const serverLinks: { serverId: number; serverName: string; deviceId: number; deviceName: string; port: number | null; wired: boolean }[] = [];
for (const l of linkRows) {
const device = byExternal.get(`${l.integrationId}:${l.deviceExternalId}`);
const name = serverName.get(l.serverId);
if (!device || !name) continue;
plugged.set(device.id, [...(plugged.get(device.id) ?? []), { serverId: l.serverId, serverName: name, port: l.port, wired: l.wired }]);
serverLinks.push({ serverId: l.serverId, serverName: name, deviceId: device.id, deviceName: device.name, port: l.port, wired: l.wired });
}
return {
serverLinks,
integrations: intRows.map((i) => ({ id: i.id, name: i.name, enabled: i.enabled, status: statuses[i.id] ?? null })),
devices: devices
.map((d) => {
const key = nodeKey("device", d.id);
const uplink = d.uplinkExternalId ? byExternal.get(`${d.integrationId}:${d.uplinkExternalId}`) : undefined;
return {
id: d.id,
integrationId: d.integrationId,
integrationName: intName.get(d.integrationId) ?? "UniFi",
siteName: d.siteName,
name: d.name,
model: d.model,
kind: d.kind,
ip: d.ip,
mac: d.mac,
state: d.state,
uptimeSeconds: d.uptimeSeconds,
firmware: d.firmware,
firmwareUpdatable: d.firmwareUpdatable,
uplink: uplink ? { id: uplink.id, name: uplink.name } : null,
offlineSince: d.offlineSince,
lastOnlineAt: d.lastOnlineAt,
updatedAt: d.updatedAt,
// How many things depend on it (directly or through others), and how many it needs: what the dependency map says about it.
dependents: dependentsOf(graph.edges, key).length,
needs: needsOfNode(graph.edges, key).length,
inMaintenance: silenced.has(key),
servers: (plugged.get(d.id) ?? []).sort((a, b) => a.serverName.localeCompare(b.serverName)),
};
})
.sort((a, b) => a.name.localeCompare(b.name)),
networks: segments.filter((s) => s.kind === "network").map(({ kind: _k, ...s }) => ({ ...s, integrationName: intName.get(s.integrationId) ?? "UniFi" })).sort((a, b) => (a.vlanId ?? 0) - (b.vlanId ?? 0) || a.name.localeCompare(b.name)),
ssids: segments.filter((s) => s.kind === "ssid").map(({ kind: _k, ...s }) => ({ ...s, integrationName: intName.get(s.integrationId) ?? "UniFi" })).sort((a, b) => a.name.localeCompare(b.name)),
};
}
+163
View File
@@ -0,0 +1,163 @@
/**
* What the read API (/api/v1) says. Each of these is a deliberate, stable shape — not the app's own page payloads, which change with the pages — and only things
* any signed-in person can already see: no tokens, no secrets, no passwords, no settings. Dates are ISO 8601 in UTC; sizes are bytes; percentages are 0–100.
*/
import { eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { assets, endpointChecks, servers } from "../db/schema.js";
import { env } from "../env.js";
import { attentionCounts, loadAcks } from "./alertAcks.js";
import { getAlerts } from "./alerts.js";
import { loadStats } from "./endpointChecks.js";
import { describeTarget, listActiveWindows, listUpcomingWindows } from "./maintenance.js";
import { parseHostHealth } from "./hostHealth.js";
import { parsePendingUpdates } from "./pendingUpdates.js";
import { parseTags } from "./serverTags.js";
import { parseThresholds } from "./serverThresholds.js";
import { getSettings } from "./settingsStore.js";
import { serverStatus } from "./topology.js";
/** An address inside the app as a full address, for a script that has no idea where the app lives. */
export function absoluteUrl(path: string | null): string | null {
return path === null ? null : `${env.appBaseUrl.replace(/\/+$/, "")}${path.startsWith("/") ? "" : "/"}${path}`;
}
const json = <T>(text: string | null, fallback: T): T => {
if (!text) return fallback;
try {
return JSON.parse(text) as T;
} catch {
return fallback;
}
};
type ServerRow = typeof servers.$inferSelect;
export function serverV1(row: ServerRow, offlineMinutes: number, now: Date) {
const status = serverStatus(row, offlineMinutes, now);
const disks = json<{ mount: string; sizeBytes: number; usedBytes: number }[]>(row.disks, []);
const updates = parsePendingUpdates(row.pendingUpdates);
const health = parseHostHealth(row.hostHealth);
return {
id: row.id,
name: row.name,
hostname: row.hostname,
description: row.description,
os: row.osType,
tags: parseTags(row.tags),
ipAddresses: json<string[]>(row.ipAddresses, []),
// "online" while its agent has reported within its limit, "offline" after, "unknown" if it never has.
status: status === "ok" ? "online" : status === "bad" ? "offline" : "unknown",
lastSeenAt: row.lastSeenAt,
createdAt: row.createdAt,
agentVersion: row.agentVersion ?? null,
runsOnServerId: row.parentServerId ?? null,
hardware: { manufacturer: row.hwManufacturer ?? null, model: row.hwModel ?? null, serial: row.hwSerial ?? null },
cpu: { model: row.cpuModel, cores: row.cpuCores, loadPercent: row.cpuLoadPercent },
memory: { totalBytes: row.memTotalBytes, usedBytes: row.memUsedBytes },
disks: disks.map((d) => ({ mount: d.mount, sizeBytes: d.sizeBytes, usedBytes: d.usedBytes, usedPercent: d.sizeBytes > 0 ? Math.round((d.usedBytes / d.sizeBytes) * 1000) / 10 : null })),
updates: updates ? { manager: updates.manager, count: updates.count, security: updates.security ?? null, rebootRequired: !!updates.rebootRequired, reportedAt: updates.reportedAt ?? null } : null,
health: health ? { failedUnits: health.failedUnits?.length ?? 0, reportedAt: health.reportedAt ?? null } : null,
thresholds: parseThresholds(row.thresholds),
url: absoluteUrl(`/servers/${row.id}`),
};
}
export async function serversV1(now: Date = new Date()) {
const [rows, settings] = await Promise.all([db.select().from(servers).orderBy(servers.name), getSettings()]);
return rows.map((r) => serverV1(r, settings.healthChecks.serverOfflineMinutes, now));
}
export async function oneServerV1(id: number, now: Date = new Date()) {
const [row] = await db.select().from(servers).where(eq(servers.id, id)).limit(1);
if (!row) return null;
return serverV1(row, (await getSettings()).healthChecks.serverOfflineMinutes, now);
}
export async function alertsV1() {
const [report, acks] = await Promise.all([getAlerts(false), loadAcks()]);
const attention = attentionCounts(report.alerts, acks);
return {
generatedAt: report.generatedAt,
// What is on the page: those nobody has looked at, by severity, and how many somebody has.
needingAttention: { critical: attention.critical, warning: attention.warning, acknowledged: attention.acknowledged },
counts: report.counts,
couldntCheck: report.couldntCheck,
alerts: report.alerts.map((a) => {
const ack = acks.get(a.id);
return {
id: a.id,
severity: a.severity,
category: a.category,
source: a.source,
message: a.message,
url: absoluteUrl(a.link),
silenced: a.silenced,
flapping: !!a.flapping,
target: a.target,
causedBy: a.causedBy ?? null,
affects: a.affects ?? [],
acknowledgement: ack?.active ? { by: ack.ackedBy, at: ack.ackedAt, note: ack.note, until: ack.until, assignee: ack.assignee?.name ?? null } : null,
};
}),
};
}
export async function inventoryV1() {
const [rows, serverRows] = await Promise.all([db.select().from(assets).orderBy(assets.name), db.select({ id: servers.id, name: servers.name }).from(servers)]);
const serverName = new Map(serverRows.map((s) => [s.id, s.name]));
return rows.map((a) => ({
id: a.id,
name: a.name,
kind: a.kind,
manufacturer: a.manufacturer,
model: a.model,
serial: a.serial,
location: a.location,
rackUnit: a.rackUnit,
purchaseDate: a.purchaseDate,
purchasePrice: a.purchasePrice,
warrantyUntil: a.warrantyUntil,
endOfSupport: a.endOfSupport,
replacementCost: a.replacementCost,
powerWatts: a.powerWatts,
notes: a.notes,
server: a.serverId !== null && serverName.has(a.serverId) ? { id: a.serverId, name: serverName.get(a.serverId)! } : null,
updatedAt: a.updatedAt,
}));
}
export async function maintenanceV1(now: Date = new Date()) {
const shape = async (w: Awaited<ReturnType<typeof listActiveWindows>>[number]) => {
const target = await describeTarget(w.targetType, w.targetId);
return target ? { id: w.id, target: { type: w.targetType, id: w.targetId, name: target.name, kind: target.kind }, reason: w.reason, startsAt: w.startedAt, endsAt: w.endsAt, createdBy: w.createdBy } : null;
};
const active = (await Promise.all((await listActiveWindows(now)).map(shape))).filter((w): w is NonNullable<typeof w> => w !== null);
const upcoming = (await Promise.all((await listUpcomingWindows(now)).map(shape))).filter((w): w is NonNullable<typeof w> => w !== null);
return { active, upcoming };
}
export async function endpointsV1(now: Date = new Date()) {
const rows = await db.select().from(endpointChecks).orderBy(endpointChecks.name);
const stats = await loadStats(rows.map((r) => r.id), now);
return rows.map((r) => {
const st = stats.get(r.id);
return {
id: r.id,
name: r.name,
kind: r.kind,
target: r.target,
port: r.port,
enabled: r.enabled,
status: !r.enabled ? "paused" : r.lastOk === null ? "unknown" : r.lastOk ? "up" : "down",
lastCheckedAt: r.lastCheckedAt,
lastResponseMs: r.lastResponseMs,
lastMessage: r.lastOk === false ? r.lastMessage : null,
certificateExpiresAt: r.certExpiresAt,
uptime24hPercent: st?.uptime24h ?? null,
uptime7dPercent: st?.uptime7d ?? null,
averageResponseMs24h: st?.avgMs24h ?? null,
serverId: r.serverId,
};
});
}
+174 -19
View File
@@ -1,19 +1,30 @@
/** /**
* A short history of what each agent-reported server's load, memory and disks looked like, so a page can show a trend * A history of what each agent-reported server's load, memory and disks looked like, so a page can show a trend
* (and say how soon a filling disk will run out) instead of only the latest figure. * (and say how soon a filling disk will run out) instead of only the latest figure.
* *
* One sample is kept per server every ten minutes at most, however often its agent reports, for 35 days. Everything here is a * One sample is kept per server every ten minutes at most, however often its agent reports, for 35 days. Everything here is a
* percentage: CPU load (as the agent reports it), memory in use, and each disk's used share. * percentage: CPU load (as the agent reports it), memory in use, and each disk's used share.
*
* Beyond those 35 days the same figures are kept coarser: each sample also goes into its hour (kept four months) and its day (kept over two years), as a
* sum, a count, a lowest and a highest. A chart asks for a number of days and is answered from whichever is fine enough and still there: the samples up to
* 35 days, the hours up to 120, the days beyond. A year of a disk filling is then one point a day.
*/ */
import { and, desc, eq, gte, lt } from "drizzle-orm"; import { and, desc, eq, gte, lt, sql } from "drizzle-orm";
import { db } from "../db/client.js"; import { db } from "../db/client.js";
import { serverMetrics } from "../db/schema.js"; import { serverMetrics, serverMetricsRollup } from "../db/schema.js";
import { getInternalFlag, setInternalFlag } from "./settingsStore.js";
import type { IncomingSystemInfo } from "./taskSync.js"; import type { IncomingSystemInfo } from "./taskSync.js";
/** Reports closer together than this add no sample. */ /** Reports closer together than this add no sample. */
export const MIN_GAP_MS = 10 * 60_000; export const MIN_GAP_MS = 10 * 60_000;
export const RETENTION_DAYS = 35; export const RETENTION_DAYS = 35;
/** How long the hourly and daily figures are kept. */
export const HOURLY_KEEP_DAYS = 120;
export const DAILY_KEEP_DAYS = 800;
/** The longest stretch a chart may ask for. */
export const MAX_RANGE_DAYS = 365;
const DAY_MS = 24 * 3600_000; const DAY_MS = 24 * 3600_000;
const HOUR_MS = 3600_000;
export interface Sample { export interface Sample {
metric: string; metric: string;
@@ -39,6 +50,35 @@ export function samplesFromSystem(system: IncomingSystemInfo | null | undefined)
return out; return out;
} }
/** The start of the hour or day a moment falls in, as ISO. */
export const hourStart = (t: number | string) => new Date(Math.floor(new Date(t).getTime() / HOUR_MS) * HOUR_MS).toISOString();
export const dayStart = (t: number | string) => new Date(Math.floor(new Date(t).getTime() / DAY_MS) * DAY_MS).toISOString();
/** Adds samples to their hour and day. Never allowed to break recording the sample itself. */
async function addToRollups(serverId: number, samples: Sample[], at: Date): Promise<void> {
try {
for (const grain of ["h", "d"] as const) {
const bucket = grain === "h" ? hourStart(at.getTime()) : dayStart(at.getTime());
for (const s of samples) {
await db
.insert(serverMetricsRollup)
.values({ serverId, metric: s.metric, grain, at: bucket, sum: s.value, n: 1, min: s.value, max: s.value })
.onConflictDoUpdate({
target: [serverMetricsRollup.serverId, serverMetricsRollup.metric, serverMetricsRollup.grain, serverMetricsRollup.at],
set: {
sum: sql`${serverMetricsRollup.sum} + ${s.value}`,
n: sql`${serverMetricsRollup.n} + 1`,
min: sql`min(${serverMetricsRollup.min}, ${s.value})`,
max: sql`max(${serverMetricsRollup.max}, ${s.value})`,
},
});
}
}
} catch (err) {
console.error("[metrics] couldn't add to the hourly and daily figures:", err);
}
}
/** Records a report's figures, unless this server was sampled a moment ago. Returns whether anything was stored. */ /** Records a report's figures, unless this server was sampled a moment ago. Returns whether anything was stored. */
export async function recordServerMetrics(serverId: number, system: IncomingSystemInfo | null | undefined, now: Date = new Date()): Promise<boolean> { export async function recordServerMetrics(serverId: number, system: IncomingSystemInfo | null | undefined, now: Date = new Date()): Promise<boolean> {
const samples = samplesFromSystem(system); const samples = samplesFromSystem(system);
@@ -54,7 +94,32 @@ export async function recordServerMetrics(serverId: number, system: IncomingSyst
const at = now.toISOString(); const at = now.toISOString();
await db.insert(serverMetrics).values(samples.map((s) => ({ serverId, metric: s.metric, value: s.value, recordedAt: at }))); await db.insert(serverMetrics).values(samples.map((s) => ({ serverId, metric: s.metric, value: s.value, recordedAt: at })));
await addToRollups(serverId, samples, now);
await db.delete(serverMetrics).where(and(eq(serverMetrics.serverId, serverId), lt(serverMetrics.recordedAt, new Date(now.getTime() - RETENTION_DAYS * DAY_MS).toISOString()))); await db.delete(serverMetrics).where(and(eq(serverMetrics.serverId, serverId), lt(serverMetrics.recordedAt, new Date(now.getTime() - RETENTION_DAYS * DAY_MS).toISOString())));
await db.delete(serverMetricsRollup).where(and(eq(serverMetricsRollup.serverId, serverId), eq(serverMetricsRollup.grain, "h"), lt(serverMetricsRollup.at, new Date(now.getTime() - HOURLY_KEEP_DAYS * DAY_MS).toISOString())));
await db.delete(serverMetricsRollup).where(and(eq(serverMetricsRollup.serverId, serverId), eq(serverMetricsRollup.grain, "d"), lt(serverMetricsRollup.at, new Date(now.getTime() - DAILY_KEEP_DAYS * DAY_MS).toISOString())));
return true;
}
const BACKFILL_FLAG = "metricsRollupBackfilled";
/**
* The first time after the hourly and daily figures were added, builds them from the samples already kept (up to 35 days), so the longer ranges are not empty
* for weeks. A bucket is written from what the samples say, replacing what is there, so it is right however far it got before. Done once.
*/
export async function backfillMetricRollups(): Promise<boolean> {
if (await getInternalFlag(BACKFILL_FLAG)) return false;
for (const [grain, len] of [["h", 13], ["d", 10]] as const) {
const suffix = grain === "h" ? ":00:00.000Z" : "T00:00:00.000Z";
await db.run(sql`
INSERT INTO server_metrics_rollup (server_id, metric, grain, at, sum, n, min, max)
SELECT server_id, metric, ${grain}, substr(recorded_at, 1, ${len}) || ${suffix}, sum(value), count(*), min(value), max(value)
FROM server_metrics
GROUP BY server_id, metric, substr(recorded_at, 1, ${len})
ON CONFLICT (server_id, metric, grain, at) DO UPDATE SET sum = excluded.sum, n = excluded.n, min = excluded.min, max = excluded.max
`);
}
await setInternalFlag(BACKFILL_FLAG, new Date().toISOString());
return true; return true;
} }
@@ -62,6 +127,9 @@ export interface Point {
/** ISO time. */ /** ISO time. */
t: string; t: string;
v: number; v: number;
/** The lowest and highest figure in what this point stands for, when it stands for several (hourly and daily figures). */
lo?: number;
hi?: number;
} }
/** Averages points into at most `maxPoints` equal slices of [from, to], so a month of samples draws as a short line. */ /** Averages points into at most `maxPoints` equal slices of [from, to], so a month of samples draws as a short line. */
@@ -83,6 +151,42 @@ export function bucketPoints(points: { t: number; v: number }[], from: number, t
.map(([, b]) => ({ t: new Date(b.tSum / b.n).toISOString(), v: round1(b.sum / b.n) })); .map(([, b]) => ({ t: new Date(b.tSum / b.n).toISOString(), v: round1(b.sum / b.n) }));
} }
/** A row of the hourly or daily figures, with the moment it starts at as epoch ms. */
export interface RollupRow {
t: number;
sum: number;
n: number;
min: number;
max: number;
}
/** The average of what each row stands for. */
export function rollupAverages(rows: RollupRow[]): { t: number; v: number }[] {
return rows.filter((r) => r.n > 0).map((r) => ({ t: r.t, v: r.sum / r.n }));
}
/** Rows into at most `maxPoints` slices of [from, to]: the average of the samples in each (not of the rows), with the lowest and highest. */
export function bucketRollups(rows: RollupRow[], from: number, to: number, maxPoints: number): Point[] {
if (rows.length === 0 || to <= from) return [];
const size = Math.max((to - from) / maxPoints, 1);
const buckets = new Map<number, { sum: number; n: number; lo: number; hi: number; tSum: number; rows: number }>();
for (const r of rows) {
if (r.t < from || r.t > to || r.n <= 0) continue;
const key = Math.min(maxPoints - 1, Math.floor((r.t - from) / size));
const b = buckets.get(key) ?? { sum: 0, n: 0, lo: Infinity, hi: -Infinity, tSum: 0, rows: 0 };
b.sum += r.sum;
b.n += r.n;
b.lo = Math.min(b.lo, r.min);
b.hi = Math.max(b.hi, r.max);
b.tSum += r.t;
b.rows += 1;
buckets.set(key, b);
}
return [...buckets.entries()]
.sort((a, b) => a[0] - b[0])
.map(([, b]) => ({ t: new Date(b.tSum / b.rows).toISOString(), v: round1(b.sum / b.n), lo: round1(b.lo), hi: round1(b.hi) }));
}
export interface Trend { export interface Trend {
/** Change in the percentage per day, from a straight line through the points. */ /** Change in the percentage per day, from a straight line through the points. */
perDay: number; perDay: number;
@@ -175,35 +279,86 @@ function describe(metric: string): { kind: MetricSeries["kind"]; label: string }
const ORDER = { cpu: 0, mem: 1, disk: 2 } as const; const ORDER = { cpu: 0, mem: 1, disk: 2 } as const;
/** Every series recorded for a server over the last `days`, ready to draw. */ /** Which of the kept figures answers a stretch of `days`: the samples while they reach back that far, then the hours, then the days. */
export function sourceFor(days: number): "samples" | "hourly" | "daily" {
return days <= RETENTION_DAYS ? "samples" : days <= HOURLY_KEEP_DAYS ? "hourly" : "daily";
}
/** How many points a chart over `days` is drawn from at most. */
const pointsFor = (days: number) => (days <= RETENTION_DAYS ? 96 : days <= HOURLY_KEEP_DAYS ? 200 : MAX_RANGE_DAYS + 5);
/** The latest sample of each figure of a server, whatever range is asked for. */
async function latestSamples(serverId: number): Promise<Map<string, number>> {
const rows = await db.all<{ metric: string; value: number }>(
sql`SELECT metric, value FROM server_metrics WHERE id IN (SELECT max(id) FROM server_metrics WHERE server_id = ${serverId} GROUP BY metric)`,
);
return new Map(rows.map((r) => [r.metric, r.value]));
}
/** Every series recorded for a server over the last `days` (up to a year), ready to draw. */
export async function getServerMetrics(serverId: number, days: number, now: Date = new Date()): Promise<MetricSeries[]> { export async function getServerMetrics(serverId: number, days: number, now: Date = new Date()): Promise<MetricSeries[]> {
days = Math.min(MAX_RANGE_DAYS, Math.max(1, days));
const to = now.getTime(); const to = now.getTime();
const from = to - days * DAY_MS; const from = to - days * DAY_MS;
const rows = await db const source = sourceFor(days);
.select({ metric: serverMetrics.metric, value: serverMetrics.value, at: serverMetrics.recordedAt })
.from(serverMetrics)
.where(and(eq(serverMetrics.serverId, serverId), gte(serverMetrics.recordedAt, new Date(from).toISOString())))
.orderBy(serverMetrics.recordedAt);
const byMetric = new Map<string, { t: number; v: number }[]>(); // The figures, per metric, as { t, v } for a trend and as points for the chart.
for (const r of rows) { const raw = new Map<string, { t: number; v: number }[]>();
const list = byMetric.get(r.metric) ?? []; const points = new Map<string, Point[]>();
list.push({ t: Date.parse(r.at), v: r.value }); if (source === "samples") {
byMetric.set(r.metric, list); const rows = await db
.select({ metric: serverMetrics.metric, value: serverMetrics.value, at: serverMetrics.recordedAt })
.from(serverMetrics)
.where(and(eq(serverMetrics.serverId, serverId), gte(serverMetrics.recordedAt, new Date(from).toISOString())))
.orderBy(serverMetrics.recordedAt);
for (const r of rows) raw.set(r.metric, [...(raw.get(r.metric) ?? []), { t: Date.parse(r.at), v: r.value }]);
for (const [metric, list] of raw) points.set(metric, bucketPoints(list, from, to, pointsFor(days)));
} else {
const rows = await db
.select()
.from(serverMetricsRollup)
.where(and(eq(serverMetricsRollup.serverId, serverId), eq(serverMetricsRollup.grain, source === "hourly" ? "h" : "d"), gte(serverMetricsRollup.at, new Date(from).toISOString())))
.orderBy(serverMetricsRollup.at);
const byMetric = new Map<string, RollupRow[]>();
for (const r of rows) byMetric.set(r.metric, [...(byMetric.get(r.metric) ?? []), { t: Date.parse(r.at), sum: r.sum, n: r.n, min: r.min, max: r.max }]);
for (const [metric, list] of byMetric) {
raw.set(metric, rollupAverages(list));
points.set(metric, bucketRollups(list, from, to, pointsFor(days)));
}
} }
const latest = source === "samples" ? null : await latestSamples(serverId);
return [...byMetric.entries()] return [...raw.entries()]
.map(([metric, raw]) => { .map(([metric, list]) => {
const { kind, label } = describe(metric); const { kind, label } = describe(metric);
const newest = latest?.get(metric) ?? list[list.length - 1]?.v;
return { return {
metric, metric,
kind, kind,
label, label,
points: bucketPoints(raw, from, to, 96), points: points.get(metric) ?? [],
latest: raw[raw.length - 1]?.v ?? null, latest: newest === undefined ? null : source === "samples" ? newest : round1(newest),
// A disk filling is the thing worth forecasting; load and memory go up and down by the hour. // A disk filling is the thing worth forecasting; load and memory go up and down by the hour.
trend: kind === "disk" ? trendOf(raw) : null, trend: kind === "disk" ? trendOf(list) : null,
}; };
}) })
.sort((a, b) => ORDER[a.kind] - ORDER[b.kind] || a.label.localeCompare(b.label)); .sort((a, b) => ORDER[a.kind] - ORDER[b.kind] || a.label.localeCompare(b.label));
} }
/** How far back the longer look at a disk goes when the last two weeks say it is flat. */
export const LONG_FORECAST_DAYS = 90;
/**
* The series to forecast from: the last two weeks, as before — except that a disk those two weeks call flat is looked at again over the last
* ninety days, so a slow, steady climb (a point a week) is seen too. The longer trend replaces the short one only if it is really rising.
*/
export async function getForecastSeries(serverId: number, now: Date = new Date()): Promise<MetricSeries[]> {
const short = await getServerMetrics(serverId, 14, now);
if (!short.some((s) => s.kind === "disk" && (!s.trend || s.trend.daysToFull === null))) return short;
const long = await getServerMetrics(serverId, LONG_FORECAST_DAYS, now);
return short.map((s) => {
if (s.kind !== "disk" || (s.trend && s.trend.daysToFull !== null)) return s;
const longer = long.find((l) => l.metric === s.metric);
return longer?.trend && longer.trend.daysToFull !== null ? { ...s, trend: longer.trend } : s;
});
}
+2 -2
View File
@@ -16,7 +16,7 @@ import { describeTarget, listUpcomingWindows } from "./maintenance.js";
import { notify, notifyNow } from "./notify.js"; import { notify, notifyNow } from "./notify.js";
import { parsePendingUpdates } from "./pendingUpdates.js"; import { parsePendingUpdates } from "./pendingUpdates.js";
import { computeSecretStatus } from "./secretStatus.js"; import { computeSecretStatus } from "./secretStatus.js";
import { disksFillingSoon, getServerMetrics } from "./serverMetrics.js"; import { disksFillingSoon, getForecastSeries } from "./serverMetrics.js";
import { diskLimit, effectiveThresholds, parseThresholds } from "./serverThresholds.js"; import { diskLimit, effectiveThresholds, parseThresholds } from "./serverThresholds.js";
import { getSettings } from "./settingsStore.js"; import { getSettings } from "./settingsStore.js";
import { getUptime } from "./uptimeHistory.js"; import { getUptime } from "./uptimeHistory.js";
@@ -163,7 +163,7 @@ export async function buildDigest(now: Date = new Date()): Promise<Digest> {
const own = parseThresholds(s.thresholds); const own = parseThresholds(s.thresholds);
const forecastDays = effectiveThresholds(settings.healthChecks, own).diskForecastDays; const forecastDays = effectiveThresholds(settings.healthChecks, own).diskForecastDays;
if (!(forecastDays > 0)) continue; if (!(forecastDays > 0)) continue;
for (const f of disksFillingSoon(await getServerMetrics(s.id, 14, now), forecastDays, (mount) => diskLimit(own, mount, diskUsagePercent))) { for (const f of disksFillingSoon(await getForecastSeries(s.id, now), forecastDays, (mount) => diskLimit(own, mount, diskUsagePercent))) {
lines.push(`- ${s.name}: ${f.mount} is ${Math.round(f.latest)}% full and filling by about ${f.perDay.toFixed(1)} points a day — full in about ${plural(f.daysToFull, "day")}`); lines.push(`- ${s.name}: ${f.mount} is ${Math.round(f.latest)}% full and filling by about ${f.perDay.toFixed(1)} points a day — full in about ${plural(f.daysToFull, "day")}`);
} }
} }
+249
View File
@@ -0,0 +1,249 @@
/**
* Longer history: server figures and endpoint answer times kept by the hour and the day beyond the days they are kept in full, and drawn from whichever is
* fine enough for the range asked for, up to a year.
*
* Run with: npm test --workspace server
*/
import { test, describe, before, after } from "node:test";
import assert from "node:assert/strict";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { AddressInfo } from "node:net";
import type { Server } from "node:http";
const dir = mkdtempSync(join(tmpdir(), "hm-history-"));
process.env.DATABASE_PATH = join(dir, "test.sqlite");
process.env.SESSION_DIR = join(dir, "sessions");
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
process.env.HEALTH_STARTUP_GRACE_MS = "0";
const express = (await import("express")).default;
const { db } = await import("../src/db/client.js");
const { users, servers, serverMetrics, serverMetricsRollup, endpointChecks, endpointResults, endpointHourly, endpointDaily } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const metrics = await import("../src/services/serverMetrics.js");
const checks = await import("../src/services/endpointChecks.js");
const { serversRouter } = await import("../src/routes/servers.js");
const { endpointsRouter } = await import("../src/routes/endpoints.js");
const { eq, and } = await import("drizzle-orm");
await runMigrations();
const DAY = 24 * 3600_000;
const HOUR = 3600_000;
const NOW = new Date(Math.floor(Date.now() / HOUR) * HOUR + 20 * 60_000); // twenty minutes into an hour
const ago = (days: number, extraMs = 0) => new Date(NOW.getTime() - days * DAY + extraMs);
const system = (cpu: number, disk: number) => ({ cpu: { load_percent: cpu }, memory: { total_bytes: 1000, used_bytes: 500 }, disks: [{ mount: "/", size_bytes: 100, used_bytes: disk }] }) as never;
let serverId = 0;
let checkId = 0;
before(async () => {
await db.insert(users).values([{ oidcSub: "ada", name: "Ada", role: "admin" }]);
serverId = (await db.insert(servers).values({ name: "web", apiTokenHash: "w", apiTokenPrefix: "w", lastSeenAt: NOW.toISOString() }).returning({ id: servers.id }))[0].id;
checkId = (await db.insert(endpointChecks).values({ name: "Site", kind: "tcp", target: "127.0.0.1", port: 1 }).returning({ id: endpointChecks.id }))[0].id;
});
after(() => {
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows may still hold the database file
}
});
describe("the hourly and daily figures of a server", () => {
test("which figures answer which range: the samples while they reach, then the hours, then the days", () => {
assert.deepEqual([1, 7, 35, 36, 120, 121, 365].map(metrics.sourceFor), ["samples", "samples", "samples", "hourly", "hourly", "daily", "daily"]);
});
test("a sample goes into its hour and its day, and the next one in the same hour is added to it, with the lowest and highest kept", async () => {
const t = new Date(ago(0).getTime() - 10 * 60_000); // ten minutes into the hour
assert.equal(await metrics.recordServerMetrics(serverId, system(10, 50), t), true);
assert.equal(await metrics.recordServerMetrics(serverId, system(30, 52), new Date(t.getTime() + 11 * 60_000)), true);
const cpuHour = (await db.select().from(serverMetricsRollup).where(and(eq(serverMetricsRollup.serverId, serverId), eq(serverMetricsRollup.metric, "cpu"), eq(serverMetricsRollup.grain, "h"))))[0];
assert.deepEqual([cpuHour.n, cpuHour.sum, cpuHour.min, cpuHour.max, cpuHour.at], [2, 40, 10, 30, metrics.hourStart(t.getTime())]);
const cpuDay = (await db.select().from(serverMetricsRollup).where(and(eq(serverMetricsRollup.serverId, serverId), eq(serverMetricsRollup.metric, "cpu"), eq(serverMetricsRollup.grain, "d"))))[0];
assert.deepEqual([cpuDay.n, cpuDay.at], [2, metrics.dayStart(t.getTime())]);
});
test("a hundred days of a disk filling: seven days come from the samples, ninety from the hours, a year from the days", async () => {
// one sample a day, climbing 0.3 points a day, oldest first (the way agents report)
const hist = (await db.insert(servers).values({ name: "hist", apiTokenHash: "h", apiTokenPrefix: "h", lastSeenAt: NOW.toISOString() }).returning({ id: servers.id }))[0].id;
for (let d = 100; d >= 1; d--) await metrics.recordServerMetrics(hist, system(20, 30 + (100 - d) * 0.3), ago(d));
const week = await metrics.getServerMetrics(hist, 7, NOW);
const disk7 = week.find((s) => s.metric === "disk:/")!;
assert.ok(disk7.points.length > 0 && disk7.points.every((p) => p.lo === undefined), "from the samples: no band");
const ninety = await metrics.getServerMetrics(hist, 90, NOW);
const disk90 = ninety.find((s) => s.metric === "disk:/")!;
assert.ok(disk90.points.length >= 85, `about a point a day (got ${disk90.points.length})`);
assert.ok(disk90.points.every((p) => p.lo !== undefined && p.hi !== undefined && p.lo <= p.v && p.v <= p.hi), "from the hours: each has a lowest and highest");
assert.ok(disk90.trend && Math.abs(disk90.trend.perDay - 0.3) < 0.05, "and the trend reaches back all ninety days");
assert.ok(disk90.trend!.spanDays > 85);
const year = await metrics.getServerMetrics(hist, 365, NOW);
const diskYear = year.find((s) => s.metric === "disk:/")!;
assert.ok(diskYear.points.length >= 99 && diskYear.points.length <= 370);
assert.equal(diskYear.latest, 30 + 99 * 0.3 > 100 ? 100 : Math.round((30 + 99 * 0.3) * 10) / 10, "the latest figure is the latest sample, not an average");
});
test("a range is never longer than a year, and never shorter than a day", async () => {
const huge = await metrics.getServerMetrics(serverId, 9999, NOW);
assert.ok(huge.length > 0);
const tiny = await metrics.getServerMetrics(serverId, 0, NOW);
assert.ok(Array.isArray(tiny));
});
test("a slow, steady climb that two weeks call flat is seen over ninety days", async () => {
const other = (await db.insert(servers).values({ name: "slow", apiTokenHash: "s", apiTokenPrefix: "s", lastSeenAt: NOW.toISOString() }).returning({ id: servers.id }))[0].id;
// 0.07 a day is under what two weeks of data round to being worth a forecast once the noise is in, but over ninety days it is plainly a climb
for (let d = 90; d >= 1; d--) await metrics.recordServerMetrics(other, system(10, 40 + (90 - d) * 0.07 + (d % 2 ? 0.01 : -0.01)), ago(d));
const series = await metrics.getForecastSeries(other, NOW);
const disk = series.find((s) => s.metric === "disk:/")!;
assert.ok(disk.trend && disk.trend.daysToFull !== null, "there is a forecast");
assert.ok(disk.trend!.fit > 0.9);
});
test("the hourly and daily figures are kept so long and no longer", async () => {
const old = (await db.insert(servers).values({ name: "old", apiTokenHash: "o", apiTokenPrefix: "o" }).returning({ id: servers.id }))[0].id;
await db.insert(serverMetricsRollup).values([
{ serverId: old, metric: "cpu", grain: "h", at: ago(metrics.HOURLY_KEEP_DAYS + 3).toISOString(), sum: 1, n: 1, min: 1, max: 1 },
{ serverId: old, metric: "cpu", grain: "d", at: ago(metrics.HOURLY_KEEP_DAYS + 3).toISOString(), sum: 1, n: 1, min: 1, max: 1 },
{ serverId: old, metric: "cpu", grain: "d", at: ago(metrics.DAILY_KEEP_DAYS + 3).toISOString(), sum: 1, n: 1, min: 1, max: 1 },
]);
await metrics.recordServerMetrics(old, system(5, 5), NOW);
const left = await db.select().from(serverMetricsRollup).where(and(eq(serverMetricsRollup.serverId, old), eq(serverMetricsRollup.metric, "cpu")));
assert.deepEqual(left.map((r) => r.grain).sort(), ["d", "d", "h"], "the old hour is gone, the old day within two years stays, the one beyond is gone, and today's two are there");
assert.equal(left.filter((r) => r.grain === "h").length, 1);
});
test("the first time, the hours and days are built from the samples already kept — once, and exactly", async () => {
const legacy = (await db.insert(servers).values({ name: "legacy", apiTokenHash: "l", apiTokenPrefix: "l" }).returning({ id: servers.id }))[0].id;
const base = new Date("2026-03-10T10:05:00.000Z").getTime();
await db.insert(serverMetrics).values([
{ serverId: legacy, metric: "cpu", value: 10, recordedAt: new Date(base).toISOString() },
{ serverId: legacy, metric: "cpu", value: 20, recordedAt: new Date(base + 10 * 60_000).toISOString() },
{ serverId: legacy, metric: "cpu", value: 60, recordedAt: new Date(base + HOUR).toISOString() },
]);
assert.equal(await metrics.backfillMetricRollups(), true);
assert.equal(await metrics.backfillMetricRollups(), false, "done once");
const rows = await db.select().from(serverMetricsRollup).where(eq(serverMetricsRollup.serverId, legacy));
const hours = rows.filter((r) => r.grain === "h").sort((a, b) => a.at.localeCompare(b.at));
assert.deepEqual(hours.map((r) => [r.at, r.n, r.sum, r.min, r.max]), [["2026-03-10T10:00:00.000Z", 2, 30, 10, 20], ["2026-03-10T11:00:00.000Z", 1, 60, 60, 60]]);
const days = rows.filter((r) => r.grain === "d");
assert.deepEqual(days.map((r) => [r.at, r.n, r.sum, r.min, r.max]), [["2026-03-10T00:00:00.000Z", 3, 90, 10, 60]]);
});
});
describe("how a check has done over a long time", () => {
const probe = (ok: boolean, ms: number | null) => async () => ({ ok, ms, message: ok ? "open" : "refused" });
const row = () => db.select().from(endpointChecks).where(eq(endpointChecks.id, checkId)).then((r) => r[0]);
test("each answer goes into its hour, and the average, the slowest and how many answered are kept", async () => {
const t = ago(5, -45 * 60_000); // five days ago, a little into an hour
await checks.runCheck(await row(), t, probe(true, 100));
await checks.runCheck(await row(), new Date(t.getTime() + 60_000), probe(true, 300));
await checks.runCheck(await row(), new Date(t.getTime() + 120_000), probe(false, null));
const hour = (await db.select().from(endpointHourly).where(eq(endpointHourly.checkId, checkId)))[0];
assert.deepEqual([hour.total, hour.ok, hour.msSum, hour.msCount, hour.msMax], [3, 2, 400, 2, 300]);
});
test("bucketing adds the figures up, so a slice is as true as the checks in it", () => {
const rows = [
{ t: 0, total: 10, ok: 10, msSum: 1000, msCount: 10, msMax: 400 },
{ t: 1000, total: 10, ok: 5, msSum: 1000, msCount: 5, msMax: 900 },
{ t: 9000, total: 4, ok: 4, msSum: 400, msCount: 4, msMax: 100 },
];
const points = checks.bucketHistory(rows, 0, 10_000, 2);
assert.deepEqual(points.map((p) => [p.availability, p.avgMs, p.maxMs, p.checks]), [[75, 133, 900, 20], [100, 100, 100, 4]]);
assert.deepEqual(checks.bucketHistory([], 0, 10, 2), []);
assert.equal(checks.bucketHistory([{ t: 0, total: 1, ok: 0, msSum: 0, msCount: 0, msMax: 0 }], 0, 10, 1)[0].avgMs, null, "no timed answer, no average");
});
test("a day is drawn from the results, a month from the hours, and half a year from the days", async () => {
// some results of today, kept in full
await db.insert(endpointResults).values([
{ checkId, at: ago(0, -30 * 60_000).toISOString(), ok: true, ms: 80, message: "open" },
{ checkId, at: ago(0, -20 * 60_000).toISOString(), ok: false, ms: null, message: "refused" },
]);
// and daily figures for the last 200 days
for (let d = 200; d >= 7; d--) {
const day = ago(d).toISOString().slice(0, 10);
await db.insert(endpointDaily).values({ checkId, day, total: 288, ok: d % 50 === 0 ? 250 : 288, msSum: 288 * 40, msCount: 288 }).onConflictDoNothing();
}
const day = await checks.getEndpointHistory(checkId, 1, NOW);
assert.equal(day.source, "results");
assert.deepEqual([day.checks, day.availability, day.avgMs], [2, 50, 80]);
const month = await checks.getEndpointHistory(checkId, 30, NOW);
assert.equal(month.source, "hourly");
assert.equal(month.checks, 3, "the three asked five days ago");
assert.equal(month.availability, 66.7);
assert.equal(month.points[0].maxMs, 300);
const half = await checks.getEndpointHistory(checkId, 200, NOW);
assert.equal(half.source, "daily");
assert.ok(half.points.length >= 150 && half.points.length <= 200, "a point a day");
assert.ok(half.availability !== null && half.availability < 100 && half.availability > 98);
assert.equal(half.avgMs, 40);
});
test("the first time, the hours are built from the results still kept — once", async () => {
const fresh = (await db.insert(endpointChecks).values({ name: "Other", kind: "tcp", target: "127.0.0.1", port: 2 }).returning({ id: endpointChecks.id }))[0].id;
await db.insert(endpointResults).values([
{ checkId: fresh, at: "2026-03-10T10:05:00.000Z", ok: true, ms: 50, message: "" },
{ checkId: fresh, at: "2026-03-10T10:35:00.000Z", ok: true, ms: 150, message: "" },
{ checkId: fresh, at: "2026-03-10T10:45:00.000Z", ok: false, ms: null, message: "" },
]);
assert.equal(await checks.backfillEndpointHourly(), true);
assert.equal(await checks.backfillEndpointHourly(), false);
const [hour] = await db.select().from(endpointHourly).where(eq(endpointHourly.checkId, fresh));
assert.deepEqual([hour.hour, hour.total, hour.ok, hour.msSum, hour.msCount, hour.msMax], ["2026-03-10T10:00:00.000Z", 3, 2, 200, 2, 150]);
});
test("the hours are pruned after four months", async () => {
await db.insert(endpointHourly).values({ checkId, hour: ago(checks.KEEP_HOURLY_DAYS + 5).toISOString(), total: 1, ok: 1, msSum: 1, msCount: 1, msMax: 1 });
await checks.pruneResults(NOW);
const left = await db.select().from(endpointHourly).where(eq(endpointHourly.checkId, checkId));
assert.ok(left.every((r) => Date.parse(r.hour) > NOW.getTime() - checks.KEEP_HOURLY_DAYS * DAY));
});
});
describe("over the routes", () => {
let app: Server;
let base = "";
before(async () => {
const a = express();
a.use(express.json());
a.use((req, _res, next) => {
(req as unknown as { session: unknown }).session = { user: { sub: "ada" } };
next();
});
a.use("/api/servers", serversRouter);
a.use("/api/endpoints", endpointsRouter);
app = await new Promise<Server>((resolve) => {
const s = a.listen(0, "127.0.0.1", () => resolve(s));
});
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api`;
});
after(() => app.close());
test("a server's metrics can be asked for a year, and no more", async () => {
const year = (await (await fetch(`${base}/servers/${serverId}/metrics?days=365`)).json()) as any;
assert.equal(year.days, 365);
assert.ok(year.series.length > 0);
const more = (await (await fetch(`${base}/servers/${serverId}/metrics?days=5000`)).json()) as any;
assert.equal(more.days, 365);
const none = (await (await fetch(`${base}/servers/${serverId}/metrics`)).json()) as any;
assert.equal(none.days, 7);
});
test("a check's history: availability and answer times for a range, 404 for one that is not there", async () => {
const body = (await (await fetch(`${base}/endpoints/${checkId}/history?days=30`)).json()) as any;
assert.deepEqual([body.check.name, body.days, body.source, body.checks], ["Site", 30, "hourly", 5]); // the three asked five days ago, and the two results of today that the backfill above counted
assert.equal((await fetch(`${base}/endpoints/999999/history`)).status, 404);
assert.equal((await fetch(`${base}/endpoints/abc/history`)).status, 400);
assert.equal(((await (await fetch(`${base}/endpoints/${checkId}/history?days=99999`)).json()) as any).days, 365);
});
});
+279
View File
@@ -0,0 +1,279 @@
/**
* The read API and personal tokens: who may make a token, that the secret is shown once and only its hash kept, what a token can read (and that it can only
* read), and when it stops working.
*
* Run with: npm test --workspace server
*/
import { test, describe, before, after } from "node:test";
import assert from "node:assert/strict";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { AddressInfo } from "node:net";
import type { Server } from "node:http";
const dir = mkdtempSync(join(tmpdir(), "hm-readapi-"));
process.env.DATABASE_PATH = join(dir, "test.sqlite");
process.env.SESSION_DIR = join(dir, "sessions");
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
process.env.HEALTH_STARTUP_GRACE_MS = "0";
process.env.APP_BASE_URL = "https://hm.example.lan";
const express = (await import("express")).default;
const { db } = await import("../src/db/client.js");
const { users, servers, assets, apiTokens, endpointChecks, endpointResults, alertIncidents, maintenanceWindows, auditLog } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const { createApp } = await import("../src/app.js");
const { apiTokensRouter } = await import("../src/routes/apiTokens.js");
const { setAck } = await import("../src/services/alertAcks.js");
const { invalidateAlertsCache } = await import("../src/services/alerts.js");
const { startOrExtendWindow } = await import("../src/services/maintenance.js");
const { eq } = await import("drizzle-orm");
await runMigrations();
const HOUR = 3600_000;
let app: Server;
let tokensApp: Server;
let base = "";
let tokensBase = "";
let who = "ada";
const ids: Record<string, number> = {};
const api = (path: string, secret: string | null, init: RequestInit = {}) =>
fetch(`${base}/api/v1${path}`, { ...init, headers: { ...(secret ? { authorization: `Bearer ${secret}` } : {}), ...(init.headers ?? {}) } });
const mine = (path: string, init: RequestInit = {}) => fetch(`${tokensBase}${path}`, { ...init, headers: { "content-type": "application/json", ...(init.headers ?? {}) } });
const make = async (label: string, extra: Record<string, unknown> = {}) => {
const res = await mine("", { method: "POST", body: JSON.stringify({ label, ...extra }) });
return { status: res.status, body: (await res.json()) as any };
};
before(async () => {
const rows = await db
.insert(users)
.values([
{ oidcSub: "ada", name: "Ada", role: "admin" },
{ oidcSub: "vic", name: "Vic", email: "vic@example.lan", role: "viewer" },
])
.returning({ id: users.id, oidcSub: users.oidcSub });
for (const r of rows) ids[r.oidcSub] = r.id;
// two servers (one reporting, one gone quiet), an alert on the quiet one, a piece of hardware, a check, an incident and a maintenance window
ids.web = (await db.insert(servers).values({ name: "web", apiTokenHash: "SECRET-HASH-WEB", apiTokenPrefix: "w", tags: JSON.stringify(["lab"]), ipAddresses: JSON.stringify(["10.0.0.5"]), lastSeenAt: new Date().toISOString(), cpuLoadPercent: 12, memTotalBytes: 1000, memUsedBytes: 400, disks: JSON.stringify([{ mount: "/", sizeBytes: 100, usedBytes: 40 }]) }).returning({ id: servers.id }))[0].id;
ids.db = (await db.insert(servers).values({ name: "db", apiTokenHash: "SECRET-HASH-DB", apiTokenPrefix: "d", lastSeenAt: new Date(Date.now() - 6 * HOUR).toISOString() }).returning({ id: servers.id }))[0].id;
await db.insert(assets).values({ name: "Rack switch", kind: "network", location: "Rack A", purchasePrice: 120, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() });
ids.check = (await db.insert(endpointChecks).values({ name: "Site", kind: "tcp", target: "127.0.0.1", port: 1, lastOk: true, lastCheckedAt: new Date().toISOString(), lastResponseMs: 12 }).returning({ id: endpointChecks.id }))[0].id;
await db.insert(endpointResults).values({ checkId: ids.check, at: new Date().toISOString(), ok: true, ms: 12, message: "open" });
await db.insert(alertIncidents).values({ alertKey: "offline:offline:server:1", severity: "critical", peakSeverity: "critical", category: "offline", source: "Server", message: "old", openedAt: new Date(Date.now() - 9 * HOUR).toISOString(), resolvedAt: new Date(Date.now() - 8 * HOUR).toISOString(), lastSeenAt: new Date().toISOString() });
await startOrExtendWindow("server", ids.web, 60, "Patching", "Ada");
await setAck({ alertId: `offline:offline:server:${ids.db}`, note: "On it", assigneeId: ids.ada, hours: 4, actor: "Ada" });
invalidateAlertsCache();
app = await new Promise<Server>((resolve) => {
const s = createApp().listen(0, "127.0.0.1", () => resolve(s));
});
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}`;
const a = express();
a.use(express.json());
a.use((req, _res, next) => {
(req as unknown as { session: unknown }).session = { user: { sub: who } };
next();
});
a.use("/", apiTokensRouter);
tokensApp = await new Promise<Server>((resolve) => {
const s = a.listen(0, "127.0.0.1", () => resolve(s));
});
tokensBase = `http://127.0.0.1:${(tokensApp.address() as AddressInfo).port}`;
});
after(() => {
app.close();
tokensApp.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows may still hold the database file
}
});
describe("making and keeping tokens", () => {
let secret = "";
let tokenId = 0;
test("anyone signed in makes their own; the secret is in the answer once, and only a hash is kept", async () => {
who = "vic";
const made = await make("Home Assistant", { expiresInDays: 90 });
assert.equal(made.status, 201);
secret = made.body.secret;
tokenId = made.body.token.id;
assert.match(secret, /^hlm_p_[A-Za-z0-9_-]{20,}$/);
assert.ok(made.body.token.expiresAt, "it ends");
const stored = (await db.select().from(apiTokens).where(eq(apiTokens.id, tokenId)))[0];
assert.notEqual(stored.tokenHash, secret);
assert.equal(stored.tokenHash.length, 64);
assert.equal(stored.userId, ids.vic);
const list = await (await mine("")).json();
assert.deepEqual(list.tokens.map((t: any) => t.label), ["Home Assistant"]);
assert.ok(!JSON.stringify(list).includes(secret) && !JSON.stringify(list).includes(stored.tokenHash), "the list never has the secret or the hash");
});
test("a token needs a name, and the end is 30, 90 or 365 days or none", async () => {
assert.equal((await make("")).status, 400);
assert.equal((await make("x", { expiresInDays: 7 })).status, 400);
const forever = await make("No end");
assert.equal(forever.status, 201);
assert.equal(forever.body.token.expiresAt, null);
await mine(`/${forever.body.token.id}`, { method: "DELETE" });
});
test("a person has at most ten", async () => {
who = "ada";
for (let i = 0; i < 10; i++) assert.equal((await make(`t${i}`)).status, 201);
const eleventh = await make("one too many");
assert.equal(eleventh.status, 400);
assert.match(eleventh.body.message, /already 10/);
for (const t of (await (await mine("")).json()).tokens) await mine(`/${t.id}`, { method: "DELETE" });
});
test("somebody else's token is not yours to see or remove", async () => {
who = "ada";
assert.equal(((await (await mine("")).json()) as any).tokens.length, 0, "Ada sees none of Vic's");
assert.equal((await mine(`/${tokenId}`, { method: "DELETE" })).status, 404);
assert.equal((await api("/me", secret)).status, 200, "and it still works");
});
test("removing your own stops it at once", async () => {
who = "vic";
assert.equal((await api("/me", secret)).status, 200);
assert.equal((await mine(`/${tokenId}`, { method: "DELETE" })).status, 204);
assert.equal((await api("/me", secret)).status, 401);
const entries = (await db.select().from(auditLog)).filter((e) => e.category === "api_token");
assert.ok(entries.some((e) => e.action === "create") && entries.some((e) => e.action === "delete"), "making and removing a token is written down");
assert.ok(entries.every((e) => !JSON.stringify(e).includes("hlm_p_")), "and the secret is not");
});
});
describe("what a token can read", () => {
let secret = "";
before(async () => {
who = "vic";
secret = (await make("Reader")).body.secret;
});
test("no token, a wrong one, and one in the address are all the same 401", async () => {
for (const res of [await api("/servers", null), await api("/servers", "hlm_p_wrongwrongwrongwrongwrong"), await fetch(`${base}/api/v1/servers?token=${secret}`)]) {
assert.equal(res.status, 401);
assert.equal(res.headers.get("www-authenticate"), 'Bearer realm="homelab-manager"');
assert.equal(((await res.json()) as any).error, "unauthorized");
}
});
test("it only reads: any other verb is refused, even with a good token", async () => {
for (const method of ["POST", "PUT", "PATCH", "DELETE"]) {
const res = await api("/servers", secret, { method });
assert.equal(res.status, 405, method);
assert.equal(res.headers.get("allow"), "GET, HEAD");
}
});
test("who the token is", async () => {
const body = (await (await api("/me", secret)).json()) as any;
assert.deepEqual([body.user.name, body.user.role, body.token.label], ["Vic", "viewer", "Reader"]);
});
test("servers: a stable shape, no token hashes, the state worked out, filtered by tag and status", async () => {
const res = await api("/servers", secret);
assert.equal(res.headers.get("cache-control"), "no-store");
const text = await res.text();
assert.ok(!text.includes("SECRET-HASH") && !text.includes("apiToken"), "nothing of the servers' own tokens");
const body = JSON.parse(text) as any;
const web = body.servers.find((s: any) => s.name === "web");
assert.deepEqual([web.status, web.tags, web.ipAddresses, web.cpu.loadPercent, web.disks[0].usedPercent, web.url], ["online", ["lab"], ["10.0.0.5"], 12, 40, `https://hm.example.lan/servers/${ids.web}`]);
assert.equal(body.servers.find((s: any) => s.name === "db").status, "offline");
assert.deepEqual(((await (await api("/servers?tag=lab", secret)).json()) as any).servers.map((s: any) => s.name), ["web"]);
assert.deepEqual(((await (await api("/servers?status=offline", secret)).json()) as any).servers.map((s: any) => s.name), ["db"]);
assert.equal((await api(`/servers/${ids.web}`, secret)).status, 200);
assert.equal((await api("/servers/99999", secret)).status, 404);
assert.equal((await api("/servers/abc", secret)).status, 400);
});
test("a server's metrics, for up to a year", async () => {
const body = (await (await api(`/servers/${ids.web}/metrics?days=9999`, secret)).json()) as any;
assert.equal(body.days, 365);
assert.ok(Array.isArray(body.series));
});
test("alerts: what is wrong, with whether somebody is on it, filterable; addresses are whole", async () => {
const body = (await (await api("/alerts", secret)).json()) as any;
const offline = body.alerts.find((a: any) => a.id === `offline:offline:server:${ids.db}`);
assert.ok(offline, "the quiet server is raised");
assert.deepEqual([offline.severity, offline.acknowledgement.by, offline.acknowledgement.assignee, offline.acknowledgement.note], ["critical", "Ada", "Ada", "On it"]);
assert.equal(offline.url, `https://hm.example.lan/servers/${ids.db}`);
assert.equal(body.needingAttention.acknowledged, 1);
assert.equal(((await (await api("/alerts?acknowledged=false", secret)).json()) as any).alerts.some((a: any) => a.id === offline.id), false);
assert.equal(((await (await api("/alerts?severity=info", secret)).json()) as any).alerts.length, 0);
});
test("incidents, inventory, network, endpoints and maintenance", async () => {
const incidents = (await (await api("/incidents?status=resolved", secret)).json()) as any;
assert.equal(incidents.incidents.length, 1);
assert.equal(((await (await api(`/incidents/${incidents.incidents[0].id}`, secret)).json()) as any).incident?.id ?? incidents.incidents[0].id, incidents.incidents[0].id);
const open = ((await (await api("/incidents?status=open", secret)).json()) as any).incidents;
assert.deepEqual(open.map((i: any) => i.alertKey), [`offline:offline:server:${ids.db}`], "the quiet server's alert is an incident that is still open");
const inventory = (await (await api("/inventory", secret)).json()) as any;
assert.deepEqual([inventory.assets[0].name, inventory.assets[0].location, inventory.assets[0].purchasePrice], ["Rack switch", "Rack A", 120]);
const network = (await (await api("/network", secret)).json()) as any;
assert.deepEqual(Object.keys(network).sort(), ["devices", "networks", "serverLinks", "ssids"]);
const endpoints = (await (await api("/endpoints", secret)).json()) as any;
assert.deepEqual([endpoints.endpoints[0].name, endpoints.endpoints[0].status, endpoints.endpoints[0].lastResponseMs], ["Site", "up", 12]);
const history = (await (await api(`/endpoints/${ids.check}/history?days=1`, secret)).json()) as any;
assert.deepEqual([history.check.name, history.source, history.checks], ["Site", "results", 1]);
assert.equal((await api("/endpoints/99999/history", secret)).status, 404);
const maintenance = (await (await api("/maintenance", secret)).json()) as any;
assert.deepEqual([maintenance.active.length, maintenance.active[0].target.name, maintenance.active[0].reason], [1, "web", "Patching"]);
});
test("an address that is not there says so, and the index lists them", async () => {
const res = await api("/nothing", secret);
assert.equal(res.status, 404);
const index = (await (await api("/", secret)).json()) as any;
assert.ok(index.endpoints.some((e: string) => e.includes("/api/v1/alerts")));
});
});
describe("when a token stops working", () => {
test("it ends on the day it was made to; a removed person's tokens go with them", async () => {
who = "ada";
const { body } = await make("Short");
const secret = body.secret;
assert.equal((await api("/me", secret)).status, 200);
// the end comes: move it into the past
await db.update(apiTokens).set({ expiresAt: new Date(Date.now() - 1000).toISOString() }).where(eq(apiTokens.id, body.token.id));
assert.equal((await api("/me", secret)).status, 401, "expired");
const listed = ((await (await mine("")).json()) as any).tokens.find((t: any) => t.id === body.token.id);
assert.equal(listed.expired, true, "and the list says so");
const gone = (await db.insert(users).values({ oidcSub: "temp", name: "Temp", role: "viewer" }).returning({ id: users.id }))[0].id;
const { createApiToken } = await import("../src/services/apiTokens.js");
const t = await createApiToken({ userId: gone, label: "Leaver", expiresInDays: null });
assert.equal((await api("/me", t.token)).status, 200);
await db.delete(users).where(eq(users.id, gone));
assert.equal((await api("/me", t.token)).status, 401, "the person is gone, so is the token");
assert.equal((await db.select().from(apiTokens).where(eq(apiTokens.userId, gone))).length, 0);
});
test("use is noted, but not more than once a minute", async () => {
who = "ada";
const { body } = await make("Used");
assert.equal((await db.select().from(apiTokens).where(eq(apiTokens.id, body.token.id)))[0].lastUsedAt, null);
await api("/me", body.secret);
const first = (await db.select().from(apiTokens).where(eq(apiTokens.id, body.token.id)))[0].lastUsedAt;
assert.ok(first);
await api("/me", body.secret);
assert.equal((await db.select().from(apiTokens).where(eq(apiTokens.id, body.token.id)))[0].lastUsedAt, first);
});
});
+3 -3
View File
@@ -23,7 +23,7 @@ const { users, servers, serverMetrics } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js"); const { runMigrations } = await import("../src/db/migrate.js");
const { serversRouter } = await import("../src/routes/servers.js"); const { serversRouter } = await import("../src/routes/servers.js");
const { syncServerTasks } = await import("../src/services/taskSync.js"); const { syncServerTasks } = await import("../src/services/taskSync.js");
const { samplesFromSystem, recordServerMetrics, bucketPoints, trendOf, getServerMetrics, MIN_GAP_MS, RETENTION_DAYS } = await import("../src/services/serverMetrics.js"); const { samplesFromSystem, recordServerMetrics, bucketPoints, trendOf, getServerMetrics, MIN_GAP_MS, RETENTION_DAYS, MAX_RANGE_DAYS } = await import("../src/services/serverMetrics.js");
await runMigrations(); await runMigrations();
@@ -189,8 +189,8 @@ describe("GET /api/servers/:id/metrics", () => {
test("anyone signed in can read it, and the number of days is kept within what is stored", async () => { test("anyone signed in can read it, and the number of days is kept within what is stored", async () => {
const res = await fetch(`${base}/${serverId}/metrics?days=9999`); const res = await fetch(`${base}/${serverId}/metrics?days=9999`);
assert.equal(res.status, 200); assert.equal(res.status, 200);
const body = await res.json(); assert.equal((await res.json()).days, MAX_RANGE_DAYS, "a year at most: the rest is kept as hours and days");
assert.equal(body.days, RETENTION_DAYS); const body = await (await fetch(`${base}/${serverId}/metrics?days=${RETENTION_DAYS}`)).json();
assert.deepEqual(body.series.map((s: { kind: string }) => s.kind), ["cpu", "mem", "disk"]); assert.deepEqual(body.series.map((s: { kind: string }) => s.kind), ["cpu", "mem", "disk"]);
assert.equal((await fetch(`${base}/${serverId}/metrics`)).status, 200); assert.equal((await fetch(`${base}/${serverId}/metrics`)).status, 200);
}); });
+2
View File
@@ -8,6 +8,7 @@ import Secrets from "./pages/Secrets";
import Ipam from "./pages/Ipam"; import Ipam from "./pages/Ipam";
import NetworkDevices from "./pages/NetworkDevices"; import NetworkDevices from "./pages/NetworkDevices";
import MyWorkPage from "./pages/MyWork"; import MyWorkPage from "./pages/MyWork";
import ApiTokens from "./pages/ApiTokens";
import Ports from "./pages/Ports"; import Ports from "./pages/Ports";
import Dns from "./pages/Dns"; import Dns from "./pages/Dns";
import Servers from "./pages/Servers"; import Servers from "./pages/Servers";
@@ -136,6 +137,7 @@ function Shelled({ user }: { user: CurrentUser }) {
<Routes> <Routes>
<Route path="/" element={<Dashboard user={user} />} /> <Route path="/" element={<Dashboard user={user} />} />
<Route path="/my-work" element={<MyWorkPage user={user} />} /> <Route path="/my-work" element={<MyWorkPage user={user} />} />
<Route path="/api-tokens" element={<ApiTokens />} />
<Route path="/map" element={<MapPage user={user} />} /> <Route path="/map" element={<MapPage user={user} />} />
<Route path="/servers" element={<Servers user={user} />} /> <Route path="/servers" element={<Servers user={user} />} />
<Route path="/servers/compare" element={<ServerCompare />} /> <Route path="/servers/compare" element={<ServerCompare />} />
+32 -2
View File
@@ -305,7 +305,8 @@ export interface ServerMetricSeries {
metric: string; metric: string;
kind: "cpu" | "mem" | "disk"; kind: "cpu" | "mem" | "disk";
label: string; label: string;
points: { t: string; v: number }[]; /** `lo` and `hi` are there when a point stands for an hour or a day: the lowest and highest figure in it. */
points: { t: string; v: number; lo?: number; hi?: number }[];
latest: number | null; latest: number | null;
/** Disks only: the rate of change in points a day, and the days until full when it is rising. */ /** Disks only: the rate of change in points a day, and the days until full when it is rising. */
trend: { perDay: number; fit: number; spanDays: number; daysToFull: number | null } | null; trend: { perDay: number; fit: number; spanDays: number; daysToFull: number | null } | null;
@@ -907,6 +908,29 @@ export interface EndpointCheck {
server: { id: number; name: string } | null; server: { id: number; name: string } | null;
stats?: EndpointStats; stats?: EndpointStats;
} }
/** How one check has done over a stretch (GET /api/endpoints/:id/history). */
export interface EndpointHistory {
check: { id: number; name: string };
days: number;
/** Which figures it is drawn from: each answer (a day or two), the hourly figures, or the daily ones. */
source: "results" | "hourly" | "daily";
points: { t: string; availability: number | null; avgMs: number | null; maxMs: number | null; checks: number }[];
availability: number | null;
avgMs: number | null;
checks: number;
}
/** One of a person's own read-only API tokens; the secret is only ever shown when it is made. */
export interface ApiToken {
id: number;
label: string;
tokenPrefix: string;
createdAt: string;
lastUsedAt: string | null;
expiresAt: string | null;
expired: boolean;
}
export interface EndpointInput { export interface EndpointInput {
name: string; name: string;
kind: EndpointKind; kind: EndpointKind;
@@ -2155,7 +2179,12 @@ export const api = {
markChangesSeen: () => request<{ lastLookedAt: string }>("/api/me/changes/seen", { method: "POST" }), markChangesSeen: () => request<{ lastLookedAt: string }>("/api/me/changes/seen", { method: "POST" }),
}), }),
uptime: { uptime: {
get: () => request<UptimeReport>("/api/uptime"), get: (days?: number) => request<UptimeReport>(days ? `/api/uptime?days=${days}` : "/api/uptime"),
},
apiTokens: {
list: () => request<{ tokens: ApiToken[]; max: number; expiryChoices: number[] }>("/api/me/tokens"),
create: (data: { label: string; expiresInDays: number | null }) => request<{ token: ApiToken; secret: string }>("/api/me/tokens", { method: "POST", body: JSON.stringify(data) }),
remove: (id: number) => request<void>(`/api/me/tokens/${id}`, { method: "DELETE" }),
}, },
metricsTokens: { metricsTokens: {
list: () => request<{ tokens: MetricsToken[] }>("/api/metrics-tokens"), list: () => request<{ tokens: MetricsToken[] }>("/api/metrics-tokens"),
@@ -2204,6 +2233,7 @@ export const api = {
update: (id: number, data: EndpointInput) => request<{ check: EndpointCheck }>(`/api/endpoints/${id}`, { method: "PUT", body: JSON.stringify(data) }), update: (id: number, data: EndpointInput) => request<{ check: EndpointCheck }>(`/api/endpoints/${id}`, { method: "PUT", body: JSON.stringify(data) }),
remove: (id: number) => request<void>(`/api/endpoints/${id}`, { method: "DELETE" }), remove: (id: number) => request<void>(`/api/endpoints/${id}`, { method: "DELETE" }),
check: (id: number) => request<{ result: { ok: boolean; ms: number | null; message: string } }>(`/api/endpoints/${id}/check`, { method: "POST" }), check: (id: number) => request<{ result: { ok: boolean; ms: number | null; message: string } }>(`/api/endpoints/${id}/check`, { method: "POST" }),
history: (id: number, days: number) => request<EndpointHistory>(`/api/endpoints/${id}/history?days=${days}`),
suggestions: () => request<{ suggestions: EndpointSuggestion[]; dismissed: EndpointSuggestion[] }>("/api/endpoints/suggestions"), suggestions: () => request<{ suggestions: EndpointSuggestion[]; dismissed: EndpointSuggestion[] }>("/api/endpoints/suggestions"),
addSuggestions: (keys: string[]) => request<{ added: { id: number; name: string }[] }>("/api/endpoints/suggestions/add", { method: "POST", body: JSON.stringify({ keys }) }), addSuggestions: (keys: string[]) => request<{ added: { id: number; name: string }[] }>("/api/endpoints/suggestions/add", { method: "POST", body: JSON.stringify({ keys }) }),
dismissSuggestions: (keys: string[]) => request<{ suggestions: EndpointSuggestion[]; dismissed: EndpointSuggestion[] }>("/api/endpoints/suggestions/dismiss", { method: "POST", body: JSON.stringify({ keys }) }), dismissSuggestions: (keys: string[]) => request<{ suggestions: EndpointSuggestion[]; dismissed: EndpointSuggestion[] }>("/api/endpoints/suggestions/dismiss", { method: "POST", body: JSON.stringify({ keys }) }),
+1
View File
@@ -322,6 +322,7 @@ export default function CommandPalette({
items.push({ key: `dep-int-${i.id}`, category: "Dependencies", title: `What depends on ${i.name}?`, subtitle: `${i.type} · opens the dependency map`, path: `/map?view=dependencies&select=integration:${i.id}`, keywords: "depends dependency impact down" }); items.push({ key: `dep-int-${i.id}`, category: "Dependencies", title: `What depends on ${i.name}?`, subtitle: `${i.type} · opens the dependency map`, path: `/map?view=dependencies&select=integration:${i.id}`, keywords: "depends dependency impact down" });
} }
} }
items.push({ key: "act-tokens", category: "Actions", title: "API tokens", subtitle: "Read-only access for scripts and Home Assistant", path: "/api-tokens", keywords: "api token key read home assistant script bearer" });
items.push({ key: "act-shortcuts", category: "Actions", title: "Show keyboard shortcuts", subtitle: "", hint: "?", run: () => void window.dispatchEvent(new Event(SHOW_SHORTCUTS_EVENT)), keywords: "keys help" }); items.push({ key: "act-shortcuts", category: "Actions", title: "Show keyboard shortcuts", subtitle: "", hint: "?", run: () => void window.dispatchEvent(new Event(SHOW_SHORTCUTS_EVENT)), keywords: "keys help" });
if (user.role === "admin") { if (user.role === "admin") {
// Each setting, so "quiet hours" or "flapping" finds the place it is set. // Each setting, so "quiet hours" or "flapping" finds the place it is set.
+86
View File
@@ -0,0 +1,86 @@
import { useEffect, useMemo, useState } from "react";
import { api, type EndpointHistory as History } from "../api/client";
import DetailDrawer from "./DetailDrawer";
import RangeSelect from "./RangeSelect";
import TimeChart from "./TimeChart";
import { BlockSkeleton } from "./Skeleton";
import { ErrorNotice } from "./Notice";
import { CHART_RANGES, useChartRange } from "../utils/chartRanges";
import { readableError } from "../utils/errors";
const SOURCE_WORDS: Record<History["source"], string> = {
results: "each answer",
hourly: "the hourly figures",
daily: "the daily figures",
};
/** How one check has done: availability and answer times over a day to a year, drawn with the same chart as everything else. */
export default function EndpointHistory({ checkId, name, onClose }: { checkId: number; name: string; onClose: () => void }) {
const [days, setDays] = useChartRange(7);
const [history, setHistory] = useState<History | null>(null);
const [error, setError] = useState<string | null>(null);
const [to, setTo] = useState(() => Date.now());
useEffect(() => {
let alive = true;
setError(null);
api.endpoints
.history(checkId, days)
.then((res) => {
if (!alive) return;
setHistory(res);
setTo(Date.now());
})
.catch((err) => alive && setError(readableError(err)));
return () => {
alive = false;
};
}, [checkId, days]);
const from = to - days * 86_400_000;
const rangeLabel = CHART_RANGES.find((r) => r.days === days)?.label ?? `${days} days`;
const availability = useMemo(() => [{ name: "Availability", color: "#2fb344", points: (history?.points ?? []).filter((p) => p.availability !== null).map((p) => ({ t: p.t, v: p.availability as number })) }], [history]);
// The line is the average answer time; the band reaches up to the slowest.
const answer = useMemo(() => [{ name: "Answer time", color: "#4299e1", points: (history?.points ?? []).filter((p) => p.avgMs !== null).map((p) => ({ t: p.t, v: p.avgMs as number, lo: p.avgMs as number, hi: (p.maxMs ?? p.avgMs) as number })) }], [history]);
return (
<DetailDrawer title={name} subtitle="How it has done" onClose={onClose}>
<div className="mb-3">
<RangeSelect value={days} onChange={setDays} />
</div>
<ErrorNotice error={error} />
{!history && !error && <BlockSkeleton lines={5} />}
{history && (
<>
<div className="row g-3 mb-3">
<div className="col-4">
<div className="h3 mb-0">{history.availability === null ? "—" : `${history.availability}%`}</div>
<div className="text-secondary small">answered</div>
</div>
<div className="col-4">
<div className="h3 mb-0">{history.avgMs === null ? "—" : `${history.avgMs} ms`}</div>
<div className="text-secondary small">average answer</div>
</div>
<div className="col-4">
<div className="h3 mb-0">{history.checks}</div>
<div className="text-secondary small">checks</div>
</div>
</div>
<h4 className="mb-1">Availability</h4>
<div className="mb-3">
<TimeChart series={availability} from={from} to={to} label={`${name}: availability over the last ${rangeLabel}`} bars={history.points.length <= 120} barColor={(v) => (v >= 99.9 ? "#2fb344" : v >= 90 ? "#f59f00" : "#f03e3e")} empty="No checks in this stretch yet." />
</div>
<h4 className="mb-1">Answer time</h4>
<TimeChart series={answer} from={from} to={to} unit="ms" label={`${name}: answer time over the last ${rangeLabel}`} empty="No timed answers in this stretch yet." />
<div className="text-secondary small mt-2">
Drawn from {SOURCE_WORDS[history.source]}.
{history.source !== "results" && " Each point is an average of the answers in it; the shaded band reaches up to the slowest."}
{history.source === "daily" && " A day's slowest answer is not kept, so the band follows the average."}
</div>
</>
)}
</DetailDrawer>
);
}
-53
View File
@@ -1,53 +0,0 @@
import { formatDate, formatTime } from "../utils/date";
export interface ChartSeries {
name: string;
color: string;
/** SVG dash pattern, so lines can be told apart without their colour. Empty for a solid line. */
dash: string;
points: { t: string; v: number }[];
}
const W = 720;
const H = 260;
const PAD = { left: 40, right: 12, top: 10, bottom: 26 };
/**
* Several percentage lines over the same stretch of time, on a fixed 0–100% scale (so a quiet server never looks as busy as a loaded
* one). Each line has its own colour and dash pattern. It is a picture: the numbers are in the table beside it.
*/
export default function MultiLineChart({ series, from, to, label }: { series: ChartSeries[]; from: number; to: number; label: string }) {
const x = (t: number) => PAD.left + ((t - from) / Math.max(to - from, 1)) * (W - PAD.left - PAD.right);
const y = (v: number) => PAD.top + (1 - Math.min(100, Math.max(0, v)) / 100) * (H - PAD.top - PAD.bottom);
const ticks = [0, 0.25, 0.5, 0.75, 1].map((f) => from + f * (to - from));
const spanDays = (to - from) / 86_400_000;
const tickLabel = (t: number) => (spanDays <= 1.5 ? formatTime(new Date(t), false) : formatDate(new Date(t)).replace(/^\d{4}-|\/\d{4}$/, ""));
return (
<svg viewBox={`0 0 ${W} ${H}`} className="multi-chart" role="img" aria-label={label}>
{[0, 25, 50, 75, 100].map((v) => (
<g key={v}>
<line x1={PAD.left} x2={W - PAD.right} y1={y(v)} y2={y(v)} stroke="currentColor" strokeOpacity={v === 0 ? 0.4 : 0.15} />
<text x={PAD.left - 6} y={y(v) + 4} textAnchor="end" fontSize="11" fill="currentColor" fillOpacity="0.7">
{v}%
</text>
</g>
))}
{ticks.map((t, i) => (
<text key={i} x={x(t)} y={H - 6} textAnchor={i === 0 ? "start" : i === ticks.length - 1 ? "end" : "middle"} fontSize="11" fill="currentColor" fillOpacity="0.7">
{tickLabel(t)}
</text>
))}
{series.map((s) => {
if (s.points.length === 0) return null;
const d = s.points.map((p, i) => `${i === 0 ? "M" : "L"}${x(Date.parse(p.t)).toFixed(1)},${y(p.v).toFixed(1)}`).join(" ");
return s.points.length === 1 ? (
<circle key={s.name} cx={x(Date.parse(s.points[0].t))} cy={y(s.points[0].v)} r="3" fill={s.color} />
) : (
<path key={s.name} d={d} fill="none" stroke={s.color} strokeWidth="2" strokeDasharray={s.dash || undefined} strokeLinejoin="round" strokeLinecap="round" />
);
})}
</svg>
);
}
+14
View File
@@ -0,0 +1,14 @@
import { CHART_RANGES } from "../utils/chartRanges";
/** The one way to choose how far back a chart looks: 24 hours, 7, 30 or 90 days, or a year. */
export default function RangeSelect({ value, onChange, label = "Time range", only }: { value: number; onChange: (days: number) => void; label?: string; /** Offer only these (in days), for a chart that has no use for the shortest. */ only?: number[] }) {
return (
<div className="btn-group btn-group-sm" role="group" aria-label={label}>
{CHART_RANGES.filter((r) => !only || only.includes(r.days)).map((r) => (
<button key={r.days} type="button" className={`btn ${value === r.days ? "btn-primary" : "btn-outline-secondary"}`} aria-pressed={value === r.days} onClick={() => onChange(r.days)}>
{r.label}
</button>
))}
</div>
);
}
+38 -38
View File
@@ -1,13 +1,9 @@
import { useEffect, useState } from "react"; import { useEffect, useMemo, useState } from "react";
import { api, type ServerMetricSeries } from "../api/client"; import { api, type ServerMetricSeries } from "../api/client";
import Sparkline from "./Sparkline"; import TimeChart from "./TimeChart";
import RangeSelect from "./RangeSelect";
import { BlockSkeleton } from "./Skeleton"; import { BlockSkeleton } from "./Skeleton";
import { CHART_RANGES, useChartRange } from "../utils/chartRanges";
const RANGES = [
{ days: 1, label: "24 hours" },
{ days: 7, label: "7 days" },
{ days: 30, label: "30 days" },
];
function levelColor(series: ServerMetricSeries): string { function levelColor(series: ServerMetricSeries): string {
const v = series.latest ?? 0; const v = series.latest ?? 0;
@@ -26,40 +22,48 @@ function describeTrend(series: ServerMetricSeries): string {
if (series.kind === "disk") return "not enough history for a trend yet"; if (series.kind === "disk") return "not enough history for a trend yet";
const values = series.points.map((p) => p.v); const values = series.points.map((p) => p.v);
if (values.length === 0) return ""; if (values.length === 0) return "";
return `${Math.round(Math.min(...values))}–${Math.round(Math.max(...values))}% over this time`; // With hourly or daily figures the line is an average: the real lowest and highest are in the band.
const lo = Math.min(...series.points.map((p) => p.lo ?? p.v));
const hi = Math.max(...series.points.map((p) => p.hi ?? p.v));
return `${Math.round(lo)}–${Math.round(hi)}% over this time`;
} }
/** How an agent-reported server's load, memory and disks have moved lately, with a forecast for a filling disk. */ /** How an agent-reported server's load, memory and disks have moved over a day to a year, with a forecast for a filling disk. */
export default function ServerTrends({ serverId }: { serverId: number }) { export default function ServerTrends({ serverId }: { serverId: number }) {
const [days, setDays] = useState(7); const [days, setDays] = useChartRange(7);
const [series, setSeries] = useState<ServerMetricSeries[] | null>(null); const [series, setSeries] = useState<ServerMetricSeries[] | null>(null);
const [failed, setFailed] = useState(false); const [failed, setFailed] = useState(false);
// Fixed per load, so the right-hand end of a chart is when it was read and does not creep as the page re-renders.
const [to, setTo] = useState(() => Date.now());
useEffect(() => { useEffect(() => {
let alive = true; let alive = true;
setFailed(false); setFailed(false);
api.servers api.servers
.metrics(serverId, days) .metrics(serverId, days)
.then((res) => alive && setSeries(res.series)) .then((res) => {
if (!alive) return;
setSeries(res.series);
setTo(Date.now());
})
.catch(() => alive && setFailed(true)); .catch(() => alive && setFailed(true));
return () => { return () => {
alive = false; alive = false;
}; };
}, [serverId, days]); }, [serverId, days]);
const from = to - days * 86_400_000;
const rangeLabel = CHART_RANGES.find((r) => r.days === days)?.label ?? `${days} days`;
const charts = useMemo(
() => (series ?? []).map((s) => ({ s, words: describeTrend(s), series: [{ name: s.label, color: levelColor(s), points: s.points }] })),
[series],
);
return ( return (
<div className="card mb-3"> <div className="card mb-3">
<div className="card-header"> <div className="card-header d-flex flex-wrap gap-2">
<h3 className="card-title">Trends</h3> <h3 className="card-title me-auto">Trends</h3>
<div className="card-actions"> <RangeSelect value={days} onChange={setDays} />
<select className="form-select form-select-sm" value={days} onChange={(e) => setDays(Number(e.target.value))} aria-label="Time range">
{RANGES.map((r) => (
<option key={r.days} value={r.days}>
Last {r.label}
</option>
))}
</select>
</div>
</div> </div>
<div className="card-body"> <div className="card-body">
{failed ? ( {failed ? (
@@ -68,25 +72,21 @@ export default function ServerTrends({ serverId }: { serverId: number }) {
<BlockSkeleton lines={4} /> <BlockSkeleton lines={4} />
) : series.length === 0 ? ( ) : series.length === 0 ? (
<div className="text-secondary"> <div className="text-secondary">
No history yet. A sample is kept about every ten minutes once the agent has reported, so lines appear here after a short while. No history in this stretch yet. A sample is kept about every ten minutes once the agent has reported, and its hours and days after that, so lines appear here after a short while.
</div> </div>
) : ( ) : (
<div className="trend-grid"> <div className="trend-grid">
{series.map((s) => { {charts.map(({ s, words, series: lines }) => (
const words = describeTrend(s); <div key={s.metric} className="trend-block mb-3">
return ( <div className="d-flex flex-wrap align-items-baseline gap-2 mb-1">
<div key={s.metric} className="trend-row"> <strong>{s.label}</strong>
<div className="trend-label">{s.label}</div> <span>{s.latest !== null ? `${Math.round(s.latest)}%` : "—"}</span>
<Sparkline <span className="text-secondary small">{words}</span>
points={s.points}
color={levelColor(s)}
label={`${s.label}, ${s.latest !== null ? `${Math.round(s.latest)}% now` : "no reading"}${words ? `, ${words}` : ""}`}
/>
<div className="trend-now">{s.latest !== null ? `${Math.round(s.latest)}%` : "—"}</div>
<div className="trend-words text-secondary small">{words}</div>
</div> </div>
); <TimeChart series={lines} from={from} to={to} compact label={`${s.label} over the last ${rangeLabel}, ${s.latest !== null ? `${Math.round(s.latest)}% now` : "no reading"}`} />
})} </div>
))}
{days > 35 && <div className="text-secondary small">Over {days > 120 ? "more than four months" : "more than five weeks"} each point is {days > 120 ? "a day" : "an hour"}&rsquo;s average, and the shaded band is its lowest and highest.</div>}
</div> </div>
)} )}
</div> </div>
-37
View File
@@ -1,37 +0,0 @@
/**
* A small line of how a percentage moved. The scale is always 0–100%, so a disk at 40% looks half-empty and one at 95% looks full
* however little it moved — a line that stretched to fit its own ups and downs would make every wobble look alarming.
*/
export default function Sparkline({
points,
color = "#4299e1",
label,
}: {
points: { t: string; v: number }[];
color?: string;
/** Read out by screen readers in place of the picture. */
label: string;
}) {
const W = 160;
const H = 36;
if (points.length < 2) {
return (
<svg viewBox={`0 0 ${W} ${H}`} className="sparkline" role="img" aria-label={label}>
<line x1="0" y1={H - 1} x2={W} y2={H - 1} stroke="currentColor" strokeOpacity="0.25" />
</svg>
);
}
const t0 = Date.parse(points[0].t);
const span = Math.max(Date.parse(points[points.length - 1].t) - t0, 1);
const xy = points.map((p) => {
const x = ((Date.parse(p.t) - t0) / span) * (W - 2) + 1;
const y = H - 2 - (Math.min(100, Math.max(0, p.v)) / 100) * (H - 4);
return `${x.toFixed(1)},${y.toFixed(1)}`;
});
return (
<svg viewBox={`0 0 ${W} ${H}`} className="sparkline" role="img" aria-label={label} preserveAspectRatio="none">
<polyline points={`1,${H - 1} ${xy.join(" ")} ${W - 1},${H - 1}`} fill={color} fillOpacity="0.15" stroke="none" />
<polyline points={xy.join(" ")} fill="none" stroke={color} strokeWidth="1.6" strokeLinejoin="round" strokeLinecap="round" vectorEffect="non-scaling-stroke" />
</svg>
);
}
+241
View File
@@ -0,0 +1,241 @@
import { useMemo, useRef, useState, type KeyboardEvent, type PointerEvent } from "react";
import { formatDate, formatDateTime, formatTime } from "../utils/date";
export interface ChartPoint {
/** ISO time. */
t: string;
v: number;
/** The lowest and highest of what this point stands for (an hour's or a day's figures); drawn as a band round the line. */
lo?: number;
hi?: number;
}
export interface ChartSeries {
name: string;
color: string;
/** SVG dash pattern, so lines can be told apart without their colour. Empty for a solid line. */
dash?: string;
points: ChartPoint[];
}
const W = 720;
const PAD = { left: 46, right: 12, top: 10, bottom: 24 };
/** A round number at or above `v`: 1, 2, 5 or 10 times a power of ten. */
function niceCeil(v: number): number {
if (!(v > 0)) return 10;
const pow = 10 ** Math.floor(Math.log10(v));
const f = v / pow;
return (f <= 1 ? 1 : f <= 2 ? 2 : f <= 5 ? 5 : 10) * pow;
}
const median = (xs: number[]) => {
if (xs.length === 0) return 0;
const s = [...xs].sort((a, b) => a - b);
return s[Math.floor(s.length / 2)];
};
/**
* The one chart: lines (or bars) over a stretch of time, the same everywhere — server load and disks, a check's answer times and availability, uptime.
* Hover (or arrow keys, once it has focus) reads off the values at that moment. A band shows the lowest and highest where a point stands for an hour or a day, and
* a gap in the data is a gap in the line. The scale is 0–100 for percentages, so a quiet server never looks as busy as a loaded one; for times it fits the data.
*/
export default function TimeChart({
series,
from,
to,
label,
unit = "%",
compact = false,
bars = false,
barColor,
format,
empty = "No history in this stretch yet.",
}: {
series: ChartSeries[];
from: number;
to: number;
/** Read out by screen readers in place of the picture. */
label: string;
unit?: "%" | "ms";
compact?: boolean;
/** One bar per point instead of a line (daily availability). */
bars?: boolean;
barColor?: (v: number) => string;
format?: (v: number) => string;
empty?: string;
}) {
const H = compact ? 116 : 250;
const wrap = useRef<HTMLDivElement>(null);
// Where the cursor is, as a time (null: nowhere), and whether the keyboard put it there.
const [cursor, setCursor] = useState<number | null>(null);
const fmt = format ?? ((v: number) => (unit === "%" ? `${Math.round(v * 10) / 10}%` : `${Math.round(v)} ms`));
const parsed = useMemo(() => series.map((s) => ({ ...s, pts: s.points.map((p) => ({ ...p, x: Date.parse(p.t) })).filter((p) => Number.isFinite(p.x)) })), [series]);
const any = parsed.some((s) => s.pts.length > 0);
const top = unit === "%" ? 100 : niceCeil(Math.max(0, ...parsed.flatMap((s) => s.pts.map((p) => p.hi ?? p.v))) * 1.05);
const x = (t: number) => PAD.left + ((t - from) / Math.max(to - from, 1)) * (W - PAD.left - PAD.right);
const y = (v: number) => PAD.top + (1 - Math.min(top, Math.max(0, v)) / top) * (H - PAD.top - PAD.bottom);
const spanDays = (to - from) / 86_400_000;
const tickLabel = (t: number) =>
spanDays <= 1.5 ? formatTime(new Date(t), false) : spanDays <= 45 ? new Date(t).toLocaleDateString(undefined, { day: "numeric", month: "short" }) : new Date(t).toLocaleDateString(undefined, { month: "short", year: "2-digit" });
const ticks = (compact ? [0, 0.5, 1] : [0, 0.25, 0.5, 0.75, 1]).map((f) => from + f * (to - from));
const grid = compact ? [0, top / 2, top] : [0, top / 4, top / 2, (3 * top) / 4, top];
// Every moment any series has a point, for the arrow keys to step through.
const moments = useMemo(() => [...new Set(parsed.flatMap((s) => s.pts.map((p) => p.x)))].sort((a, b) => a - b), [parsed]);
const nearest = (s: (typeof parsed)[number], t: number) => {
let best: (typeof s.pts)[number] | null = null;
for (const p of s.pts) if (best === null || Math.abs(p.x - t) < Math.abs(best.x - t)) best = p;
return best;
};
// The moment closest to the cursor, so the vertical line sits on a real point.
const at = cursor === null || moments.length === 0 ? null : moments.reduce((b, m) => (Math.abs(m - cursor) < Math.abs(b - cursor) ? m : b), moments[0]);
const readings = at === null ? [] : parsed.map((s) => ({ s, p: nearest(s, at) })).filter((r): r is { s: (typeof parsed)[number]; p: NonNullable<typeof r.p> } => r.p !== null && Math.abs(r.p.x - at) <= Math.max((to - from) / 40, 1));
function move(e: PointerEvent<HTMLDivElement>) {
const box = wrap.current?.getBoundingClientRect();
if (!box || box.width === 0) return;
const vx = ((e.clientX - box.left) / box.width) * W;
setCursor(from + ((vx - PAD.left) / (W - PAD.left - PAD.right)) * (to - from));
}
function key(e: KeyboardEvent<HTMLDivElement>) {
if (moments.length === 0) return;
if (e.key === "Escape") return setCursor(null);
if (e.key !== "ArrowLeft" && e.key !== "ArrowRight" && e.key !== "Home" && e.key !== "End") return;
e.preventDefault();
const i = at === null ? moments.length - 1 : moments.indexOf(at);
const next = e.key === "Home" ? 0 : e.key === "End" ? moments.length - 1 : Math.min(moments.length - 1, Math.max(0, i + (e.key === "ArrowRight" ? 1 : -1)));
setCursor(moments[next]);
}
const summary = parsed
.filter((s) => s.pts.length > 0)
.map((s) => {
const vs = s.pts.map((p) => p.v);
return `${s.name}: now ${fmt(vs[vs.length - 1])}, from ${fmt(Math.min(...vs))} to ${fmt(Math.max(...vs))}`;
})
.join(". ");
if (!any) {
return (
<div className="time-chart time-chart-empty text-secondary small" style={{ minHeight: compact ? 50 : 120 }} role="status">
{empty}
</div>
);
}
const spacing = median(parsed.flatMap((s) => s.pts.slice(1).map((p, i) => p.x - s.pts[i].x)));
const barW = Math.max(1.5, Math.min(24, ((W - PAD.left - PAD.right) * (spacing > 0 ? spacing : (to - from) / 30)) / Math.max(to - from, 1) * 0.8));
const tipLeft = at === null ? 0 : ((x(at) / W) * 100);
return (
<div
ref={wrap}
className="time-chart"
tabIndex={0}
role="group"
aria-label={`${label}. Use the arrow keys to read it off.`}
onPointerMove={move}
onPointerLeave={() => setCursor(null)}
onKeyDown={key}
onBlur={() => setCursor(null)}
>
<svg viewBox={`0 0 ${W} ${H}`} className="time-chart-svg" role="img" aria-label={`${label}. ${summary}`}>
{grid.map((v) => (
<g key={v}>
<line x1={PAD.left} x2={W - PAD.right} y1={y(v)} y2={y(v)} stroke="currentColor" strokeOpacity={v === 0 ? 0.4 : 0.15} />
<text x={PAD.left - 6} y={y(v) + 4} textAnchor="end" fontSize="11" fill="currentColor" fillOpacity="0.7">
{unit === "%" ? `${v}%` : `${Math.round(v)}`}
</text>
</g>
))}
{unit === "ms" && (
<text x={4} y={PAD.top + 10} fontSize="10" fill="currentColor" fillOpacity="0.6">
ms
</text>
)}
{ticks.map((t, i) => (
<text key={i} x={x(t)} y={H - 6} textAnchor={i === 0 ? "start" : i === ticks.length - 1 ? "end" : "middle"} fontSize="11" fill="currentColor" fillOpacity="0.7">
{tickLabel(t)}
</text>
))}
{parsed.map((s) => {
if (s.pts.length === 0) return null;
if (bars) {
return (
<g key={s.name}>
{s.pts.map((p, i) => (
<rect key={i} x={x(p.x) - barW / 2} y={y(p.v)} width={barW} height={Math.max(0, y(0) - y(p.v))} fill={barColor ? barColor(p.v) : s.color} opacity={at !== null && p.x !== at ? 0.55 : 1} />
))}
</g>
);
}
// Where the data stops for a while, so does the line.
const limit = Math.max(spacing * 3, (to - from) / 60);
let d = "";
const bands: string[] = [];
s.pts.forEach((p, i) => {
const gap = i > 0 && p.x - s.pts[i - 1].x > limit;
d += `${i === 0 || gap ? "M" : "L"}${x(p.x).toFixed(1)},${y(p.v).toFixed(1)} `;
});
// The band: along the highs, then back along the lows, one shape for each unbroken stretch.
const hasBand = s.pts.some((p) => p.hi !== undefined);
if (hasBand) {
let run: typeof s.pts = [];
const close = () => {
if (run.length > 1) {
const up = run.map((p) => `${x(p.x).toFixed(1)},${y(p.hi ?? p.v).toFixed(1)}`);
const down = [...run].reverse().map((p) => `${x(p.x).toFixed(1)},${y(p.lo ?? p.v).toFixed(1)}`);
bands.push([...up, ...down].join(" "));
}
run = [];
};
s.pts.forEach((p, i) => {
if (i > 0 && p.x - s.pts[i - 1].x > limit) close();
run.push(p);
});
close();
}
return (
<g key={s.name}>
{hasBand && bands.map((b, i) => <polygon key={i} points={b} fill={s.color} fillOpacity="0.14" stroke="none" />)}
{s.pts.length === 1 ? (
<circle cx={x(s.pts[0].x)} cy={y(s.pts[0].v)} r="3" fill={s.color} />
) : (
<path d={d} fill="none" stroke={s.color} strokeWidth={compact ? 1.6 : 2} strokeDasharray={s.dash || undefined} strokeLinejoin="round" strokeLinecap="round" />
)}
</g>
);
})}
{at !== null && (
<g pointerEvents="none">
<line x1={x(at)} x2={x(at)} y1={PAD.top} y2={H - PAD.bottom} stroke="currentColor" strokeOpacity="0.5" strokeDasharray="3 3" />
{!bars && readings.map((r) => <circle key={r.s.name} cx={x(r.p.x)} cy={y(r.p.v)} r="3.5" fill={r.s.color} stroke="var(--tblr-bg-surface, #fff)" strokeWidth="1.5" />)}
</g>
)}
</svg>
{at !== null && readings.length > 0 && (
<div className="time-chart-tip" style={{ left: `${tipLeft}%`, transform: tipLeft > 60 ? "translateX(calc(-100% - 10px))" : "translateX(10px)" }} role="status" aria-live="polite">
<div className="time-chart-tip-time">{spanDays > 120 ? formatDate(new Date(at)) : formatDateTime(new Date(at))}</div>
{readings.map((r) => (
<div key={r.s.name} className="time-chart-tip-row">
<span className="time-chart-swatch" style={{ background: bars && barColor ? barColor(r.p.v) : r.s.color }} aria-hidden="true" />
<span className="time-chart-tip-name">{r.s.name}</span>
<strong>{fmt(r.p.v)}</strong>
{r.p.lo !== undefined && r.p.hi !== undefined && r.p.hi !== r.p.lo && (
<span className="text-secondary small">
{" "}
({fmt(r.p.lo)}–{fmt(r.p.hi)})
</span>
)}
</div>
))}
</div>
)}
</div>
);
}
+78
View File
@@ -0,0 +1,78 @@
import { useEffect, useMemo, useState } from "react";
import { api, type UptimeReport } from "../api/client";
import RangeSelect from "./RangeSelect";
import TimeChart from "./TimeChart";
import { BlockSkeleton } from "./Skeleton";
import { useChartRange } from "../utils/chartRanges";
const DAY_MS = 24 * 3600_000;
/** A day of uptime is drawn green when nothing was wrong, amber for some time down, red for most of the day. */
const dayColor = (v: number) => (v >= 99.9 ? "#2fb344" : v >= 50 ? "#f59f00" : "#f03e3e");
/**
* How a server (or an integration) has done, a day at a time, as far back as the record goes: the share of each day it was up. The thin ribbon on the lists is the
* last 30 days of the same thing; this is the chart, with a value for any day and a range up to a year.
*/
export default function UptimeHistory({ kind, id, name }: { kind: "servers" | "integrations"; id: number; name: string }) {
const [chosen, setDays] = useChartRange(30);
// A day is the smallest thing recorded, so 24 hours is not offered here: a chart of a single bar says nothing.
const days = chosen < 30 ? 30 : chosen;
const [report, setReport] = useState<UptimeReport | null>(null);
const [failed, setFailed] = useState(false);
useEffect(() => {
let alive = true;
setFailed(false);
api.uptime
.get(days)
.then((res) => alive && setReport(res))
.catch(() => alive && setFailed(true));
return () => {
alive = false;
};
}, [days]);
const series = report?.[kind][id];
const to = report ? Date.parse(report.endsAt) : Date.now();
const lines = useMemo(() => {
if (!report || !series) return [];
const end = Date.parse(report.endsAt);
return [
{
name: "Up",
color: "#2fb344",
// One point per day with something known about it, in the middle of that day.
points: series.buckets.flatMap((b, i) => (b.k === 0 ? [] : [{ t: new Date(end - (report.days - i - 0.5) * DAY_MS).toISOString(), v: Math.round((1 - b.d / b.k) * 1000) / 10 }])),
},
];
}, [report, series]);
return (
<div className="card mb-3">
<div className="card-header d-flex flex-wrap gap-2">
<h3 className="card-title me-auto">Availability</h3>
<RangeSelect value={days} onChange={setDays} only={[30, 90, 365]} />
</div>
<div className="card-body">
{failed ? (
<div className="text-secondary">Couldn't load the record.</div>
) : !report ? (
<BlockSkeleton lines={3} />
) : !series ? (
<div className="text-secondary">Nothing is known about {name} in this stretch yet.</div>
) : (
<>
<div className="mb-2">
<span className="h3 me-2">{series.percent}%</span>
<span className="text-secondary">up over the last {days} days</span>
</div>
<TimeChart series={lines} from={to - days * DAY_MS} to={to} bars barColor={dayColor} label={`${name}: share of each day it was up, over the last ${days} days. ${series.percent}% in all.`} />
<div className="text-secondary small mt-2">
Worked out from when it stopped reporting and reported again, so it goes back as far as the change log does; days before it was known are left blank.
</div>
</>
)}
</div>
</div>
);
}
+13 -1
View File
@@ -1,6 +1,6 @@
import { useEffect, useRef, useState, type ReactNode } from "react"; import { useEffect, useRef, useState, type ReactNode } from "react";
import { Link, NavLink, useLocation } from "react-router-dom"; import { Link, NavLink, useLocation } from "react-router-dom";
import { IconMenu2, IconSun, IconMoon, IconShieldLock, IconTool, IconChevronUp, IconLogout, IconDeviceDesktop, IconChevronsLeft, IconChevronsRight } from "@tabler/icons-react"; import { IconKey, IconMenu2, IconSun, IconMoon, IconShieldLock, IconTool, IconChevronUp, IconLogout, IconDeviceDesktop, IconChevronsLeft, IconChevronsRight } from "@tabler/icons-react";
import { api, type CurrentUser, type MaintenanceWindow } from "../api/client"; import { api, type CurrentUser, type MaintenanceWindow } from "../api/client";
import { isCurrent, isGroup, visibleNav, type NavGroup } from "./nav"; import { isCurrent, isGroup, visibleNav, type NavGroup } from "./nav";
import SidebarNav, { type NavBadge } from "./SidebarNav"; import SidebarNav, { type NavBadge } from "./SidebarNav";
@@ -305,6 +305,18 @@ export default function AppShell({ user, children }: { user: CurrentUser; childr
<IconShieldLock size={16} /> <IconShieldLock size={16} />
Privacy Privacy
</NavLink> </NavLink>
<NavLink
to="/api-tokens"
className="user-menu-item"
role="menuitem"
onClick={() => {
setMenuOpen(false);
setSidebarOpen(false);
}}
>
<IconKey size={16} />
API tokens
</NavLink>
<NavLink <NavLink
to="/wall" to="/wall"
className="user-menu-item" className="user-menu-item"
+221
View File
@@ -0,0 +1,221 @@
import { useEffect, useState } from "react";
import { api, type ApiToken } from "../api/client";
import CopyButton from "../components/CopyButton";
import { EmptyRow } from "../components/EmptyState";
import { ErrorNotice } from "../components/Notice";
import { BlockSkeleton } from "../components/Skeleton";
import TimeAgo from "../components/TimeAgo";
import { confirmDialog } from "../utils/dialogs";
import { formatDate } from "../utils/date";
import { readableError } from "../utils/errors";
import { toast } from "../utils/toast";
const EXPIRY = [
{ value: "90", label: "90 days" },
{ value: "30", label: "30 days" },
{ value: "365", label: "1 year" },
{ value: "", label: "No end — until I remove it" },
];
const READS = [
["/api/v1/servers", "every server: whether it is online, its addresses, load, memory, disks and waiting updates"],
["/api/v1/servers/:id/metrics?days=365", "a server's load, memory and disks, up to a year back"],
["/api/v1/alerts", "what is wrong now, and whether somebody is on it"],
["/api/v1/incidents?status=open", "the record of alerts that began and ended"],
["/api/v1/inventory", "the hardware"],
["/api/v1/network", "switches, access points and gateways, networks and Wi-Fi names"],
["/api/v1/endpoints", "the checks, and /endpoints/:id/history for how one has done"],
["/api/v1/maintenance", "what is under maintenance now, and what is coming"],
];
/**
* A person's own read-only tokens for the API (/api/v1): a script, Home Assistant or a dashboard sends one in a header and gets JSON back. A token can only read, sees
* what its owner sees, and is gone when its owner is. The secret is shown once, here, when it is made.
*/
export default function ApiTokens() {
const [tokens, setTokens] = useState<ApiToken[] | null>(null);
const [max, setMax] = useState(10);
const [error, setError] = useState<string | null>(null);
const [label, setLabel] = useState("");
const [expiry, setExpiry] = useState("90");
const [busy, setBusy] = useState(false);
const [fresh, setFresh] = useState<{ label: string; secret: string } | null>(null);
function load() {
api.apiTokens
.list()
.then((res) => {
setTokens(res.tokens);
setMax(res.max);
})
.catch((err) => setError(readableError(err)));
}
useEffect(load, []);
async function make(e: React.FormEvent) {
e.preventDefault();
setBusy(true);
setError(null);
try {
const res = await api.apiTokens.create({ label: label.trim(), expiresInDays: expiry === "" ? null : Number(expiry) });
setFresh({ label: res.token.label, secret: res.secret });
setLabel("");
load();
} catch (err) {
setError(readableError(err));
} finally {
setBusy(false);
}
}
async function remove(t: ApiToken) {
// Not undoable: the secret is not kept, so a token cannot be made again the same.
if (!(await confirmDialog({ title: "Remove a token", message: `Remove "${t.label}"? Whatever uses it stops working at once, and it cannot be put back.`, confirmLabel: "Remove", danger: true }))) return;
try {
await api.apiTokens.remove(t.id);
toast.success(`Removed "${t.label}".`);
load();
} catch (err) {
toast.error(readableError(err));
}
}
const origin = window.location.origin;
return (
<>
<div className="d-flex align-items-center mb-1">
<h2 className="page-title mb-0">API tokens</h2>
</div>
<div className="text-secondary mb-3">
Read-only access to your installation&rsquo;s data for scripts, Home Assistant and dashboards. A token can only read, sees what you see, and stops working when you are removed. Make one for each thing that reads, so each can be removed on its own.
</div>
<ErrorNotice error={error} />
{fresh && (
<div className="alert alert-success" role="status">
<div className="w-100">
<div className="fw-bold mb-1">Your token &ldquo;{fresh.label}&rdquo; — copy it now, it is not shown again</div>
<div className="d-flex flex-wrap align-items-center gap-2 mb-2">
<code className="text-break">{fresh.secret}</code>
<CopyButton text={fresh.secret} />
</div>
<div className="small">Send it in a header, never in the address:</div>
<pre className="mb-2 mt-1 small">{`curl -H "Authorization: Bearer ${fresh.secret}" ${origin}/api/v1/alerts`}</pre>
<button type="button" className="btn btn-sm" onClick={() => setFresh(null)}>
I have copied it
</button>
</div>
</div>
)}
<form className="card mb-3" onSubmit={make}>
<div className="card-header">
<h3 className="card-title">Make a token</h3>
</div>
<div className="card-body row g-3 align-items-end">
<div className="col-md-5">
<label className="form-label" htmlFor="tok-label">
What it is for
</label>
<input id="tok-label" className="form-control" maxLength={60} required placeholder="e.g. Home Assistant" value={label} onChange={(e) => setLabel(e.target.value)} />
</div>
<div className="col-md-4">
<label className="form-label" htmlFor="tok-exp">
Works for
</label>
<select id="tok-exp" className="form-select" value={expiry} onChange={(e) => setExpiry(e.target.value)}>
{EXPIRY.map((o) => (
<option key={o.value} value={o.value}>
{o.label}
</option>
))}
</select>
</div>
<div className="col-md-3">
<button type="submit" className="btn btn-primary w-100" disabled={busy || label.trim() === "" || (tokens?.length ?? 0) >= max}>
{busy ? "Making…" : "Make the token"}
</button>
</div>
{(tokens?.length ?? 0) >= max && <div className="col-12 text-secondary small">You have {max} tokens, the most there can be. Remove one you do not use.</div>}
</div>
</form>
<div className="card mb-3">
<div className="card-header">
<h3 className="card-title">Your tokens</h3>
</div>
<div className="table-responsive">
<table className="table table-vcenter card-table table-stack">
<thead>
<tr>
<th>Name</th>
<th>Starts with</th>
<th>Made</th>
<th>Last used</th>
<th>Ends</th>
<th className="w-1">
<span className="visually-hidden">Actions</span>
</th>
</tr>
</thead>
<tbody>
{tokens === null && !error && (
<tr>
<td colSpan={6}>
<BlockSkeleton lines={2} />
</td>
</tr>
)}
{tokens?.map((t) => (
<tr key={t.id}>
<td className="stack-wide">
<strong>{t.label}</strong>
{t.expired && <span className="badge bg-red-lt text-red ms-2">expired</span>}
</td>
<td className="stack-label font-monospace" data-label="Starts with">
{t.tokenPrefix}…
</td>
<td className="stack-label" data-label="Made">
<TimeAgo value={t.createdAt} fromDb />
</td>
<td className="stack-label" data-label="Last used">
{t.lastUsedAt ? <TimeAgo value={t.lastUsedAt} /> : <span className="text-secondary">never</span>}
</td>
<td className="stack-label" data-label="Ends">
{t.expiresAt ? formatDate(new Date(t.expiresAt)) : <span className="text-secondary">no end</span>}
</td>
<td className="stack-wide">
<button className="btn btn-sm btn-outline-danger" onClick={() => void remove(t)}>
Remove
</button>
</td>
</tr>
))}
{tokens !== null && tokens.length === 0 && <EmptyRow colSpan={6} title="No tokens yet" hint="Make one above, and copy it when it is shown: that is the only time it is." />}
</tbody>
</table>
</div>
</div>
<div className="card">
<div className="card-header">
<h3 className="card-title">What it can read</h3>
</div>
<div className="card-body">
<p className="text-secondary">
Everything is a <code>GET</code> that answers JSON, under <code>{origin}/api/v1</code>, with the token as <code>Authorization: Bearer …</code>. Nothing can be changed through it. Dates are ISO 8601 in UTC and sizes are in bytes.
</p>
<ul className="mb-2">
{READS.map(([path, what]) => (
<li key={path}>
<code>{path}</code> — {what}
</li>
))}
</ul>
<div className="text-secondary small">The full list, with an example of each answer, is in API.md.</div>
</div>
</div>
</>
);
}
+6
View File
@@ -16,6 +16,7 @@ import { readableError } from "../utils/errors";
import { toast } from "../utils/toast"; import { toast } from "../utils/toast";
import { EmptyRow } from "../components/EmptyState"; import { EmptyRow } from "../components/EmptyState";
import EndpointSuggestions from "../components/EndpointSuggestions"; import EndpointSuggestions from "../components/EndpointSuggestions";
import EndpointHistory from "../components/EndpointHistory";
const KIND_LABELS: Record<EndpointKind, string> = { http: "Web address", tcp: "Port", tls: "Certificate" }; const KIND_LABELS: Record<EndpointKind, string> = { http: "Web address", tcp: "Port", tls: "Certificate" };
const KIND_HINTS: Record<EndpointKind, string> = { const KIND_HINTS: Record<EndpointKind, string> = {
@@ -128,6 +129,7 @@ export default function Endpoints({ user }: { user: CurrentUser }) {
const [draft, setDraft] = useState<Draft | null>(null); const [draft, setDraft] = useState<Draft | null>(null);
const [busy, setBusy] = useState(false); const [busy, setBusy] = useState(false);
const [asking, setAsking] = useState<number | null>(null); const [asking, setAsking] = useState<number | null>(null);
const [historyFor, setHistoryFor] = useState<{ id: number; name: string } | null>(null);
function load() { function load() {
api.endpoints api.endpoints
@@ -438,6 +440,9 @@ export default function Endpoints({ user }: { user: CurrentUser }) {
<div> <div>
<Ticks recent={c.stats?.recent ?? []} /> <Ticks recent={c.stats?.recent ?? []} />
</div> </div>
<button type="button" className="btn btn-link btn-sm p-0" onClick={() => setHistoryFor({ id: c.id, name: c.name })}>
History…
</button>
</td> </td>
<td className="stack-label" data-label="Certificate"> <td className="stack-label" data-label="Certificate">
{c.certDays === null ? ( {c.certDays === null ? (
@@ -488,6 +493,7 @@ export default function Endpoints({ user }: { user: CurrentUser }) {
</div> </div>
<Pagination page={page.page} pageCount={page.pageCount} totalCount={page.totalCount} onPageChange={page.setPage} /> <Pagination page={page.page} pageCount={page.pageCount} totalCount={page.totalCount} onPageChange={page.setPage} />
</div> </div>
{historyFor && <EndpointHistory checkId={historyFor.id} name={historyFor.name} onClose={() => setHistoryFor(null)} />}
</> </>
); );
} }
+7 -16
View File
@@ -1,16 +1,13 @@
import { useEffect, useMemo, useState } from "react"; import { useEffect, useMemo, useState } from "react";
import { Link, useSearchParams } from "react-router-dom"; import { Link, useSearchParams } from "react-router-dom";
import { api, type ServerMetricSeries, type ServerRecord } from "../api/client"; import { api, type ServerMetricSeries, type ServerRecord } from "../api/client";
import MultiLineChart, { type ChartSeries } from "../components/MultiLineChart"; import TimeChart, { type ChartSeries } from "../components/TimeChart";
import RangeSelect from "../components/RangeSelect";
import { CHART_RANGES, useChartRange } from "../utils/chartRanges";
import { BlockSkeleton } from "../components/Skeleton"; import { BlockSkeleton } from "../components/Skeleton";
import ExportTableButton from "../components/ExportTableButton"; import ExportTableButton from "../components/ExportTableButton";
const MAX_SERVERS = 4; const MAX_SERVERS = 4;
const RANGES = [
{ days: 1, label: "24 hours" },
{ days: 7, label: "7 days" },
{ days: 30, label: "30 days" },
];
// A colour and a dash pattern for each line, so they can be told apart by either. // A colour and a dash pattern for each line, so they can be told apart by either.
const LOOKS = [ const LOOKS = [
{ color: "#4299e1", dash: "" }, { color: "#4299e1", dash: "" },
@@ -43,7 +40,7 @@ export default function ServerCompare() {
return [...seen].slice(0, MAX_SERVERS); return [...seen].slice(0, MAX_SERVERS);
}, [params]); }, [params]);
const [days, setDays] = useState(7); const [days, setDays] = useChartRange(7);
const [metric, setMetric] = useState("cpu"); const [metric, setMetric] = useState("cpu");
const [loaded, setLoaded] = useState<Loaded[] | null>(null); const [loaded, setLoaded] = useState<Loaded[] | null>(null);
const [failed, setFailed] = useState(false); const [failed, setFailed] = useState(false);
@@ -98,7 +95,7 @@ export default function ServerCompare() {
}; };
}); });
const chart: ChartSeries[] = rows.filter((r) => r.series).map((r) => ({ name: r.server.name, color: r.look.color, dash: r.look.dash, points: r.series!.points })); const chart: ChartSeries[] = rows.filter((r) => r.series).map((r) => ({ name: r.server.name, color: r.look.color, dash: r.look.dash, points: r.series!.points }));
const summary = `${metricName} over the last ${RANGES.find((r) => r.days === days)?.label}: ${rows.map((r) => `${r.server.name} ${percent(r.now)} now`).join(", ")}`; const summary = `${metricName} over the last ${CHART_RANGES.find((r) => r.days === days)?.label}: ${rows.map((r) => `${r.server.name} ${percent(r.now)} now`).join(", ")}`;
return ( return (
<> <>
@@ -126,13 +123,7 @@ export default function ServerCompare() {
</option> </option>
))} ))}
</select> </select>
<select className="form-select form-select-sm w-auto" aria-label="Time range" value={days} onChange={(e) => setDays(Number(e.target.value))}> <RangeSelect value={days} onChange={setDays} />
{RANGES.map((r) => (
<option key={r.days} value={r.days}>
Last {r.label}
</option>
))}
</select>
<ExportTableButton filename={`compare-${metric}`} /> <ExportTableButton filename={`compare-${metric}`} />
</div> </div>
<div className="card-body"> <div className="card-body">
@@ -145,7 +136,7 @@ export default function ServerCompare() {
{chart.length === 0 ? ( {chart.length === 0 ? (
<div className="text-secondary mb-3">None of these servers has a history for this yet. A sample is kept about every ten minutes once an agent has reported.</div> <div className="text-secondary mb-3">None of these servers has a history for this yet. A sample is kept about every ten minutes once an agent has reported.</div>
) : ( ) : (
<MultiLineChart series={chart} from={to - days * 86_400_000} to={to} label={summary} /> <TimeChart series={chart} from={to - days * 86_400_000} to={to} label={summary} />
)} )}
<div className="table-responsive mt-3"> <div className="table-responsive mt-3">
<table className="table table-vcenter"> <table className="table table-vcenter">
+2
View File
@@ -14,6 +14,7 @@ import {
} from "../api/client"; } from "../api/client";
import ServerPorts from "../components/ServerPorts"; import ServerPorts from "../components/ServerPorts";
import ServerTrends from "../components/ServerTrends"; import ServerTrends from "../components/ServerTrends";
import UptimeHistory from "../components/UptimeHistory";
import ServerActivity from "../components/ServerActivity"; import ServerActivity from "../components/ServerActivity";
import TimeAgo from "../components/TimeAgo"; import TimeAgo from "../components/TimeAgo";
import UptimeRibbon from "../components/UptimeRibbon"; import UptimeRibbon from "../components/UptimeRibbon";
@@ -800,6 +801,7 @@ export default function ServerDetail({ user }: { user: CurrentUser }) {
{view === "history" && ( {view === "history" && (
<> <>
<UptimeHistory kind="servers" id={server.id} name={server.name} />
{hardware.source === "agent" && <ServerTrends serverId={serverId} />} {hardware.source === "agent" && <ServerTrends serverId={serverId} />}
{(user.role === "admin" || user.role === "operator") && <ServerActivity serverId={serverId} />} {(user.role === "admin" || user.role === "operator") && <ServerActivity serverId={serverId} />}
</> </>
+65
View File
@@ -992,6 +992,71 @@ a.map-node:focus-visible {
border-left-color: #48bb78; border-left-color: #48bb78;
} }
/* The one chart (components/TimeChart.tsx). */
.time-chart {
position: relative;
width: 100%;
border-radius: var(--tblr-border-radius, 4px);
}
.time-chart:focus-visible {
outline: 2px solid var(--tblr-primary, #206bc4);
outline-offset: 2px;
}
.time-chart-svg {
display: block;
width: 100%;
height: auto;
color: var(--tblr-body-color);
touch-action: pan-y;
}
.time-chart-empty {
display: flex;
align-items: center;
justify-content: center;
border: 1px dashed var(--tblr-border-color);
text-align: center;
}
.time-chart-tip {
position: absolute;
top: 4px;
z-index: 5;
padding: 0.35rem 0.6rem;
font-size: 0.8rem;
white-space: nowrap;
pointer-events: none;
background: var(--tblr-bg-surface);
border: 1px solid var(--tblr-border-color);
border-radius: 6px;
box-shadow: 0 4px 14px rgba(0, 0, 0, 0.25);
}
.time-chart-tip-time {
margin-bottom: 0.15rem;
color: var(--tblr-secondary-color, #667085);
}
.time-chart-tip-row {
display: flex;
gap: 0.3rem;
align-items: baseline;
}
.time-chart-swatch {
display: inline-block;
flex-shrink: 0;
width: 0.7rem;
height: 0.7rem;
border-radius: 2px;
}
.time-chart-tip-name {
margin-right: 0.3rem;
}
.map-label { .map-label {
display: flex; display: flex;
flex-direction: column; flex-direction: column;
+43
View File
@@ -0,0 +1,43 @@
import { useCallback, useState } from "react";
/** The stretches of time every chart can show, the same everywhere: a day to a year. */
export const CHART_RANGES = [
{ days: 1, label: "24 hours" },
{ days: 7, label: "7 days" },
{ days: 30, label: "30 days" },
{ days: 90, label: "90 days" },
{ days: 365, label: "1 year" },
] as const;
export type ChartDays = (typeof CHART_RANGES)[number]["days"];
const KEY = "chart.range";
const isRange = (n: number): n is ChartDays => CHART_RANGES.some((r) => r.days === n);
function remembered(fallback: ChartDays): ChartDays {
try {
const n = Number(localStorage.getItem(KEY));
return isRange(n) ? n : fallback;
} catch {
return fallback;
}
}
/**
* The range a chart shows, remembered between charts and visits: choosing 30 days on one page means the next chart opens on 30 days as well. A convenience only —
* without storage it is just the default each time.
*/
export function useChartRange(fallback: ChartDays = 7): [ChartDays, (days: number) => void] {
const [days, setDays] = useState<ChartDays>(() => remembered(fallback));
const choose = useCallback((n: number) => {
if (!isRange(n)) return;
setDays(n);
try {
localStorage.setItem(KEY, String(n));
} catch {
// not remembered
}
}, []);
return [days, choose];
}