Add status pages (a share link kind) and a downloadable Grafana dashboard

- Share links can open a status page: an admin picks servers, integrations and Uptime Kuma
  monitors and names them; the public sees only those names, Working / Not working /
  Being worked on / Can't tell, an optional message and the 30-day figure (share_links.kind/
  title/message and status_items, migration 0033). A status address doesn't open the wall and
  the other way round; Uptime Kuma is asked at most every 30 seconds
- Grafana dashboard built from code (download in Settings -> API and webhooks); a test checks
  it only uses series /metrics serves
- Tests and docs

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-18 15:38:08 +02:00
1 parent 2744a84719
commit 5cc51c57de
24 files changed
+4880 -35

No files matched your search

+19
View File
@@ -75,6 +75,25 @@ 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`.
## A Grafana dashboard
Settings → API and webhooks → **Download the dashboard** (administrators) gives `homelab-manager-dashboard.json`; the same file is at
`GET /api/metrics-tokens/grafana-dashboard.json` for a signed-in administrator. In Grafana: **Dashboards → New → Import**, upload it, and
choose your Prometheus when asked (the file never names one, so it isn't tied to any installation). It is a dashboard with a **Server**
picker (taken from `homelab_server_up`) and five rows:
| Row | What it has |
|---|---|
| Needs attention | Critical alerts, warnings, acknowledged, open incidents, servers down and up, integrations failing, maintenance, stale and failed backups, failed services, updates waiting, restarts needed; alerts over time; each integration's state. |
| Servers | One table (up, CPU, memory, updates, security updates, failed services, agent behind), CPU and memory over time, 30-day uptime, time since each agent last reported. |
| Disks | Usage with a 90% line, disks filling up (days to full), SMART health, SSD life used, disk temperature, ZFS pools. |
| Backups | Guests by backup state, the age of each newest backup, and the age, last result and count of Homelab Manager's own backups. |
| Secrets, power and the app itself | Secrets and certificates by days left, the inventory's power draw, how long `/metrics` takes to build. |
The dashboard is built by the app from the same code that serves `/metrics`, and a test checks that it only asks for series that are
really served — so after an upgrade that adds series, download it again to get panels for them. It was written for Grafana 9 and later
and has been checked for structure (every panel on the grid, every query well-formed, every series real), **not** opened in a Grafana here.
## Event webhooks ## Event webhooks
A webhook is a URL (http or https, no user name or password in it) with a list of events it wants. It is A webhook is a URL (http or https, no user name or password in it) with a list of events it wants. It is
+22 -6
View File
@@ -23,8 +23,8 @@ what the app actually creates.
|---|---| |---|---|
| **File** | `DATABASE_PATH`, default `../data/homelab-manager.sqlite` (relative to `server/`; `/app/data/...` in Docker). The folder is created if missing. | | **File** | `DATABASE_PATH`, default `../data/homelab-manager.sqlite` (relative to `server/`; `/app/data/...` in Docker). The folder is created if missing. |
| **Foreign keys** | Switched on for every connection (`PRAGMA foreign_keys = ON`), so the `ON DELETE` rules below are enforced. | | **Foreign keys** | Switched on for every connection (`PRAGMA foreign_keys = ON`), so the `ON DELETE` rules below are enforced. |
| **Migrations** | SQL files in [`server/drizzle/`](server/drizzle) (`0000` … `0032`), applied automatically when the server starts. Which ones have run is recorded in the table `__drizzle_migrations`. | | **Migrations** | SQL files in [`server/drizzle/`](server/drizzle) (`0000` … `0033`), applied automatically when the server starts. Which ones have run is recorded in the table `__drizzle_migrations`. |
| **Tables** | 34 application tables, plus drizzle's own `__drizzle_migrations`. | | **Tables** | 35 application tables, plus drizzle's own `__drizzle_migrations`. |
**Not in the database, but beside it in the data folder:** the backups of the database itself (`backups/homelab-manager-….sqlite`, taken daily and on request; see [BACKUP.md](BACKUP.md)), and, only while a restore is waiting or has just happened, `restore-pending.sqlite` / `restore-pending.json` and `restore-result.json`. **Not in the database, but beside it in the data folder:** the backups of the database itself (`backups/homelab-manager-….sqlite`, taken daily and on request; see [BACKUP.md](BACKUP.md)), and, only while a restore is waiting or has just happened, `restore-pending.sqlite` / `restore-pending.json` and `restore-result.json`.
@@ -103,7 +103,7 @@ Who changed what. Written by the app on every change (see
| `id` | integer PK | | | `id` | integer PK | |
| `actor_user_id` | integer → `users.id`, **set null** on delete | Null for automatic actions, and for entries whose user was deleted. | | `actor_user_id` | integer → `users.id`, **set null** on delete | Null for automatic actions, and for entries whose user was deleted. |
| `actor_label` | text | The user's name/email as it was at the time (or `system`), so an entry still reads correctly after the account is gone. | | `actor_label` | text | The user's name/email as it was at the time (or `system`), so an entry still reads correctly after the account is gone. |
| `category` | text NOT NULL | Free text. In use: `server` (including the health check's own `went_offline`, `back_online`, `disk_full` and `disk_ok`, and `agent_updated` when a server's agent reports a higher version than before, written as `system` and shown on a server's Activity card), `integration` (including the health check's `went_failing` / `recovered` for a kind of service, with `target_type` `integration_type` and the service type as `target_id`, which the dashboard summary and the uptime ribbons read), `dns`, `settings` (including `agent_auto_update`), `ipam`, `secret`, `domain`, `tag`, `task`, `session`, `network`, `maintenance`, `consistency`, `user`, `privacy`, `diag_log`, `alert_ticket`, `share_link` (a link made or removed — never the secret), `runbook`, `alert` (`ack`, `unack` — with the alert's id; on the thing it is about, so they show on a server's Activity card), `incident` (`note`, `note_removed`), `db_backup` (`create`, `upload`, `download`, `delete`, `restore_staged`, `restore_cancelled`, `settings`), `update_run` (`start`, `finished`, `failed`, `cancelled` — shown on the server's Activity card), `inventory`, `metrics_token` and `webhook` (made, changed or removed — never a secret or an address). `user` also records `role_from_groups` when a sign-in changed someone's role. | | `category` | text NOT NULL | Free text. In use: `server` (including the health check's own `went_offline`, `back_online`, `disk_full` and `disk_ok`, and `agent_updated` when a server's agent reports a higher version than before, written as `system` and shown on a server's Activity card), `integration` (including the health check's `went_failing` / `recovered` for a kind of service, with `target_type` `integration_type` and the service type as `target_id`, which the dashboard summary and the uptime ribbons read), `dns`, `settings` (including `agent_auto_update`), `ipam`, `secret`, `domain`, `tag`, `task`, `session`, `network`, `maintenance`, `consistency`, `user`, `privacy`, `diag_log`, `alert_ticket`, `share_link` (a link made or removed, and `update_status_page` when what a status page shows is changed — never the secret), `runbook`, `alert` (`ack`, `unack` — with the alert's id; on the thing it is about, so they show on a server's Activity card), `incident` (`note`, `note_removed`), `db_backup` (`create`, `upload`, `download`, `delete`, `restore_staged`, `restore_cancelled`, `settings`), `update_run` (`start`, `finished`, `failed`, `cancelled` — shown on the server's Activity card), `inventory`, `metrics_token` and `webhook` (made, changed or removed — never a secret or an address). `user` also records `role_from_groups` when a sign-in changed someone's role. |
| `action` | text NOT NULL | `create`, `update`, `delete`, `start`, `stop`, … — free text. | | `action` | text NOT NULL | `create`, `update`, `delete`, `start`, `stop`, … — free text. |
| `target_type`, `target_id` | text | What it happened to. `target_id` is text so it can hold any kind of ID; there's no foreign key. | | `target_type`, `target_id` | text | What it happened to. `target_id` is text so it can hold any kind of ID; there's no foreign key. |
| `detail` | text | JSON, free-form context (what changed, names, counts). Secrets are never put here. | | `detail` | text | JSON, free-form context (what changed, names, counts). Secrets are never put here. |
@@ -618,8 +618,8 @@ URLs sent a signed JSON message when an alert begins or ends or maintenance star
#### `share_links` #### `share_links`
Addresses that open a read-only wall display without signing in (Settings → Share Addresses that open a read-only page without signing in (Settings → Share
links). Only a hash of the secret is stored. links): the wall display, or a status page. Only a hash of the secret is stored.
| Column | Type | Notes | | Column | Type | Notes |
|---|---|---| |---|---|---|
@@ -627,12 +627,28 @@ links). Only a hash of the secret is stored.
| `label` | text NOT NULL | What it is for, e.g. "Hall TV". | | `label` | text NOT NULL | What it is for, e.g. "Hall TV". |
| `token_hash` | text NOT NULL, unique | SHA-256 of the secret in the address; the secret itself is shown once and never stored. | | `token_hash` | text NOT NULL, unique | SHA-256 of the secret in the address; the secret itself is shown once and never stored. |
| `token_prefix` | text NOT NULL | The first characters of the secret, to tell links apart in the list. | | `token_prefix` | text NOT NULL | The first characters of the secret, to tell links apart in the list. |
| `detail` | text NOT NULL, default `summary` | `summary` (numbers only) or `names` (also the names of what is wrong, in maintenance, and the integrations). | | `detail` | text NOT NULL, default `summary` | For a wall: `summary` (numbers only) or `names` (also the names of what is wrong, in maintenance, and the integrations). Not used by a status page. |
| `kind` | text NOT NULL, default `wall` | `wall` or `status`. A status page's address doesn't open the wall, and the other way round. |
| `title`, `message` | text | A status page's heading and its optional message; null for a wall. |
| `created_by` | text | The administrator's name at the time. | | `created_by` | text | The administrator's name at the time. |
| `created_at` | text NOT NULL | | | `created_at` | text NOT NULL | |
| `expires_at` | text | ISO; null = until removed. | | `expires_at` | text | ISO; null = until removed. |
| `last_used_at` | text | ISO; updated at most once a minute. | | `last_used_at` | text | ISO; updated at most once a minute. |
#### `status_items`
What a status page shows, in order.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `link_id` | integer NOT NULL | → `share_links.id`, deleted with the link. |
| `position` | integer NOT NULL | Order on the page (indexed with `link_id`). |
| `label` | text NOT NULL | The name people will recognise — the only thing about it the public sees. |
| `kind` | text NOT NULL | `server`, `integration` or `monitor`. |
| `target_id` | integer NOT NULL | The server, the integration, or the Uptime Kuma a monitor belongs to. A plain reference, **not a foreign key**: if it is removed the item reads "can't tell". |
| `monitor_id` | text | Uptime Kuma's own id for the monitor (`kind` = `monitor`). |
## What's stored inside the JSON columns ## What's stored inside the JSON columns
| Column | Shape | | Column | Shape |
+22
View File
@@ -603,6 +603,28 @@ removed answers the same way, and making and removing links are in the audit log
(without the secret). It is as private as the address: remove it when it isn't (without the secret). It is as private as the address: remove it when it isn't
needed. needed.
**Status pages** are the other thing a share link can open: a page for family or housemates
that answers "is the movie server up?" without a sign-in and without anything that isn't
theirs to see. Pick **A status page** when making a link, then choose what is on it and what
each thing is called ("Movies and TV", "Family photos"): each is a server (reporting, or not
— judged by its own limits), an integration (its latest calls work, or don't) or an Uptime
Kuma monitor. It says *Working*, *Not working*, *Being worked on* (under a maintenance
window) or *Can't tell right now*, with the 30-day figure where one is known, a heading and
an optional message ("Movies are being updated tonight"). The page follows the device's
light or dark setting and looks again every 30 seconds. Whoever has the address is given only
the names you chose and those states — no addresses, no ids, no alert text, nothing about
what the thing really is — and a status page's address doesn't open the wall display (or the
other way round). Uptime Kuma is asked at most every 30 seconds however many people look. Up
to 30 things per page.
**A Grafana dashboard** for the `/metrics` series: Settings → API and webhooks → *Download
the dashboard*, then in Grafana Dashboards → New → Import and pick your Prometheus when
asked. It has rows for what needs attention, servers (with a server picker), disks (usage,
filling up, SMART health, SSD wear, temperature, ZFS pools), backups (guests by state, age
of each newest backup, the app's own backup) and secrets, power and the app itself. It is
built from the same code as `/metrics`, and a test checks that it only asks for series that
are really served. See [API.md](API.md).
**Since you last looked.** The dashboard opens with a card on what happened **Since you last looked.** The dashboard opens with a card on what happened
since you last pressed "Got it" (the first time, the last day; never more than since you last pressed "Got it" (the first time, the last day; never more than
two weeks): servers that stopped reporting or filled a disk, services that two weeks): servers that stopped reporting or filled a disk, services that
+2 -2
View File
@@ -104,8 +104,8 @@ even further, to admin only:
- **Alert limits** on a server's page: everyone can see the ones a server has of its own; only an administrator changes them. - **Alert limits** on a server's page: everyone can see the ones a server has of its own; only an administrator changes them.
- **Host health** (failed services, disk health, ZFS pools) is shown to everyone on a server's page; **Update agents automatically** - **Host health** (failed services, disk health, ZFS pools) is shown to everyone on a server's page; **Update agents automatically**
on the Servers page is admin-only. on the Servers page is admin-only.
- **Sign-in groups, metrics tokens, event webhooks and share links** are all under - **Sign-in groups, metrics tokens, event webhooks, share links (the wall display and the status pages, and what is on them) and the
Settings, so admin-only; `/metrics` itself needs a metrics token, not a login. Grafana dashboard download** are all under Settings, so admin-only; `/metrics` itself needs a metrics token, not a login.
- Everything under **Settings** (notification channels, badge colors, - Everything under **Settings** (notification channels, badge colors,
display prefs, log retention, backup/restore) is admin-only, matching display prefs, log retention, backup/restore) is admin-only, matching
the page itself being admin-only. the page itself being admin-only.
@@ -0,0 +1,15 @@
CREATE TABLE `status_items` (
`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
`link_id` integer NOT NULL,
`position` integer DEFAULT 0 NOT NULL,
`label` text NOT NULL,
`kind` text NOT NULL,
`target_id` integer NOT NULL,
`monitor_id` text,
FOREIGN KEY (`link_id`) REFERENCES `share_links`(`id`) ON UPDATE no action ON DELETE cascade
);
--> statement-breakpoint
CREATE INDEX `status_items_link_idx` ON `status_items` (`link_id`,`position`);--> statement-breakpoint
ALTER TABLE `share_links` ADD `kind` text DEFAULT 'wall' NOT NULL;--> statement-breakpoint
ALTER TABLE `share_links` ADD `title` text;--> statement-breakpoint
ALTER TABLE `share_links` ADD `message` text;
File diff suppressed because it is too large. Load diff
+7
View File
@@ -232,6 +232,13 @@
"when": 1792281947686, "when": 1792281947686,
"tag": "0032_daffy_captain_stacy", "tag": "0032_daffy_captain_stacy",
"breakpoints": true "breakpoints": true
},
{
"idx": 33,
"version": "6",
"when": 1792329463659,
"tag": "0033_bright_princess_powerful",
"breakpoints": true
} }
] ]
} }
+2
View File
@@ -19,6 +19,7 @@ import { backupsRouter } from "./routes/backups.js";
import { metricsRouter, metricsTokensRouter } from "./routes/metrics.js"; import { metricsRouter, metricsTokensRouter } from "./routes/metrics.js";
import { eventWebhooksRouter } from "./routes/eventWebhooks.js"; import { eventWebhooksRouter } from "./routes/eventWebhooks.js";
import { publicWallRouter } from "./routes/publicWall.js"; import { publicWallRouter } from "./routes/publicWall.js";
import { publicStatusRouter } from "./routes/publicStatus.js";
import { usersRouter } from "./routes/users.js"; import { usersRouter } from "./routes/users.js";
import { auditLogRouter } from "./routes/auditLog.js"; import { auditLogRouter } from "./routes/auditLog.js";
import { diagLogRouter } from "./routes/diagLog.js"; import { diagLogRouter } from "./routes/diagLog.js";
@@ -111,6 +112,7 @@ export function createApp() {
// Prometheus scrapes this with a bearer token, not a session. // Prometheus scrapes this with a bearer token, not a session.
app.use("/metrics", metricsRouter); app.use("/metrics", metricsRouter);
app.use("/api/public/wall", publicWallRouter); app.use("/api/public/wall", publicWallRouter);
app.use("/api/public/status", publicStatusRouter);
app.use("/api/users", usersRouter); app.use("/api/users", usersRouter);
app.use("/api/audit-log", auditLogRouter); app.use("/api/audit-log", auditLogRouter);
app.use("/api/diag-log", diagLogRouter); app.use("/api/diag-log", diagLogRouter);
+27
View File
@@ -514,6 +514,10 @@ export const alertTickets = sqliteTable(
export const shareLinkDetails = ["summary", "names"] as const; export const shareLinkDetails = ["summary", "names"] as const;
export type ShareLinkDetail = (typeof shareLinkDetails)[number]; export type ShareLinkDetail = (typeof shareLinkDetails)[number];
// What a link opens: the wall display (how things are, for a TV), or a status page (is each of the things I chose working, for people at home).
export const shareLinkKinds = ["wall", "status"] as const;
export type ShareLinkKind = (typeof shareLinkKinds)[number];
// A link to the wall display that needs no sign-in, for a TV in the hall or someone who only wants to know if things are up. Only a hash // A link to the wall display that needs no sign-in, for a TV in the hall or someone who only wants to know if things are up. Only a hash
// of the secret part of the address is kept (like an agent token), so it can't be read back out of the database or a backup. // of the secret part of the address is kept (like an agent token), so it can't be read back out of the database or a backup.
export const shareLinks = sqliteTable("share_links", { export const shareLinks = sqliteTable("share_links", {
@@ -523,6 +527,10 @@ export const shareLinks = sqliteTable("share_links", {
tokenPrefix: text("token_prefix").notNull(), // the first characters, to tell links apart in the list tokenPrefix: text("token_prefix").notNull(), // the first characters, to tell links apart in the list
// summary = how things are, in numbers; names = also the names of what is wrong, in maintenance, and the integrations // summary = how things are, in numbers; names = also the names of what is wrong, in maintenance, and the integrations
detail: text("detail").$type<ShareLinkDetail>().notNull().default("summary"), detail: text("detail").$type<ShareLinkDetail>().notNull().default("summary"),
kind: text("kind").$type<ShareLinkKind>().notNull().default("wall"),
// A status page's own heading and an optional announcement under it ("Movies are being updated tonight"). Unused by a wall.
title: text("title"),
message: text("message"),
createdBy: text("created_by"), createdBy: text("created_by"),
createdAt: text("created_at") createdAt: text("created_at")
.notNull() .notNull()
@@ -531,6 +539,25 @@ export const shareLinks = sqliteTable("share_links", {
lastUsedAt: text("last_used_at"), // ISO lastUsedAt: text("last_used_at"), // ISO
}); });
// What a status page shows, in order: each with the name people will recognise, and what it points at.
export const statusItemKinds = ["server", "integration", "monitor"] as const;
export type StatusItemKind = (typeof statusItemKinds)[number];
export const statusItems = sqliteTable(
"status_items",
{
id: integer("id").primaryKey({ autoIncrement: true }),
linkId: integer("link_id")
.notNull()
.references(() => shareLinks.id, { onDelete: "cascade" }),
position: integer("position").notNull().default(0),
label: text("label").notNull(),
kind: text("kind").$type<StatusItemKind>().notNull(),
targetId: integer("target_id").notNull(), // the server, the integration, or the Uptime Kuma a monitor belongs to — a plain reference, not a foreign key
monitorId: text("monitor_id"), // Uptime Kuma's id for the monitor (kind = monitor)
},
(t) => [index("status_items_link_idx").on(t.linkId, t.position)],
);
// ─── Recurring maintenance ────────────────────────────────────────────────── // ─── Recurring maintenance ──────────────────────────────────────────────────
// "Every Sunday 02:00–04:00 on these servers": a schedule kept here, turned into ordinary maintenance windows a week ahead (each marked // "Every Sunday 02:00–04:00 on these servers": a schedule kept here, turned into ordinary maintenance windows a week ahead (each marked
+9
View File
@@ -6,6 +6,7 @@ import { metricsTokens } 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 { buildMetrics } from "../services/metrics.js"; import { buildMetrics } from "../services/metrics.js";
import { buildGrafanaDashboard } from "../services/grafanaDashboard.js";
import { createMetricsToken, publicMetricsToken, resolveMetricsToken } from "../services/metricsTokens.js"; import { createMetricsToken, publicMetricsToken, resolveMetricsToken } from "../services/metricsTokens.js";
import { asyncHandler } from "../utils/asyncHandler.js"; import { asyncHandler } from "../utils/asyncHandler.js";
import { rateLimit } from "../utils/rateLimit.js"; import { rateLimit } from "../utils/rateLimit.js";
@@ -34,6 +35,14 @@ metricsTokensRouter.use(requireAuth, requireRole("admin"));
const MAX_TOKENS = 10; const MAX_TOKENS = 10;
// A Grafana dashboard for these series, to import (Dashboards → New → Import). Nothing in it is specific to this installation: Grafana asks which
// Prometheus to use.
metricsTokensRouter.get("/grafana-dashboard.json", asyncHandler(async (_req, res) => {
res.setHeader("Content-Disposition", "attachment; filename=\"homelab-manager-dashboard.json\"");
res.setHeader("Cache-Control", "no-store");
res.json(buildGrafanaDashboard());
}));
metricsTokensRouter.get("/", asyncHandler(async (_req, res) => { metricsTokensRouter.get("/", asyncHandler(async (_req, res) => {
const rows = await db.select().from(metricsTokens).orderBy(metricsTokens.createdAt); const rows = await db.select().from(metricsTokens).orderBy(metricsTokens.createdAt);
res.json({ tokens: rows.map(publicMetricsToken) }); res.json({ tokens: rows.map(publicMetricsToken) });
+19
View File
@@ -0,0 +1,19 @@
import { Router } from "express";
import { NOT_FOUND, resolveShareLink } from "../services/shareLinks.js";
import { buildPublicStatus } from "../services/statusPage.js";
import { rateLimit } from "../utils/rateLimit.js";
import { asyncHandler } from "../utils/asyncHandler.js";
export const publicStatusRouter = Router();
// No sign-in: the secret in the address is the whole of the access, so this reads nothing but the page's own picture, and answers a link that
// doesn't work — never made, ended, taken back, or a wall's rather than a status page's — in the same words.
const limiter = rateLimit({ windowMs: 60_000, max: 60, message: "Too many requests. Wait a minute." });
publicStatusRouter.get("/:token", limiter, asyncHandler(async (req, res) => {
const link = await resolveShareLink(req.params.token);
if (!link || link.kind !== "status") return res.status(404).json(NOT_FOUND);
res.setHeader("Cache-Control", "no-store");
res.setHeader("X-Robots-Tag", "noindex, nofollow");
res.json(await buildPublicStatus(link));
}));
+2 -1
View File
@@ -12,7 +12,8 @@ const limiter = rateLimit({ windowMs: 60_000, max: 60, message: "Too many reques
publicWallRouter.get("/:token", limiter, asyncHandler(async (req, res) => { publicWallRouter.get("/:token", limiter, asyncHandler(async (req, res) => {
const link = await resolveShareLink(req.params.token); const link = await resolveShareLink(req.params.token);
if (!link) return res.status(404).json(NOT_FOUND); // A status page's address doesn't open the wall (and the other way round): each shows only what its link was made to show.
if (!link || link.kind !== "wall") return res.status(404).json(NOT_FOUND);
res.setHeader("Cache-Control", "no-store"); res.setHeader("Cache-Control", "no-store");
res.setHeader("X-Robots-Tag", "noindex, nofollow"); res.setHeader("X-Robots-Tag", "noindex, nofollow");
res.json(await buildPublicWall(link.detail)); res.json(await buildPublicWall(link.detail));
+63 -7
View File
@@ -2,10 +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 { shareLinkDetails, shareLinks } from "../db/schema.js"; import { shareLinkDetails, shareLinkKinds, shareLinks, statusItemKinds, statusItems } 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 { createShareLink, publicShareLink } from "../services/shareLinks.js"; import { createShareLink, publicShareLink } from "../services/shareLinks.js";
import { getStatusItems, MAX_ITEMS, MAX_LABEL, MAX_MESSAGE, MAX_TITLE, setStatusItems, statusChoices, StatusPageError } from "../services/statusPage.js";
import { asyncHandler } from "../utils/asyncHandler.js"; import { asyncHandler } from "../utils/asyncHandler.js";
export const shareLinksRouter = Router(); export const shareLinksRouter = Router();
@@ -18,20 +19,31 @@ const MAX_LINKS = 20;
const createSchema = z.object({ const createSchema = z.object({
label: z.string().trim().min(1).max(60), label: z.string().trim().min(1).max(60),
detail: z.enum(shareLinkDetails), kind: z.enum(shareLinkKinds).default("wall"),
// For a wall: how much it shows. A status page always shows only names and states, so this is ignored for it.
detail: z.enum(shareLinkDetails).default("summary"),
title: z.string().trim().max(MAX_TITLE).optional(),
message: z.string().trim().max(MAX_MESSAGE).optional(),
expiresInDays: z.number().int().min(1).max(365).nullable(), expiresInDays: z.number().int().min(1).max(365).nullable(),
}); });
shareLinksRouter.get("/", asyncHandler(async (_req, res) => { shareLinksRouter.get("/", asyncHandler(async (_req, res) => {
const rows = await db.select().from(shareLinks).orderBy(shareLinks.createdAt); const rows = await db.select().from(shareLinks).orderBy(shareLinks.createdAt);
res.json({ links: rows.map((r) => publicShareLink(r)) }); const counts = new Map<number, number>();
for (const i of await db.select({ linkId: statusItems.linkId }).from(statusItems)) counts.set(i.linkId, (counts.get(i.linkId) ?? 0) + 1);
res.json({ links: rows.map((r) => ({ ...publicShareLink(r), itemCount: counts.get(r.id) ?? 0 })) });
}));
// What a status page can be made of, for the editor: servers and integrations (Uptime Kuma's monitors are read from its own page of the app).
shareLinksRouter.get("/status-choices", asyncHandler(async (_req, res) => {
res.json(await statusChoices());
})); }));
// The secret part of the address is in this response and nowhere else, ever: only a hash of it is kept. // The secret part of the address is in this response and nowhere else, ever: only a hash of it is kept.
shareLinksRouter.post("/", asyncHandler(async (req, res) => { shareLinksRouter.post("/", asyncHandler(async (req, res) => {
const parsed = createSchema.safeParse(req.body); const parsed = createSchema.safeParse(req.body);
if (!parsed.success) { if (!parsed.success) {
return res.status(400).json({ error: "invalid_body", message: "Give the link a name, say how much it shows, and how long it lasts.", details: parsed.error.flatten() }); return res.status(400).json({ error: "invalid_body", message: "Give the link a name, say what it opens and how long it lasts.", details: parsed.error.flatten() });
} }
const existing = await db.select({ id: shareLinks.id }).from(shareLinks); const existing = await db.select({ id: shareLinks.id }).from(shareLinks);
if (existing.length >= MAX_LINKS) { if (existing.length >= MAX_LINKS) {
@@ -45,9 +57,53 @@ shareLinksRouter.post("/", asyncHandler(async (req, res) => {
action: "create", action: "create",
targetType: "share_link", targetType: "share_link",
targetId: link.id, targetId: link.id,
detail: { label: link.label, detail: link.detail, expiresAt: link.expiresAt }, detail: { label: link.label, kind: link.kind, detail: link.detail, expiresAt: link.expiresAt },
}); });
res.status(201).json({ link: publicShareLink(link), token, path: `/share/wall/${token}` }); res.status(201).json({ link: publicShareLink(link), token, path: `/share/${link.kind === "status" ? "status" : "wall"}/${token}` });
}));
const idOf = (v: string) => (/^\d+$/.test(v) ? Number(v) : NaN);
// A status page's heading, message and the things on it.
shareLinksRouter.get("/:id/status", asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const [link] = await db.select().from(shareLinks).where(eq(shareLinks.id, id)).limit(1);
if (!link || link.kind !== "status") return res.status(404).json({ error: "not_found" });
res.json({ title: link.title ?? "", message: link.message ?? "", items: await getStatusItems(id), maxItems: MAX_ITEMS });
}));
const statusSchema = z.object({
title: z.string().trim().max(MAX_TITLE),
message: z.string().trim().max(MAX_MESSAGE),
items: z
.array(
z.object({
label: z.string().trim().min(1).max(MAX_LABEL),
kind: z.enum(statusItemKinds),
targetId: z.number().int().positive(),
monitorId: z.string().max(100).nullable().optional(),
}),
)
.max(MAX_ITEMS),
});
shareLinksRouter.put("/:id/status", asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const [link] = await db.select().from(shareLinks).where(eq(shareLinks.id, id)).limit(1);
if (!link || link.kind !== "status") return res.status(404).json({ error: "not_found" });
const parsed = statusSchema.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: "invalid_body", message: parsed.error.issues[0]?.message ?? "A title, a message and up to thirty named things.", details: parsed.error.flatten() });
try {
await setStatusItems(id, parsed.data.items);
} catch (err) {
if (err instanceof StatusPageError) return res.status(err.status).json({ error: err.code, message: err.message });
throw err;
}
await db.update(shareLinks).set({ title: parsed.data.title || null, message: parsed.data.message || null }).where(eq(shareLinks.id, id));
await recordAudit({ actor: req.currentUser!, category: "share_link", action: "update_status_page", targetType: "share_link", targetId: id, detail: { label: link.label, items: parsed.data.items.map((i) => i.label) } });
res.json({ title: parsed.data.title, message: parsed.data.message, items: await getStatusItems(id) });
})); }));
shareLinksRouter.delete("/:id", asyncHandler(async (req, res) => { shareLinksRouter.delete("/:id", asyncHandler(async (req, res) => {
@@ -56,6 +112,6 @@ shareLinksRouter.delete("/:id", asyncHandler(async (req, res) => {
const [link] = await db.select().from(shareLinks).where(eq(shareLinks.id, id)).limit(1); const [link] = await db.select().from(shareLinks).where(eq(shareLinks.id, id)).limit(1);
if (!link) return res.status(404).json({ error: "not_found" }); if (!link) return res.status(404).json({ error: "not_found" });
await db.delete(shareLinks).where(eq(shareLinks.id, id)); await db.delete(shareLinks).where(eq(shareLinks.id, id));
await recordAudit({ actor: req.currentUser!, category: "share_link", action: "delete", targetType: "share_link", targetId: id, detail: { label: link.label } }); await recordAudit({ actor: req.currentUser!, category: "share_link", action: "delete", targetType: "share_link", targetId: id, detail: { label: link.label, kind: link.kind } });
res.status(204).end(); res.status(204).end();
})); }));
+279
View File
@@ -0,0 +1,279 @@
/**
* A Grafana dashboard for the series `/metrics` serves, built here rather than kept as a file so that it can be tested against what the
* app really emits (a panel for a series that was renamed would otherwise just go blank). It is downloaded from Settings → API and
* webhooks and imported in Grafana (Dashboards → New → Import); Grafana asks which Prometheus to use, so nothing in it is tied to one
* installation.
*
* Laid out in rows — what needs looking at, servers, disks, backups, then the quieter things — each panel on a 24-column grid.
*/
const DS = { type: "prometheus", uid: "${DS_PROMETHEUS}" } as const;
type Panel = Record<string, unknown>;
interface Thresholds {
/** From the lowest: [colour, from]; the first has no lower bound. */
steps: [color: string, from: number | null][];
}
const GREEN = "green";
const YELLOW = "yellow";
const RED = "red";
const BLUE = "blue";
const thresholds = (t: Thresholds) => ({ mode: "absolute", steps: t.steps.map(([color, value]) => ({ color, value })) });
/** Red as soon as there is anything. */
const redAbove0: Thresholds = { steps: [[GREEN, null], [RED, 1]] };
const yellowAbove0: Thresholds = { steps: [[GREEN, null], [YELLOW, 1]] };
class Layout {
private y = 0;
private x = 0;
private rowHeight = 0;
private id = 1;
readonly panels: Panel[] = [];
nextId(): number {
return this.id++;
}
row(title: string): void {
this.endLine();
this.panels.push({ type: "row", id: this.nextId(), title, collapsed: false, gridPos: { h: 1, w: 24, x: 0, y: this.y }, panels: [] });
this.y += 1;
}
private endLine(): void {
if (this.x > 0) {
this.y += this.rowHeight;
this.x = 0;
this.rowHeight = 0;
}
}
add(panel: Panel, w: number, h: number): void {
if (this.x + w > 24) this.endLine();
this.panels.push({ ...panel, id: this.nextId(), gridPos: { h, w, x: this.x, y: this.y } });
this.x += w;
this.rowHeight = Math.max(this.rowHeight, h);
if (this.x >= 24) this.endLine();
}
done(): Panel[] {
this.endLine();
return this.panels;
}
}
const target = (expr: string, legend = "", extra: Record<string, unknown> = {}, refId = "A") => ({ datasource: DS, expr, legendFormat: legend, refId, ...extra });
function stat(title: string, expr: string, options: { unit?: string; thresholds?: Thresholds; legend?: string; description?: string; mappings?: unknown[]; decimals?: number; graph?: boolean } = {}): Panel {
return {
type: "stat",
title,
description: options.description ?? "",
datasource: DS,
targets: [target(expr, options.legend ?? "")],
fieldConfig: {
defaults: {
unit: options.unit ?? "none",
decimals: options.decimals,
thresholds: thresholds(options.thresholds ?? { steps: [[BLUE, null]] }),
mappings: options.mappings ?? [],
color: { mode: "thresholds" },
},
overrides: [],
},
options: { reduceOptions: { calcs: ["lastNotNull"], fields: "", values: false }, colorMode: "background", graphMode: options.graph ? "area" : "none", textMode: "auto", justifyMode: "center", orientation: "auto" },
};
}
function timeseries(title: string, queries: { expr: string; legend: string }[], options: { unit?: string; min?: number; max?: number; thresholds?: Thresholds; description?: string; stack?: boolean } = {}): Panel {
return {
type: "timeseries",
title,
description: options.description ?? "",
datasource: DS,
targets: queries.map((q, i) => target(q.expr, q.legend, {}, String.fromCharCode(65 + i))),
fieldConfig: {
defaults: {
unit: options.unit ?? "none",
min: options.min,
max: options.max,
thresholds: thresholds(options.thresholds ?? { steps: [[GREEN, null]] }),
custom: { drawStyle: "line", lineWidth: 1, fillOpacity: options.stack ? 30 : 8, showPoints: "never", spanNulls: true, stacking: { mode: options.stack ? "normal" : "none" }, thresholdsStyle: { mode: options.thresholds ? "line" : "off" } },
},
overrides: [],
},
options: { legend: { displayMode: "table", placement: "bottom", calcs: ["lastNotNull", "max"] }, tooltip: { mode: "multi", sort: "desc" } },
};
}
function bargauge(title: string, expr: string, legend: string, options: { unit?: string; min?: number; max?: number; thresholds?: Thresholds; description?: string } = {}): Panel {
return {
type: "bargauge",
title,
description: options.description ?? "",
datasource: DS,
targets: [target(expr, legend, { instant: true })],
fieldConfig: { defaults: { unit: options.unit ?? "none", min: options.min, max: options.max, thresholds: thresholds(options.thresholds ?? { steps: [[GREEN, null]] }), color: { mode: "thresholds" } }, overrides: [] },
options: { reduceOptions: { calcs: ["lastNotNull"], fields: "", values: false }, orientation: "horizontal", displayMode: "gradient", showUnfilled: true },
};
}
function table(title: string, queries: { expr: string; name: string }[], options: { unit?: string; description?: string; sortBy?: string; thresholds?: Thresholds; labels?: string[] } = {}): Panel {
// One value column per query, named, with the labels kept as columns and everything else hidden.
const rename: Record<string, string> = {};
const exclude: Record<string, boolean> = { Time: true, __name__: true };
queries.forEach((q, i) => {
rename[queries.length === 1 ? "Value" : `Value #${String.fromCharCode(65 + i)}`] = q.name;
});
return {
type: "table",
title,
description: options.description ?? "",
datasource: DS,
targets: queries.map((q, i) => target(q.expr, "", { instant: true, format: "table" }, String.fromCharCode(65 + i))),
transformations: [
{ id: "merge", options: {} },
{ id: "organize", options: { excludeByName: exclude, renameByName: { ...rename, server: "Server", mount: "Disk", device: "Device", pool: "Pool", guest: "Guest", integration: "Integration", name: "Name", status: "State" } } },
],
fieldConfig: { defaults: { unit: options.unit ?? "none", thresholds: thresholds(options.thresholds ?? { steps: [[GREEN, null]] }), custom: { align: "auto", cellOptions: { type: options.thresholds ? "color-background" : "auto" } } }, overrides: [] },
options: { showHeader: true, sortBy: options.sortBy ? [{ displayName: options.sortBy, desc: false }] : [] },
};
}
function piechart(title: string, expr: string, legend: string): Panel {
return {
type: "piechart",
title,
datasource: DS,
targets: [target(expr, legend, { instant: true })],
fieldConfig: { defaults: { unit: "none", color: { mode: "palette-classic" } }, overrides: [] },
options: { reduceOptions: { calcs: ["lastNotNull"], fields: "", values: false }, pieType: "donut", legend: { displayMode: "table", placement: "right", values: ["value"] }, displayLabels: [] },
};
}
const okFailing = [{ type: "value", options: { "0": { text: "Failing", color: RED, index: 0 }, "1": { text: "OK", color: GREEN, index: 1 } } }];
/** The dashboard, as Grafana's import takes it. */
export function buildGrafanaDashboard(): Record<string, unknown> {
const l = new Layout();
const srv = '{server=~"$server"}';
l.row("Needs attention");
l.add(stat("Critical alerts", 'sum(homelab_alerts{severity="critical"}) or vector(0)', { thresholds: redAbove0, description: "Counts every critical alert, including ones somebody has acknowledged." }), 4, 4);
l.add(stat("Warnings", 'sum(homelab_alerts{severity="warning"}) or vector(0)', { thresholds: yellowAbove0 }), 4, 4);
l.add(stat("Acknowledged", "homelab_alerts_acknowledged", { description: "Somebody has said they are on it." }), 4, 4);
l.add(stat("Open incidents", "homelab_incidents_open", { thresholds: yellowAbove0 }), 4, 4);
l.add(stat("Servers down", "count(homelab_server_up == 0) or vector(0)", { thresholds: redAbove0 }), 4, 4);
l.add(stat("Integrations failing", "count(homelab_integration_up == 0) or vector(0)", { thresholds: redAbove0 }), 4, 4);
l.add(stat("Servers up", "sum(homelab_server_up) or vector(0)", { thresholds: { steps: [[RED, null], [GREEN, 1]] } }), 4, 4);
l.add(stat("In maintenance", "homelab_maintenance_active_windows", { description: "Maintenance windows running now." }), 4, 4);
l.add(stat("Backups gone stale", 'homelab_backup_guests{status="stale"}', { thresholds: yellowAbove0, description: "Proxmox guests whose newest backup is older than its limit." }), 4, 4);
l.add(stat("Failed services", "sum(homelab_server_failed_units) or vector(0)", { thresholds: yellowAbove0 }), 4, 4);
l.add(stat("Updates waiting", "sum(homelab_server_pending_updates) or vector(0)", { thresholds: { steps: [[GREEN, null], [YELLOW, 1], [RED, 50]] } }), 4, 4);
l.add(stat("Need a restart", "sum(homelab_server_reboot_required) or vector(0)", { thresholds: yellowAbove0 }), 4, 4);
l.add(timeseries("Alerts by severity", [{ expr: "homelab_alerts", legend: "{{severity}}" }, { expr: "homelab_alerts_silenced", legend: "silenced" }, { expr: "homelab_alerts_grouped", legend: "folded under a down server" }], { description: "Raised alerts over time." }), 12, 8);
l.add(
stat("Integrations", "homelab_integration_up", { legend: "{{integration}} ({{type}})", mappings: okFailing, thresholds: { steps: [[RED, null], [GREEN, 1]] }, description: "Whether each integration's latest calls work." }),
12,
8,
);
l.row("Servers");
l.add(
table(
"Servers",
[
{ expr: `homelab_server_up${srv}`, name: "Up" },
{ expr: `homelab_server_cpu_load_percent${srv}`, name: "CPU load %" },
{ expr: `homelab_server_memory_used_percent${srv}`, name: "Memory %" },
{ expr: `homelab_server_pending_updates${srv}`, name: "Updates waiting" },
{ expr: `homelab_server_pending_security_updates${srv}`, name: "Security updates" },
{ expr: `homelab_server_failed_units${srv}`, name: "Failed services" },
{ expr: `homelab_server_agent_outdated${srv}`, name: "Agent behind" },
],
{ sortBy: "Server" },
),
24,
9,
);
l.add(timeseries("CPU load", [{ expr: `homelab_server_cpu_load_percent${srv}`, legend: "{{server}}" }], { unit: "percent", min: 0 }), 12, 8);
l.add(timeseries("Memory in use", [{ expr: `homelab_server_memory_used_percent${srv}`, legend: "{{server}}" }], { unit: "percent", min: 0, max: 100 }), 12, 8);
l.add(bargauge("Uptime, last 30 days", `homelab_server_uptime_ratio_30d${srv}`, "{{server}}", { unit: "percentunit", min: 0, max: 1, thresholds: { steps: [[RED, null], [YELLOW, 0.95], [GREEN, 0.99]] } }), 12, 8);
l.add(timeseries("Last report", [{ expr: `time() - homelab_server_last_seen_timestamp_seconds${srv}`, legend: "{{server}}" }], { unit: "s", min: 0, description: "How long since each agent last reported." }), 12, 8);
l.row("Disks");
l.add(timeseries("Disk usage", [{ expr: `homelab_server_disk_used_percent${srv}`, legend: "{{server}} {{mount}}" }], { unit: "percent", min: 0, max: 100, thresholds: { steps: [[GREEN, null], [RED, 90]] } }), 12, 9);
l.add(
table("Disks filling up", [{ expr: `sort(homelab_server_disk_days_to_full${srv})`, name: "Days to full" }], { unit: "d", thresholds: { steps: [[RED, null], [YELLOW, 7], [GREEN, 30]] }, description: "Only disks on a steady climb over the last days." }),
12,
9,
);
l.add(stat("Disk health (SMART)", `homelab_server_disk_healthy${srv}`, { legend: "{{server}} {{device}}", mappings: [{ type: "value", options: { "0": { text: "Failing", color: RED, index: 0 }, "1": { text: "Passes", color: GREEN, index: 1 } } }], thresholds: { steps: [[RED, null], [GREEN, 1]] } }), 8, 6);
l.add(bargauge("SSD life used", `homelab_server_disk_wear_percent${srv}`, "{{server}} {{device}}", { unit: "percent", min: 0, max: 100, thresholds: { steps: [[GREEN, null], [YELLOW, 80], [RED, 90]] } }), 8, 6);
l.add(timeseries("Disk temperature", [{ expr: `homelab_server_disk_temperature_celsius${srv}`, legend: "{{server}} {{device}}" }], { unit: "celsius", thresholds: { steps: [[GREEN, null], [RED, 60]] } }), 8, 6);
l.add(stat("ZFS pools", `homelab_server_zfs_pool_online${srv}`, { legend: "{{server}} / {{pool}}", mappings: [{ type: "value", options: { "0": { text: "Not online", color: RED, index: 0 }, "1": { text: "Online", color: GREEN, index: 1 } } }], thresholds: { steps: [[RED, null], [GREEN, 1]] } }), 24, 4);
l.row("Backups");
l.add(piechart("Proxmox guests by backup state", "homelab_backup_guests", "{{status}}"), 8, 8);
l.add(table("Age of each guest's newest backup", [{ expr: "sort_desc(homelab_backup_last_age_seconds)", name: "Age" }], { unit: "s", thresholds: { steps: [[GREEN, null], [YELLOW, 172800], [RED, 604800]] } }), 16, 8);
l.add(stat("Homelab Manager's own backup", "time() - homelab_selfbackup_last_success_timestamp_seconds", { unit: "s", thresholds: { steps: [[GREEN, null], [YELLOW, 129600], [RED, 172800]] }, description: "How old the newest backup of Homelab Manager's own database is." }), 6, 4);
l.add(stat("Last attempt", "homelab_selfbackup_last_attempt_ok", { mappings: okFailing, thresholds: { steps: [[RED, null], [GREEN, 1]] } }), 6, 4);
l.add(stat("Backups kept", "homelab_selfbackup_snapshots"), 6, 4);
l.add(stat("Failed backups", 'homelab_backup_guests{status="failed"}', { thresholds: redAbove0, description: "Guests whose latest backup failed, or whose newest snapshot failed verification." }), 6, 4);
l.row("Secrets, power and the app itself");
l.add(table("Secrets and certificates", [{ expr: "sort(homelab_secret_expiry_days)", name: "Days left" }], { unit: "d", thresholds: { steps: [[RED, null], [YELLOW, 14], [GREEN, 30]] }, description: "Negative once expired." }), 12, 8);
l.add(timeseries("Power draw (inventory)", [{ expr: "homelab_inventory_power_watts", legend: "typical draw" }], { unit: "watt", min: 0 }), 6, 8);
l.add(timeseries("Time to build /metrics", [{ expr: "homelab_scrape_duration_seconds", legend: "seconds" }], { unit: "s", min: 0 }), 6, 8);
return {
__inputs: [{ name: "DS_PROMETHEUS", label: "Prometheus", description: "The Prometheus that scrapes Homelab Manager", type: "datasource", pluginId: "prometheus", pluginName: "Prometheus" }],
__requires: [
{ type: "grafana", id: "grafana", name: "Grafana", version: "9.0.0" },
{ type: "datasource", id: "prometheus", name: "Prometheus", version: "1.0.0" },
{ type: "panel", id: "stat", name: "Stat", version: "" },
{ type: "panel", id: "timeseries", name: "Time series", version: "" },
{ type: "panel", id: "table", name: "Table", version: "" },
{ type: "panel", id: "bargauge", name: "Bar gauge", version: "" },
{ type: "panel", id: "piechart", name: "Pie chart", version: "" },
],
title: "Homelab Manager",
uid: "homelab-manager",
description: "Servers, disks, backups, alerts and incidents, from Homelab Manager's /metrics. Made by Homelab Manager (Settings → API and webhooks).",
tags: ["homelab", "homelab-manager"],
timezone: "browser",
editable: true,
graphTooltip: 1,
refresh: "1m",
schemaVersion: 39,
version: 1,
time: { from: "now-24h", to: "now" },
timepicker: {},
templating: {
list: [
{
name: "server",
label: "Server",
type: "query",
datasource: DS,
query: { query: "label_values(homelab_server_up, server)", refId: "server" },
definition: "label_values(homelab_server_up, server)",
includeAll: true,
allValue: ".+",
multi: true,
current: { selected: true, text: ["All"], value: ["$__all"] },
refresh: 2,
sort: 1,
hide: 0,
options: [],
},
],
},
annotations: { list: [{ builtIn: 1, datasource: { type: "grafana", uid: "-- Grafana --" }, enable: true, hide: true, iconColor: "rgba(0, 211, 255, 1)", name: "Annotations & Alerts", type: "dashboard" }] },
panels: l.done(),
};
}
+8 -2
View File
@@ -5,7 +5,7 @@
import { createHash, randomBytes } from "node:crypto"; import { createHash, randomBytes } from "node:crypto";
import { eq } from "drizzle-orm"; import { eq } from "drizzle-orm";
import { db } from "../db/client.js"; import { db } from "../db/client.js";
import { shareLinks, type ShareLinkDetail } from "../db/schema.js"; import { shareLinks, type ShareLinkDetail, type ShareLinkKind } from "../db/schema.js";
export type ShareLinkRow = typeof shareLinks.$inferSelect; export type ShareLinkRow = typeof shareLinks.$inferSelect;
@@ -17,7 +17,7 @@ const hash = (token: string) => createHash("sha256").update(token).digest("hex")
/** A link isn't recorded as used more than once in this time, so a screen refreshing every few seconds doesn't write the database each time. */ /** A link isn't recorded as used more than once in this time, so a screen refreshing every few seconds doesn't write the database each time. */
const USED_WRITE_GAP_MS = 60_000; const USED_WRITE_GAP_MS = 60_000;
export async function createShareLink(params: { label: string; detail: ShareLinkDetail; expiresInDays: number | null; createdBy: string; now?: Date }): Promise<{ link: ShareLinkRow; token: string }> { export async function createShareLink(params: { label: string; detail: ShareLinkDetail; kind?: ShareLinkKind; title?: string | null; message?: string | null; expiresInDays: number | null; createdBy: string; now?: Date }): Promise<{ link: ShareLinkRow; token: string }> {
const now = params.now ?? new Date(); const now = params.now ?? new Date();
const token = randomBytes(24).toString("base64url"); const token = randomBytes(24).toString("base64url");
const [link] = await db const [link] = await db
@@ -27,6 +27,9 @@ export async function createShareLink(params: { label: string; detail: ShareLink
tokenHash: hash(token), tokenHash: hash(token),
tokenPrefix: token.slice(0, 6), tokenPrefix: token.slice(0, 6),
detail: params.detail, detail: params.detail,
kind: params.kind ?? "wall",
title: params.title?.trim() || null,
message: params.message?.trim() || null,
createdBy: params.createdBy, createdBy: params.createdBy,
expiresAt: params.expiresInDays === null ? null : new Date(now.getTime() + params.expiresInDays * 86_400_000).toISOString(), expiresAt: params.expiresInDays === null ? null : new Date(now.getTime() + params.expiresInDays * 86_400_000).toISOString(),
}) })
@@ -53,6 +56,9 @@ export function publicShareLink(link: ShareLinkRow, now: Date = new Date()) {
label: link.label, label: link.label,
tokenPrefix: link.tokenPrefix, tokenPrefix: link.tokenPrefix,
detail: link.detail, detail: link.detail,
kind: link.kind,
title: link.title,
message: link.message,
createdBy: link.createdBy, createdBy: link.createdBy,
createdAt: link.createdAt, createdAt: link.createdAt,
expiresAt: link.expiresAt, expiresAt: link.expiresAt,
+208
View File
@@ -0,0 +1,208 @@
/**
* A status page: the one thing someone at home wants to know — "is Plex working?" — without a sign-in and without anything that isn't
* theirs to see. An administrator makes a share link of the status kind and picks what is on it, each with a name people will recognise
* ("Movies", "Photos") instead of what the machine is called. Each is a server (reporting, or not), an integration (its latest calls work,
* or don't) or an Uptime Kuma monitor (up, down, or in maintenance).
*
* What the public gets back is only: the page's title and message, and for each item its name, whether it is up, down, being worked on
* or can't be told, and — where known — how it has done over 30 days. No addresses, no ids, no alert text.
*/
import { and, asc, eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { integrations, servers, statusItems, type StatusItemKind } from "../db/schema.js";
import { createUptimeKumaAdapter, type UptimeKumaMonitor } from "../integrations/uptimekuma/adapter.js";
import { loadIntegrationConfig } from "../integrations/loadIntegration.js";
import { getSourceStatus } from "./integrationHealthMonitor.js";
import { activeSubjects } from "./maintenance.js";
import { effectiveThresholds, parseThresholds } from "./serverThresholds.js";
import { getSettings } from "./settingsStore.js";
import { getUptime } from "./uptimeHistory.js";
export type ItemState = "up" | "down" | "maintenance" | "unknown";
export type PageLevel = "ok" | "issue" | "maintenance" | "unknown";
export const MAX_ITEMS = 30;
export const MAX_LABEL = 60;
export const MAX_TITLE = 60;
export const MAX_MESSAGE = 300;
export interface StatusItemInput {
label: string;
kind: StatusItemKind;
/** The server, the integration, or the Uptime Kuma integration a monitor belongs to. */
targetId: number;
/** For a monitor: Uptime Kuma's own id for it. */
monitorId?: string | null;
}
export class StatusPageError extends Error {
constructor(
readonly status: number,
readonly code: string,
message: string,
) {
super(message);
}
}
export interface StoredItem {
id: number;
label: string;
kind: StatusItemKind;
targetId: number;
monitorId: string | null;
/** What it points at, for the editor: the server's or integration's name, or the monitor's. */
targetName: string | null;
}
export async function getStatusItems(linkId: number): Promise<StoredItem[]> {
const rows = await db.select().from(statusItems).where(eq(statusItems.linkId, linkId)).orderBy(asc(statusItems.position), asc(statusItems.id));
if (rows.length === 0) return [];
const serverNames = new Map((await db.select({ id: servers.id, name: servers.name }).from(servers)).map((s) => [s.id, s.name]));
const integrationNames = new Map((await db.select({ id: integrations.id, name: integrations.name }).from(integrations)).map((i) => [i.id, i.name]));
return rows.map((r) => ({
id: r.id,
label: r.label,
kind: r.kind,
targetId: r.targetId,
monitorId: r.monitorId,
targetName: r.kind === "server" ? (serverNames.get(r.targetId) ?? null) : (integrationNames.get(r.targetId) ?? null),
}));
}
/** Replaces the whole list, in the order given. Everything it points at has to exist; nothing is changed if anything is wrong. */
export async function setStatusItems(linkId: number, items: StatusItemInput[]): Promise<void> {
if (items.length > MAX_ITEMS) throw new StatusPageError(400, "too_many", `A status page can show up to ${MAX_ITEMS} things.`);
const serverIds = new Set((await db.select({ id: servers.id }).from(servers)).map((s) => s.id));
const integrationRows = new Map((await db.select({ id: integrations.id, type: integrations.type }).from(integrations)).map((i) => [i.id, i.type]));
for (const [i, item] of items.entries()) {
const where = `"${item.label}"`;
if (!item.label.trim() || item.label.length > MAX_LABEL) throw new StatusPageError(400, "invalid_label", `Give each thing a name of up to ${MAX_LABEL} characters (item ${i + 1}).`);
if (item.kind === "server" && !serverIds.has(item.targetId)) throw new StatusPageError(400, "unknown_target", `${where} points at a server that doesn't exist.`);
if (item.kind === "integration" && !integrationRows.has(item.targetId)) throw new StatusPageError(400, "unknown_target", `${where} points at an integration that doesn't exist.`);
if (item.kind === "monitor") {
if (integrationRows.get(item.targetId) !== "uptimekuma") throw new StatusPageError(400, "unknown_target", `${where} points at an Uptime Kuma that doesn't exist.`);
if (!item.monitorId || item.monitorId.length > 100) throw new StatusPageError(400, "invalid_monitor", `${where} needs one of Uptime Kuma's monitors.`);
}
}
await db.delete(statusItems).where(eq(statusItems.linkId, linkId));
if (items.length > 0) {
await db.insert(statusItems).values(items.map((item, position) => ({ linkId, position, label: item.label.trim(), kind: item.kind, targetId: item.targetId, monitorId: item.kind === "monitor" ? (item.monitorId ?? null) : null })));
}
}
// ─── The picture the public gets ────────────────────────────────────────────
export interface PublicStatusItem {
id: number;
label: string;
state: ItemState;
/** Percent over the last 30 days, where it is known. */
uptime30d: number | null;
}
export interface PublicStatus {
title: string;
message: string | null;
level: PageLevel;
counts: Record<ItemState, number>;
items: PublicStatusItem[];
generatedAt: string;
display: { dateFormat: string; timeFormat: string };
}
/** How the whole page reads: anything down is an issue; otherwise anything being worked on says so; otherwise fine — unless nothing could be told at all. */
export function pageLevel(counts: Record<ItemState, number>): PageLevel {
if (counts.down > 0) return "issue";
if (counts.maintenance > 0) return "maintenance";
if (counts.up === 0 && counts.unknown > 0) return "unknown";
return "ok";
}
// Uptime Kuma is asked at most this often per instance, however many people have the page open.
const KUMA_CACHE_MS = 30_000;
const kumaCache = new Map<number, { at: number; monitors: Map<string, UptimeKumaMonitor> | null }>();
let kumaLoader: ((integrationId: number) => Promise<UptimeKumaMonitor[] | null>) | null = null;
/** For tests: read monitors from this instead of a real Uptime Kuma. */
export function setKumaLoaderForTests(loader: typeof kumaLoader): void {
kumaLoader = loader;
kumaCache.clear();
}
async function monitorsOf(integrationId: number, now: number): Promise<Map<string, UptimeKumaMonitor> | null> {
const cached = kumaCache.get(integrationId);
if (cached && now - cached.at < KUMA_CACHE_MS) return cached.monitors;
let monitors: Map<string, UptimeKumaMonitor> | null = null;
try {
let list: UptimeKumaMonitor[] | null;
if (kumaLoader) list = await kumaLoader(integrationId);
else {
const loaded = await loadIntegrationConfig(integrationId);
list = loaded && loaded.integration.type === "uptimekuma" && loaded.integration.enabled ? await createUptimeKumaAdapter(loaded.config as never).listMonitors() : null;
}
monitors = list ? new Map(list.map((m) => [m.id, m])) : null;
} catch {
monitors = null; // can't be told, so it says so — never "up"
}
kumaCache.set(integrationId, { at: now, monitors });
return monitors;
}
export async function buildPublicStatus(link: { id: number; label: string; title: string | null; message: string | null }, now: Date = new Date()): Promise<PublicStatus> {
const items = await db.select().from(statusItems).where(eq(statusItems.linkId, link.id)).orderBy(asc(statusItems.position), asc(statusItems.id));
const settings = await getSettings();
const subjects = await activeSubjects(now);
const serverRows = new Map((await db.select().from(servers)).map((s) => [s.id, s]));
const integrationRows = new Map((await db.select({ id: integrations.id, type: integrations.type, enabled: integrations.enabled }).from(integrations)).map((i) => [i.id, i]));
const uptime = items.some((i) => i.kind !== "monitor") ? await getUptime(now, 30).catch(() => null) : null;
const out: PublicStatusItem[] = [];
for (const item of items) {
let state: ItemState = "unknown";
let uptime30d: number | null = null;
if (item.kind === "server") {
const s = serverRows.get(item.targetId);
if (s?.lastSeenAt) {
const limit = effectiveThresholds({ ...settings.healthChecks }, parseThresholds(s.thresholds)).serverOfflineMinutes * 60_000;
const quiet = now.getTime() - Date.parse(s.lastSeenAt) > limit;
state = subjects.has(`server:${s.id}`) ? "maintenance" : quiet ? "down" : "up";
}
uptime30d = uptime?.servers[item.targetId]?.percent ?? null;
} else if (item.kind === "integration") {
const i = integrationRows.get(item.targetId);
if (i?.enabled) {
const status = getSourceStatus(i.type).status;
state = subjects.has(`integration:${i.id}`) ? "maintenance" : status === "ok" ? "up" : status === "failing" ? "down" : "unknown";
}
uptime30d = uptime?.integrations[item.targetId]?.percent ?? null;
} else {
const monitor = item.monitorId ? (await monitorsOf(item.targetId, now.getTime()))?.get(item.monitorId) : undefined;
if (monitor) {
state = monitor.status === "up" ? "up" : monitor.status === "down" ? "down" : monitor.status === "maintenance" ? "maintenance" : "unknown";
uptime30d = monitor.uptime30d;
}
}
out.push({ id: item.id, label: item.label, state, uptime30d: uptime30d === null ? null : Math.round(uptime30d * 10) / 10 });
}
const counts: Record<ItemState, number> = { up: 0, down: 0, maintenance: 0, unknown: 0 };
for (const o of out) counts[o.state]++;
return {
title: link.title?.trim() || link.label,
message: link.message?.trim() || null,
level: pageLevel(counts),
counts,
items: out,
generatedAt: now.toISOString(),
display: { dateFormat: settings.display.dateFormat, timeFormat: settings.display.timeFormat },
};
}
/** What an administrator can choose from, for the editor: servers and integrations (monitors are read from each Uptime Kuma on request). */
export async function statusChoices(): Promise<{ servers: { id: number; name: string }[]; integrations: { id: number; name: string; type: string }[] }> {
const s = await db.select({ id: servers.id, name: servers.name }).from(servers).orderBy(asc(servers.name));
const i = await db.select({ id: integrations.id, name: integrations.name, type: integrations.type }).from(integrations).where(and(eq(integrations.enabled, true))).orderBy(asc(integrations.name));
return { servers: s, integrations: i };
}
+176
View File
@@ -0,0 +1,176 @@
/**
* The Grafana dashboard: that it is a dashboard Grafana will import, that every panel sits on the grid, and — the point of building it
* here — that it only asks for series `/metrics` really serves, so renaming one can't quietly blank a panel.
*
* Run with: npm test --workspace server
*/
import { test, describe, before, after } from "node:test";
import assert from "node:assert/strict";
import { mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import type { AddressInfo } from "node:net";
import type { Server } from "node:http";
const dir = mkdtempSync(join(tmpdir(), "hm-grafana-"));
process.env.DATABASE_PATH = join(dir, "test.sqlite");
process.env.SESSION_DIR = join(dir, "sessions");
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
const express = (await import("express")).default;
const { db } = await import("../src/db/client.js");
const { users } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const { buildGrafanaDashboard } = await import("../src/services/grafanaDashboard.js");
const { metricsTokensRouter } = await import("../src/routes/metrics.js");
await runMigrations();
type Panel = { id: number; type: string; title: string; gridPos: { h: number; w: number; x: number; y: number }; targets?: { expr: string; legendFormat: string; refId: string; datasource: { uid: string } }[]; datasource?: { uid: string } };
const dashboard = buildGrafanaDashboard() as { panels: Panel[]; templating: { list: { name: string }[] }; __inputs: { name: string }[]; uid: string; title: string; schemaVersion: number };
const panels = dashboard.panels;
const withQueries = panels.filter((p) => p.targets);
const exprs = withQueries.flatMap((p) => p.targets!.map((t) => t.expr));
// What /metrics can serve: every series the code that builds it adds.
const here = dirname(fileURLToPath(import.meta.url));
const served = new Set([...readFileSync(join(here, "..", "src", "services", "metrics.ts"), "utf8").matchAll(/out\.add\(\s*"(homelab_[a-z0-9_]+)"/g)].map((m) => m[1]));
describe("the dashboard is one Grafana will import", () => {
test("it has a title, a fixed id, asks which Prometheus to use, and every query uses that choice", () => {
assert.equal(dashboard.title, "Homelab Manager");
assert.equal(dashboard.uid, "homelab-manager");
assert.ok(dashboard.schemaVersion >= 36);
assert.deepEqual(dashboard.__inputs.map((i) => i.name), ["DS_PROMETHEUS"]);
for (const p of withQueries) {
assert.equal(p.datasource?.uid, "${DS_PROMETHEUS}", p.title);
for (const t of p.targets!) assert.equal(t.datasource.uid, "${DS_PROMETHEUS}", `${p.title} / ${t.refId}`);
}
});
test("it survives being written out and read back, as an import does", () => {
const again = JSON.parse(JSON.stringify(dashboard));
assert.equal(again.panels.length, panels.length);
assert.ok(panels.length >= 30, `${panels.length} panels`);
});
test("every panel has an id of its own, a title, and sits on the 24-column grid without overlapping another", () => {
assert.equal(new Set(panels.map((p) => p.id)).size, panels.length, "ids are unique");
for (const p of panels) {
assert.ok(p.title, `panel ${p.id} has no title`);
const g = p.gridPos;
assert.ok(g.x >= 0 && g.w >= 1 && g.x + g.w <= 24, `${p.title} sits outside the grid: ${JSON.stringify(g)}`);
assert.ok(g.h >= 1 && g.y >= 0);
}
for (let i = 0; i < panels.length; i++) {
for (let j = i + 1; j < panels.length; j++) {
const a = panels[i].gridPos;
const b = panels[j].gridPos;
const overlap = a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
assert.equal(overlap, false, `${panels[i].title} overlaps ${panels[j].title}`);
}
}
});
test("it is in rows, and the rows come in a sensible order", () => {
const rows = panels.filter((p) => p.type === "row").map((p) => p.title);
assert.deepEqual(rows, ["Needs attention", "Servers", "Disks", "Backups", "Secrets, power and the app itself"]);
const ys = panels.filter((p) => p.type === "row").map((p) => p.gridPos.y);
assert.deepEqual([...ys].sort((a, b) => a - b), ys, "top to bottom");
});
});
describe("what it asks for", () => {
test("it asks only for series /metrics serves (and says so if one is renamed)", () => {
assert.ok(served.size >= 30, `found ${served.size} served series in metrics.ts`);
const asked = new Set(exprs.flatMap((e) => e.match(/\bhomelab_[a-z0-9_]+\b/g) ?? []));
assert.ok(asked.size >= 25, `the dashboard uses ${asked.size} series`);
const missing = [...asked].filter((m) => !served.has(m));
assert.deepEqual(missing, [], `series the dashboard uses that /metrics doesn't serve: ${missing.join(", ")}`);
});
test("the big groups of series are all covered", () => {
const asked = new Set(exprs.flatMap((e) => e.match(/\bhomelab_[a-z0-9_]+\b/g) ?? []));
for (const m of [
"homelab_alerts", "homelab_incidents_open", "homelab_server_up", "homelab_server_disk_used_percent", "homelab_server_disk_days_to_full", "homelab_server_disk_healthy",
"homelab_server_zfs_pool_online", "homelab_backup_guests", "homelab_backup_last_age_seconds", "homelab_selfbackup_last_success_timestamp_seconds", "homelab_secret_expiry_days",
"homelab_integration_up", "homelab_server_uptime_ratio_30d", "homelab_server_pending_updates",
]) assert.ok(asked.has(m), `${m} has no panel`);
});
test("each query is well-formed: not empty, brackets and quotes balanced, no stray template text", () => {
for (const p of withQueries) {
for (const t of p.targets!) {
const e = t.expr;
assert.ok(e.trim().length > 0, `${p.title}: empty query`);
for (const [open, close] of [["(", ")"], ["{", "}"], ["[", "]"]]) assert.equal(e.split(open).length, e.split(close).length, `${p.title}: unbalanced ${open}${close} in ${e}`);
assert.equal(e.split('"').length % 2, 1, `${p.title}: an unclosed quote in ${e}`);
assert.doesNotMatch(e, /undefined|\[object/, `${p.title}: ${e}`);
}
}
});
test("the server picker exists, takes its values from the series, and everything that uses it is told how", () => {
const names = dashboard.templating.list.map((v) => v.name);
assert.deepEqual(names, ["server"]);
const variable = dashboard.templating.list[0] as unknown as { query: { query: string }; allValue: string; multi: boolean };
assert.equal(variable.query.query, "label_values(homelab_server_up, server)");
assert.equal(variable.multi, true);
assert.equal(variable.allValue, ".+", "all servers, including ones with no label at all, matches");
const using = exprs.filter((e) => e.includes("$server"));
assert.ok(using.length >= 10);
for (const e of using) assert.match(e, /\{server=~"\$server"\}/);
});
test("series that exist only once something happens use 'or vector(0)' where a stat would otherwise read 'No data'", () => {
for (const title of ["Critical alerts", "Warnings", "Servers down", "Integrations failing", "Servers up"]) {
const p = withQueries.find((x) => x.title === title)!;
assert.match(p.targets![0].expr, /or vector\(0\)/, title);
}
});
});
describe("downloading it", () => {
let app: Server;
let base = "";
let who = "ada";
before(async () => {
await db.insert(users).values([
{ oidcSub: "ada", name: "Ada", role: "admin" },
{ oidcSub: "olle", name: "Olle", role: "operator" },
]);
const a = express();
a.use(express.json());
a.use((req, _res, next) => {
(req as unknown as { session: unknown }).session = { user: { sub: who } };
next();
});
a.use("/api/metrics-tokens", metricsTokensRouter);
app = await new Promise<Server>((resolve) => {
const x = a.listen(0, "127.0.0.1", () => resolve(x));
});
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/metrics-tokens`;
});
after(() => {
app.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows keeps the database file locked until the process exits.
}
});
test("an administrator gets it as a file; nobody else does", async () => {
who = "olle";
assert.equal((await fetch(`${base}/grafana-dashboard.json`)).status, 403);
who = "ada";
const res = await fetch(`${base}/grafana-dashboard.json`);
assert.equal(res.status, 200);
assert.match(res.headers.get("content-disposition") ?? "", /attachment; filename="homelab-manager-dashboard\.json"/);
assert.match(res.headers.get("content-type") ?? "", /application\/json/);
const body = await res.json();
assert.equal(body.uid, "homelab-manager");
assert.equal(body.panels.length, panels.length);
});
});
+351
View File
@@ -0,0 +1,351 @@
/**
* The status page behind a share link: what can be put on it, how each thing reads, what the public is and isn't given, and that a status
* page's address and a wall's address each open only their own.
*
* 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-statuspage-"));
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, integrations, shareLinks, statusItems, maintenanceWindows, auditLog } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const { createShareLink } = await import("../src/services/shareLinks.js");
const sp = await import("../src/services/statusPage.js");
const { trackIntegrationHealth } = await import("../src/services/integrationHealthMonitor.js");
const { shareLinksRouter } = await import("../src/routes/shareLinks.js");
const { publicStatusRouter } = await import("../src/routes/publicStatus.js");
const { publicWallRouter } = await import("../src/routes/publicWall.js");
const { eq } = await import("drizzle-orm");
await runMigrations();
const NOW = new Date("2026-10-17T12:00:00.000Z");
const minutesAgo = (m: number) => new Date(NOW.getTime() - m * 60_000).toISOString();
describe("how the whole page reads", () => {
const c = (up: number, down: number, maintenance: number, unknown: number) => ({ up, down, maintenance, unknown });
test("anything down is a problem; otherwise anything being worked on says so; nothing known at all is unknown", () => {
assert.equal(sp.pageLevel(c(5, 0, 0, 0)), "ok");
assert.equal(sp.pageLevel(c(4, 1, 1, 1)), "issue");
assert.equal(sp.pageLevel(c(4, 0, 1, 1)), "maintenance");
assert.equal(sp.pageLevel(c(4, 0, 0, 1)), "ok", "one thing that can't be told doesn't spoil the rest");
assert.equal(sp.pageLevel(c(0, 0, 0, 3)), "unknown");
assert.equal(sp.pageLevel(c(0, 0, 0, 0)), "ok", "an empty page isn't alarming");
});
});
describe("what can be put on it", () => {
let linkId = 0;
let serverId = 0;
let kumaId = 0;
let semId = 0;
before(async () => {
const { link } = await createShareLink({ label: "Family", detail: "summary", kind: "status", expiresInDays: null, createdBy: "Ada" });
linkId = link.id;
const [s] = await db.insert(servers).values({ name: "elsa", apiTokenHash: "x", apiTokenPrefix: "x", lastSeenAt: minutesAgo(1) }).returning();
serverId = s.id;
const [k] = await db.insert(integrations).values({ type: "uptimekuma", name: "Kuma", baseUrl: "https://kuma.lab", config: "{}", enabled: false }).returning();
kumaId = k.id;
const [m] = await db.insert(integrations).values({ type: "semaphore", name: "Semaphore", baseUrl: "https://sem.lab", config: "{}", enabled: false }).returning();
semId = m.id;
});
const rejects = (items: Parameters<typeof sp.setStatusItems>[1], code: string) => assert.rejects(sp.setStatusItems(linkId, items), (e: unknown) => e instanceof sp.StatusPageError && e.code === code, code);
test("a server, an integration and a monitor, in the order given, each with its own name; saving again replaces the list", async () => {
await sp.setStatusItems(linkId, [
{ label: " Movies ", kind: "monitor", targetId: kumaId, monitorId: "12" },
{ label: "Files", kind: "server", targetId: serverId },
{ label: "Automation", kind: "integration", targetId: semId },
]);
const items = await sp.getStatusItems(linkId);
assert.deepEqual(items.map((i) => [i.label, i.kind, i.targetName, i.monitorId]), [["Movies", "monitor", "Kuma", "12"], ["Files", "server", "elsa", null], ["Automation", "integration", "Semaphore", null]]);
await sp.setStatusItems(linkId, [{ label: "Just files", kind: "server", targetId: serverId }]);
assert.deepEqual((await sp.getStatusItems(linkId)).map((i) => i.label), ["Just files"]);
await sp.setStatusItems(linkId, []);
assert.deepEqual(await sp.getStatusItems(linkId), []);
});
test("what doesn't exist, or isn't what it says, is refused with a reason — and nothing changes", async () => {
await sp.setStatusItems(linkId, [{ label: "Keep me", kind: "server", targetId: serverId }]);
await rejects([{ label: "Ghost", kind: "server", targetId: 99999 }], "unknown_target");
await rejects([{ label: "Ghost", kind: "integration", targetId: 99999 }], "unknown_target");
await rejects([{ label: "Monitor on the wrong thing", kind: "monitor", targetId: semId, monitorId: "1" }], "unknown_target");
await rejects([{ label: "No monitor", kind: "monitor", targetId: kumaId }], "invalid_monitor");
await rejects([{ label: "No monitor", kind: "monitor", targetId: kumaId, monitorId: "x".repeat(101) }], "invalid_monitor");
await rejects([{ label: " ", kind: "server", targetId: serverId }], "invalid_label");
await rejects([{ label: "x".repeat(sp.MAX_LABEL + 1), kind: "server", targetId: serverId }], "invalid_label");
await rejects(Array.from({ length: sp.MAX_ITEMS + 1 }, (_, i) => ({ label: `n${i}`, kind: "server" as const, targetId: serverId })), "too_many");
assert.deepEqual((await sp.getStatusItems(linkId)).map((i) => i.label), ["Keep me"], "the list is as it was");
});
});
describe("how each thing reads", () => {
let linkId = 0;
let link: Awaited<ReturnType<typeof createShareLink>>["link"];
let kumaId = 0;
let sem = 0;
const ids: Record<string, number> = {};
const monitor = (id: string, status: string, uptime30d: number | null = 99.123) => ({ id, name: `private name ${id}`, type: "http", target: "10.1.2.3", port: 443, status, responseTimeMs: 5, certDaysRemaining: null, uptime24h: 100, uptime30d, uptime1y: 100 }) as never;
before(async () => {
({ link } = await createShareLink({ label: "Family", detail: "summary", kind: "status", title: " Our home ", message: " Movies are being updated tonight. ", expiresInDays: null, createdBy: "Ada" }));
linkId = link.id;
const mk = async (name: string, extra: Partial<typeof servers.$inferInsert> = {}) => (await db.insert(servers).values({ name, apiTokenHash: name, apiTokenPrefix: "x", ...extra }).returning())[0].id;
ids.up = await mk("up", { lastSeenAt: minutesAgo(5) });
ids.down = await mk("down", { lastSeenAt: minutesAgo(180) });
ids.never = await mk("never");
ids.worked = await mk("worked", { lastSeenAt: minutesAgo(180) });
ids.laptop = await mk("laptop", { lastSeenAt: minutesAgo(180), thresholds: JSON.stringify({ serverOfflineMinutes: 600 }) });
await db.insert(maintenanceWindows).values({ targetType: "server", targetId: ids.worked, reason: "x", startedAt: minutesAgo(30), endsAt: new Date(NOW.getTime() + 3600_000).toISOString() });
kumaId = (await db.insert(integrations).values({ type: "uptimekuma", name: "Kuma", baseUrl: "https://kuma.lab", config: "{}", enabled: true }).returning())[0].id;
sem = (await db.insert(integrations).values({ type: "semaphore", name: "Semaphore", baseUrl: "https://sem.lab", config: "{}", enabled: true }).returning())[0].id;
await trackIntegrationHealth("semaphore", true);
await sp.setStatusItems(linkId, [
{ label: "Files", kind: "server", targetId: ids.up },
{ label: "Backups", kind: "server", targetId: ids.down },
{ label: "Printer", kind: "server", targetId: ids.never },
{ label: "Photos", kind: "server", targetId: ids.worked },
{ label: "Laptop", kind: "server", targetId: ids.laptop },
{ label: "Automation", kind: "integration", targetId: sem },
{ label: "Movies", kind: "monitor", targetId: kumaId, monitorId: "m-up" },
{ label: "Music", kind: "monitor", targetId: kumaId, monitorId: "m-down" },
{ label: "Podcasts", kind: "monitor", targetId: kumaId, monitorId: "m-maint" },
{ label: "Books", kind: "monitor", targetId: kumaId, monitorId: "m-pending" },
{ label: "Gone", kind: "monitor", targetId: kumaId, monitorId: "m-missing" },
]);
sp.setKumaLoaderForTests(async () => [monitor("m-up", "up"), monitor("m-down", "down", 80.04), monitor("m-maint", "maintenance"), monitor("m-pending", "pending", null)]);
});
after(() => sp.setKumaLoaderForTests(null));
const stateOf = (page: Awaited<ReturnType<typeof sp.buildPublicStatus>>) => Object.fromEntries(page.items.map((i) => [i.label, i.state]));
test("a server is up if it reported lately, down if not, unknown if it never has, and 'being worked on' during maintenance — whatever it is doing", async () => {
const page = await sp.buildPublicStatus(link, NOW);
const s = stateOf(page);
assert.equal(s.Files, "up");
assert.equal(s.Backups, "down");
assert.equal(s.Printer, "unknown");
assert.equal(s.Photos, "maintenance", "quiet for three hours, but it is under a maintenance window");
assert.equal(s.Laptop, "up", "its own limit of ten hours applies");
});
test("an integration is up while its calls work", async () => {
assert.equal(stateOf(await sp.buildPublicStatus(link, NOW)).Automation, "up");
await trackIntegrationHealth("semaphore", false);
assert.equal(stateOf(await sp.buildPublicStatus(link, NOW)).Automation, "down");
await trackIntegrationHealth("semaphore", true);
await db.insert(maintenanceWindows).values({ targetType: "integration", targetId: sem, reason: "x", startedAt: minutesAgo(10), endsAt: new Date(NOW.getTime() + 3600_000).toISOString() });
await trackIntegrationHealth("semaphore", false);
assert.equal(stateOf(await sp.buildPublicStatus(link, NOW)).Automation, "maintenance");
await db.delete(maintenanceWindows).where(eq(maintenanceWindows.targetId, sem));
await trackIntegrationHealth("semaphore", true);
});
test("a monitor reads as Uptime Kuma says; one that is checking, or is gone, can't be told — never 'up'", async () => {
const s = stateOf(await sp.buildPublicStatus(link, NOW));
assert.equal(s.Movies, "up");
assert.equal(s.Music, "down");
assert.equal(s.Podcasts, "maintenance");
assert.equal(s.Books, "unknown");
assert.equal(s.Gone, "unknown");
});
test("when Uptime Kuma can't be reached its monitors can't be told, and the rest of the page still works", async () => {
sp.setKumaLoaderForTests(async () => {
throw new Error("connection refused");
});
const page = await sp.buildPublicStatus(link, NOW);
const s = stateOf(page);
assert.equal(s.Movies, "unknown");
assert.equal(s.Music, "unknown");
assert.equal(s.Files, "up");
sp.setKumaLoaderForTests(async () => [monitor("m-up", "up"), monitor("m-down", "down", 80.04), monitor("m-maint", "maintenance"), monitor("m-pending", "pending", null)]);
});
test("Uptime Kuma is asked once in a while, not on every look at the page", async () => {
let asked = 0;
sp.setKumaLoaderForTests(async () => {
asked++;
return [monitor("m-up", "up")];
});
await sp.buildPublicStatus(link, NOW);
await sp.buildPublicStatus(link, new Date(NOW.getTime() + 5_000));
await sp.buildPublicStatus(link, new Date(NOW.getTime() + 10_000));
assert.equal(asked, 1);
sp.setKumaLoaderForTests(async () => [monitor("m-up", "up"), monitor("m-down", "down", 80.04), monitor("m-maint", "maintenance"), monitor("m-pending", "pending", null)]);
});
test("the page has its title and message, the counts, and the overall reading", async () => {
const page = await sp.buildPublicStatus(link, NOW);
assert.equal(page.title, "Our home");
assert.equal(page.message, "Movies are being updated tonight.");
assert.deepEqual(page.counts, { up: 4, down: 2, maintenance: 2, unknown: 3 });
assert.equal(page.level, "issue");
assert.deepEqual(page.items.map((i) => i.label), ["Files", "Backups", "Printer", "Photos", "Laptop", "Automation", "Movies", "Music", "Podcasts", "Books", "Gone"], "in the order they were put");
assert.equal(page.items.find((i) => i.label === "Music")!.uptime30d, 80, "30-day uptime from Uptime Kuma, to one decimal");
assert.equal(page.items.find((i) => i.label === "Books")!.uptime30d, null);
// with no title the link's own name is used, and no message is none
const bare = await sp.buildPublicStatus({ ...link, title: null, message: " " }, NOW);
assert.equal(bare.title, "Family");
assert.equal(bare.message, null);
});
test("the public is given names and states and nothing else", async () => {
const text = JSON.stringify(await sp.buildPublicStatus(link, NOW));
for (const secret of ["10.1.2.3", "kuma.lab", "sem.lab", "private name", "m-up", "apiToken", "elsa", "tok"]) assert.ok(!text.includes(secret), `the page leaks "${secret}"`);
assert.deepEqual(Object.keys(JSON.parse(text)).sort(), ["counts", "display", "generatedAt", "items", "level", "message", "title"]);
assert.deepEqual(Object.keys(JSON.parse(text).items[0]).sort(), ["id", "label", "state", "uptime30d"]);
});
test("a page with nothing on it is a page, not an error", async () => {
const { link: empty } = await createShareLink({ label: "Empty", detail: "summary", kind: "status", expiresInDays: null, createdBy: "Ada" });
const page = await sp.buildPublicStatus(empty, NOW);
assert.deepEqual(page.items, []);
assert.equal(page.level, "ok");
});
});
describe("through the routes", () => {
let app: Server;
let base = "";
let who = "ada";
let statusToken = "";
let statusLinkId = 0;
let wallToken = "";
let serverId = 0;
const call = (method: string, path: string, body?: unknown) => fetch(`${base}${path}`, { method, headers: { "content-type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
before(async () => {
await db.insert(users).values([
{ oidcSub: "ada", name: "Ada", role: "admin" },
{ oidcSub: "olle", name: "Olle", role: "operator" },
]);
serverId = (await db.insert(servers).values({ name: "plexbox", apiTokenHash: "p", apiTokenPrefix: "p", lastSeenAt: new Date().toISOString() }).returning())[0].id;
const a = express();
a.use(express.json());
a.use((req, _res, next) => {
(req as unknown as { session: unknown }).session = { user: { sub: who } };
next();
});
a.use("/api/share-links", shareLinksRouter);
a.use("/api/public/status", publicStatusRouter);
a.use("/api/public/wall", publicWallRouter);
app = await new Promise<Server>((resolve) => {
const x = a.listen(0, "127.0.0.1", () => resolve(x));
});
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api`;
});
after(() => {
app.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows keeps the database file locked until the process exits.
}
});
test("only an administrator makes a status page; its address is under /share/status and shown once", async () => {
who = "olle";
assert.equal((await call("POST", "/share-links", { label: "x", kind: "status", expiresInDays: null })).status, 403);
assert.equal((await call("GET", "/share-links/status-choices")).status, 403);
who = "ada";
const res = await call("POST", "/share-links", { label: "Family", kind: "status", title: "Our home", message: "Hello", expiresInDays: null });
assert.equal(res.status, 201);
const body = await res.json();
assert.match(body.path, /^\/share\/status\/[A-Za-z0-9_-]{20,}$/);
statusToken = body.path.split("/").pop();
statusLinkId = body.link.id;
assert.equal(body.link.kind, "status");
assert.equal(body.link.title, "Our home");
const wall = await (await call("POST", "/share-links", { label: "Hall TV", expiresInDays: null })).json();
assert.match(wall.path, /^\/share\/wall\//, "a link made the old way is still a wall");
assert.equal(wall.link.kind, "wall");
wallToken = wall.path.split("/").pop();
const list = await (await call("GET", "/share-links")).json();
const mine = list.links.filter((l: { id: number }) => l.id === statusLinkId || l.id === wall.link.id);
assert.deepEqual(mine.map((l: { kind: string; itemCount: number }) => [l.kind, l.itemCount]), [["status", 0], ["wall", 0]]);
assert.ok(!JSON.stringify(list).includes(statusToken), "the secret is not in the list");
});
test("the editor reads and saves the page; a wall has no such page", async () => {
const choices = await (await call("GET", "/share-links/status-choices")).json();
assert.ok(choices.servers.some((s: { name: string }) => s.name === "plexbox"), "the servers to choose from");
assert.ok(Array.isArray(choices.integrations));
const before = await (await call("GET", `/share-links/${statusLinkId}/status`)).json();
assert.deepEqual(before, { title: "Our home", message: "Hello", items: [], maxItems: 30 });
const saved = await call("PUT", `/share-links/${statusLinkId}/status`, { title: "Our home network", message: "", items: [{ label: "Movies", kind: "server", targetId: serverId }] });
assert.equal(saved.status, 200);
const out = await saved.json();
assert.equal(out.items[0].label, "Movies");
assert.equal(out.items[0].targetName, "plexbox");
assert.equal((await (await call("GET", `/share-links/${statusLinkId}/status`)).json()).title, "Our home network");
assert.equal((await (await call("GET", "/share-links")).json()).links.find((l: { id: number }) => l.id === statusLinkId).itemCount, 1);
const bad = await call("PUT", `/share-links/${statusLinkId}/status`, { title: "x", message: "", items: [{ label: "Ghost", kind: "server", targetId: 99999 }] });
assert.equal(bad.status, 400);
assert.match((await bad.json()).message, /server that doesn't exist/);
assert.equal((await (await call("GET", `/share-links/${statusLinkId}/status`)).json()).items.length, 1, "nothing changed");
assert.equal((await call("PUT", `/share-links/${statusLinkId}/status`, { title: "x" })).status, 400);
const wallId = (await (await call("GET", "/share-links")).json()).links.find((l: { kind: string }) => l.kind === "wall").id;
assert.equal((await call("GET", `/share-links/${wallId}/status`)).status, 404);
assert.equal((await call("PUT", `/share-links/${wallId}/status`, { title: "", message: "", items: [] })).status, 404);
assert.equal((await call("GET", "/share-links/x/status")).status, 400);
who = "olle";
assert.equal((await call("PUT", `/share-links/${statusLinkId}/status`, { title: "", message: "", items: [] })).status, 403);
who = "ada";
const entry = (await db.select().from(auditLog)).filter((e) => e.action === "update_status_page").pop()!;
assert.deepEqual(JSON.parse(entry.detail!).items, ["Movies"]);
});
test("anyone with the address can read the page — no sign-in — and it is never cached or indexed", async () => {
who = "nobody-signed-in";
const res = await call("GET", `/public/status/${statusToken}`);
assert.equal(res.status, 200);
assert.equal(res.headers.get("cache-control"), "no-store");
assert.match(res.headers.get("x-robots-tag") ?? "", /noindex/);
const page = await res.json();
assert.equal(page.title, "Our home network");
assert.deepEqual(page.items.map((i: { label: string; state: string }) => [i.label, i.state]), [["Movies", "up"]]);
assert.equal(page.level, "ok");
assert.ok(!JSON.stringify(page).includes("plexbox"));
who = "ada";
});
test("each address opens only its own kind of page; a link that doesn't work says the same thing however it doesn't", async () => {
const asStatusOnWall = await call("GET", `/public/wall/${statusToken}`);
assert.equal(asStatusOnWall.status, 404);
const asWallOnStatus = await call("GET", `/public/status/${wallToken}`);
assert.equal(asWallOnStatus.status, 404);
const never = await call("GET", `/public/status/${"z".repeat(32)}`);
assert.equal(never.status, 404);
assert.deepEqual(await asWallOnStatus.json(), await never.json(), "no way to tell a wall's address from one that never existed");
assert.equal((await call("GET", "/public/status/short")).status, 404);
assert.equal((await call("GET", `/public/wall/${wallToken}`)).status, 200, "and the wall still opens its own");
});
test("a link that has ended, or been removed, stops working; its list goes with it", async () => {
await db.update(shareLinks).set({ expiresAt: new Date(Date.now() - 1000).toISOString() }).where(eq(shareLinks.id, statusLinkId));
assert.equal((await call("GET", `/public/status/${statusToken}`)).status, 404, "ended");
await db.update(shareLinks).set({ expiresAt: null }).where(eq(shareLinks.id, statusLinkId));
assert.equal((await call("GET", `/public/status/${statusToken}`)).status, 200);
assert.equal((await call("DELETE", `/share-links/${statusLinkId}`)).status, 204);
assert.equal((await call("GET", `/public/status/${statusToken}`)).status, 404, "removed");
assert.equal((await db.select().from(statusItems).where(eq(statusItems.linkId, statusLinkId))).length, 0, "its things are gone with it");
});
});
+3 -1
View File
@@ -53,6 +53,7 @@ import AppShell from "./layout/AppShell";
import DialogHost from "./components/DialogHost"; import DialogHost from "./components/DialogHost";
import Wall from "./pages/Wall"; import Wall from "./pages/Wall";
import SharedWall from "./pages/SharedWall"; import SharedWall from "./pages/SharedWall";
import SharedStatus from "./pages/SharedStatus";
import MapPage from "./pages/Map"; import MapPage from "./pages/Map";
import { setDateTimeSettings } from "./utils/date"; import { setDateTimeSettings } from "./utils/date";
import { setPageSize } from "./utils/pageSize"; import { setPageSize } from "./utils/pageSize";
@@ -80,7 +81,7 @@ function RequireRole({
export default function App() { export default function App() {
const [user, setUser] = useState<CurrentUser | null | undefined>(undefined); const [user, setUser] = useState<CurrentUser | null | undefined>(undefined);
// A share link's page is for someone who isn't signed in: it asks nothing of the app's own session. // A share link's page is for someone who isn't signed in: it asks nothing of the app's own session.
const shared = useLocation().pathname.startsWith("/share/wall/"); const shared = useLocation().pathname.startsWith("/share/wall/") || useLocation().pathname.startsWith("/share/status/");
useEffect(() => { useEffect(() => {
if (shared) return; if (shared) return;
@@ -103,6 +104,7 @@ export default function App() {
return ( return (
<Routes> <Routes>
<Route path="/share/wall/:token" element={<SharedWall />} /> <Route path="/share/wall/:token" element={<SharedWall />} />
<Route path="/share/status/:token" element={<SharedStatus />} />
</Routes> </Routes>
); );
} }
+52 -2
View File
@@ -14,11 +14,48 @@ export interface CurrentUser {
export type ShareLinkDetail = "summary" | "names"; export type ShareLinkDetail = "summary" | "names";
/** A link that opens the wall display without signing in, as the settings list shows it (never the secret). */ export type ShareLinkKind = "wall" | "status";
export type StatusItemKind = "server" | "integration" | "monitor";
/** One thing on a status page, as the editor sees it. */
export interface StatusPageItem {
id: number;
label: string;
kind: StatusItemKind;
targetId: number;
monitorId: string | null;
/** What it points at (the server's, integration's or monitor's own name). */
targetName: string | null;
}
/** What somebody who opens a status page's address is given: names and states, nothing else. */
export interface PublicStatusItem {
id: number;
label: string;
state: "up" | "down" | "maintenance" | "unknown";
uptime30d: number | null;
}
export interface PublicStatus {
title: string;
message: string | null;
level: "ok" | "issue" | "maintenance" | "unknown";
counts: Record<PublicStatusItem["state"], number>;
items: PublicStatusItem[];
generatedAt: string;
display: { dateFormat: string; timeFormat: string };
}
/** A link that opens the wall display, or a status page, without signing in, as the settings list shows it (never the secret). */
export interface ShareLink { export interface ShareLink {
id: number; id: number;
label: string; label: string;
tokenPrefix: string; tokenPrefix: string;
kind: ShareLinkKind;
/** A status page's own heading and message. */
title: string | null;
message: string | null;
/** How many things a status page shows. */
itemCount: number;
detail: ShareLinkDetail; detail: ShareLinkDetail;
createdBy: string | null; createdBy: string | null;
createdAt: string; createdAt: string;
@@ -1632,10 +1669,23 @@ export const api = {
}, },
shareLinks: { shareLinks: {
list: () => request<{ links: ShareLink[] }>("/api/share-links"), list: () => request<{ links: ShareLink[] }>("/api/share-links"),
create: (data: { label: string; detail: ShareLinkDetail; expiresInDays: number | null }) => create: (data: { label: string; detail?: ShareLinkDetail; kind?: ShareLinkKind; title?: string; message?: string; expiresInDays: number | null }) =>
request<{ link: ShareLink; token: string; path: string }>("/api/share-links", { method: "POST", body: JSON.stringify(data) }), request<{ link: ShareLink; token: string; path: string }>("/api/share-links", { method: "POST", body: JSON.stringify(data) }),
remove: (id: number) => request<void>(`/api/share-links/${id}`, { method: "DELETE" }), remove: (id: number) => request<void>(`/api/share-links/${id}`, { method: "DELETE" }),
}, },
statusPages: {
get: (linkId: number) => request<{ title: string; message: string; items: StatusPageItem[]; maxItems: number }>("/api/share-links/" + linkId + "/status"),
choices: () => request<{ servers: { id: number; name: string }[]; integrations: { id: number; name: string; type: string }[] }>("/api/share-links/status-choices"),
save: (linkId: number, data: { title: string; message: string; items: { label: string; kind: StatusItemKind; targetId: number; monitorId: string | null }[] }) =>
request<{ title: string; message: string; items: StatusPageItem[] }>("/api/share-links/" + linkId + "/status", { method: "PUT", body: JSON.stringify(data) }),
},
publicStatus: {
get: async (token: string): Promise<PublicStatus> => {
const res = await fetch("/api/public/status/" + encodeURIComponent(token), { credentials: "omit", cache: "no-store" });
if (!res.ok) throw Object.assign(new Error("Request failed (" + res.status + ")"), { status: res.status });
return (await res.json()) as PublicStatus;
},
},
// Opened by someone who isn't signed in: no cookies, and the status is kept so a link that has ended can say so. // Opened by someone who isn't signed in: no cookies, and the status is kept so a link that has ended can say so.
publicWall: { publicWall: {
get: async (token: string): Promise<PublicWall> => { get: async (token: string): Promise<PublicWall> => {
+217
View File
@@ -0,0 +1,217 @@
import { useEffect, useState } from "react";
import { api, type IntegrationSummary, type StatusItemKind, type StatusPageItem } from "../api/client";
import { readableError } from "../utils/errors";
import { toast } from "../utils/toast";
import DetailDrawer from "./DetailDrawer";
import { ErrorNotice } from "./Notice";
import { BlockSkeleton } from "./Skeleton";
interface Choice {
key: string;
kind: StatusItemKind;
targetId: number;
monitorId: string | null;
name: string;
group: string;
}
const KIND_WORDS: Record<StatusItemKind, string> = { server: "Server", integration: "Integration", monitor: "Monitor" };
/**
* Choose what a status page shows and what each thing is called. Each is a server, an integration or an Uptime Kuma monitor; the name is
* whatever people at home will recognise ("Movies"), and is the only thing about it the page ever shows.
*/
export default function StatusPageEditor({ linkId, linkLabel, onClose, onSaved }: { linkId: number; linkLabel: string; onClose: () => void; onSaved: () => void }) {
const [loaded, setLoaded] = useState(false);
const [title, setTitle] = useState("");
const [message, setMessage] = useState("");
const [items, setItems] = useState<StatusPageItem[]>([]);
const [maxItems, setMaxItems] = useState(30);
const [choices, setChoices] = useState<Choice[]>([]);
const [kind, setKind] = useState<StatusItemKind>("server");
const [pick, setPick] = useState("");
const [label, setLabel] = useState("");
const [busy, setBusy] = useState(false);
const [error, setError] = useState<string | null>(null);
useEffect(() => {
let alive = true;
(async () => {
try {
const [page, options, all] = await Promise.all([api.statusPages.get(linkId), api.statusPages.choices(), api.integrations.list()]);
const list: Choice[] = [
...options.servers.map((s) => ({ key: `server:${s.id}`, kind: "server" as const, targetId: s.id, monitorId: null, name: s.name, group: "Servers" })),
...options.integrations.filter((i) => i.type !== "uptimekuma").map((i) => ({ key: `integration:${i.id}`, kind: "integration" as const, targetId: i.id, monitorId: null, name: i.name, group: "Integrations" })),
];
// Monitors are Uptime Kuma's own, read from each one that is switched on; one that can't be reached just has none to offer.
const kuma = all.integrations.filter((i: IntegrationSummary) => i.type === "uptimekuma" && i.enabled);
for (const k of kuma) {
try {
const res = await api.integrations.uptimekuma.monitors(k.id);
for (const m of res.monitors) list.push({ key: `monitor:${k.id}:${m.id}`, kind: "monitor", targetId: k.id, monitorId: m.id, name: m.name, group: `Monitors in ${k.name}` });
} catch {
// nothing to offer from this one
}
}
if (!alive) return;
setTitle(page.title);
setMessage(page.message);
setItems(page.items);
setMaxItems(page.maxItems);
setChoices(list);
setLoaded(true);
} catch (err) {
if (alive) setError(readableError(err));
}
})();
return () => {
alive = false;
};
}, [linkId]);
const candidates = choices.filter((c) => c.kind === kind);
const picked = choices.find((c) => c.key === pick);
function add() {
if (!picked || label.trim() === "") return;
setItems((prev) => [...prev, { id: -Date.now(), label: label.trim(), kind: picked.kind, targetId: picked.targetId, monitorId: picked.monitorId, targetName: picked.name }]);
setPick("");
setLabel("");
}
const move = (i: number, by: number) =>
setItems((prev) => {
const next = [...prev];
const j = i + by;
if (j < 0 || j >= next.length) return prev;
[next[i], next[j]] = [next[j], next[i]];
return next;
});
async function save() {
setBusy(true);
setError(null);
try {
await api.statusPages.save(linkId, { title: title.trim(), message: message.trim(), items: items.map((i) => ({ label: i.label.trim(), kind: i.kind, targetId: i.targetId, monitorId: i.monitorId })) });
toast.success("Saved. The page shows this at its next refresh.");
onSaved();
onClose();
} catch (err) {
setError(readableError(err));
} finally {
setBusy(false);
}
}
const groups = [...new Set(candidates.map((c) => c.group))];
return (
<DetailDrawer title="Status page" subtitle={linkLabel} onClose={onClose}>
{!loaded && !error ? (
<BlockSkeleton lines={5} />
) : (
<>
<p className="text-secondary small">Whoever has the address sees only the name you give each thing and whether it is working — nothing else about it.</p>
<div className="mb-3">
<label className="form-label" htmlFor="sp-title">
Heading <span className="text-secondary">(optional)</span>
</label>
<input id="sp-title" className="form-control" maxLength={60} placeholder={linkLabel} value={title} onChange={(e) => setTitle(e.target.value)} />
</div>
<div className="mb-3">
<label className="form-label" htmlFor="sp-message">
Message <span className="text-secondary">(optional)</span>
</label>
<textarea id="sp-message" className="form-control" rows={2} maxLength={300} placeholder="e.g. Movies are being updated tonight, back by 18:00" value={message} onChange={(e) => setMessage(e.target.value)} />
</div>
<div className="form-label">What it shows</div>
{items.length === 0 ? (
<div className="text-secondary mb-3">Nothing yet. Add the things people ask about.</div>
) : (
<ul className="list-group mb-3">
{items.map((it, i) => (
<li className="list-group-item" key={it.id}>
<div className="d-flex gap-2 align-items-center">
<div className="flex-fill">
<input className="form-control form-control-sm mb-1" aria-label={`Name for ${it.targetName ?? "this"}`} maxLength={60} value={it.label} onChange={(e) => setItems((prev) => prev.map((p, j) => (j === i ? { ...p, label: e.target.value } : p)))} />
<div className="text-secondary small">
{KIND_WORDS[it.kind]} · {it.targetName ?? "(removed)"}
</div>
</div>
<div className="btn-list flex-nowrap">
<button type="button" className="btn btn-sm btn-ghost-secondary" aria-label="Move up" disabled={i === 0} onClick={() => move(i, -1)}>
▲
</button>
<button type="button" className="btn btn-sm btn-ghost-secondary" aria-label="Move down" disabled={i === items.length - 1} onClick={() => move(i, 1)}>
▼
</button>
<button type="button" className="btn btn-sm btn-outline-danger" aria-label={`Remove ${it.label}`} onClick={() => setItems((prev) => prev.filter((_, j) => j !== i))}>
Remove
</button>
</div>
</div>
</li>
))}
</ul>
)}
{items.length < maxItems && (
<div className="border rounded p-3 mb-3">
<div className="form-label">Add something</div>
<div className="d-flex gap-2 mb-2">
<select
className="form-select w-auto"
aria-label="What kind of thing"
value={kind}
onChange={(e) => {
setKind(e.target.value as StatusItemKind);
setPick("");
}}
>
<option value="server">A server</option>
<option value="integration">An integration</option>
<option value="monitor">An Uptime Kuma monitor</option>
</select>
<select
className="form-select"
aria-label="Which one"
value={pick}
onChange={(e) => {
setPick(e.target.value);
const c = choices.find((x) => x.key === e.target.value);
if (c && label.trim() === "") setLabel(c.name);
}}
>
<option value="">{candidates.length === 0 ? "None to choose from" : "Choose…"}</option>
{groups.map((g) => (
<optgroup key={g} label={g}>
{candidates
.filter((c) => c.group === g)
.map((c) => (
<option key={c.key} value={c.key}>
{c.name}
</option>
))}
</optgroup>
))}
</select>
</div>
<div className="d-flex gap-2">
<input className="form-control" aria-label="What to call it on the page" maxLength={60} placeholder="What to call it, e.g. Movies" value={label} onChange={(e) => setLabel(e.target.value)} />
<button type="button" className="btn btn-outline-primary" disabled={!picked || label.trim() === ""} onClick={add}>
Add
</button>
</div>
</div>
)}
<ErrorNotice error={error} />
<button type="button" className="btn btn-primary" disabled={busy || items.some((i) => i.label.trim() === "")} onClick={() => void save()}>
{busy ? "Saving…" : "Save"}
</button>
</>
)}
</DetailDrawer>
);
}
+141
View File
@@ -0,0 +1,141 @@
import { useEffect, useState } from "react";
import { useParams } from "react-router-dom";
import { IconAlertTriangle, IconCircleCheck, IconHelpCircle, IconTool } from "@tabler/icons-react";
import { api, type PublicStatus, type PublicStatusItem } from "../api/client";
import { formatDateTime, setDateTimeSettings } from "../utils/date";
const REFRESH_MS = 30_000;
const STATE: Record<PublicStatusItem["state"], { label: string; badge: string }> = {
up: { label: "Working", badge: "bg-green-lt text-green" },
down: { label: "Not working", badge: "bg-red-lt text-red" },
maintenance: { label: "Being worked on", badge: "bg-blue-lt text-blue" },
unknown: { label: "Can't tell right now", badge: "bg-secondary-lt text-secondary" },
};
const BANNER: Record<PublicStatus["level"], { alert: string; icon: JSX.Element }> = {
ok: { alert: "alert-success", icon: <IconCircleCheck size={22} /> },
issue: { alert: "alert-danger", icon: <IconAlertTriangle size={22} /> },
maintenance: { alert: "alert-info", icon: <IconTool size={22} /> },
unknown: { alert: "alert-secondary", icon: <IconHelpCircle size={22} /> },
};
function headline(page: PublicStatus): string {
const { counts } = page;
if (page.items.length === 0) return "Nothing to show yet";
switch (page.level) {
case "issue":
return counts.down === 1 ? "One thing isn't working" : `${counts.down} things aren't working`;
case "maintenance":
return counts.maintenance === 1 ? "One thing is being worked on" : `${counts.maintenance} things are being worked on`;
case "unknown":
return "Can't tell right now";
default:
return counts.unknown > 0 ? "Everything we can see is working" : "Everything is working";
}
}
/**
* A status page behind a share link: is each of the things somebody chose working? For people at home who only want to know whether the movies
* are up. No sign-in, nothing to click. It follows the device's light or dark setting, and looks again every half minute. A link that doesn't
* work (never made, ended, taken back) says so and stops asking.
*/
export default function SharedStatus() {
const { token = "" } = useParams();
const [page, setPage] = useState<PublicStatus | null>(null);
const [state, setState] = useState<"loading" | "ok" | "dead" | "unreachable">("loading");
const [updatedAt, setUpdatedAt] = useState<Date | null>(null);
// Light or dark as the device likes it.
useEffect(() => {
const media = window.matchMedia?.("(prefers-color-scheme: dark)");
const apply = () => document.documentElement.setAttribute("data-bs-theme", media?.matches ? "dark" : "light");
apply();
media?.addEventListener?.("change", apply);
return () => media?.removeEventListener?.("change", apply);
}, []);
useEffect(() => {
let alive = true;
let timer: ReturnType<typeof setInterval> | undefined;
const load = () =>
api.publicStatus
.get(token)
.then((p) => {
if (!alive) return;
setDateTimeSettings({ dateFormat: p.display.dateFormat as "ymd" | "dmy" | "mdy", timeFormat: p.display.timeFormat as "24h" | "12h" });
setPage(p);
setUpdatedAt(new Date());
setState("ok");
})
.catch((err: unknown) => {
if (!alive) return;
const status = (err as { status?: number }).status;
if (status === 404) {
setState("dead");
if (timer) clearInterval(timer);
} else if (status !== 429) setState((s) => (s === "ok" ? "ok" : "unreachable"));
});
void load();
timer = setInterval(load, REFRESH_MS);
return () => {
alive = false;
if (timer) clearInterval(timer);
};
}, [token]);
useEffect(() => {
document.title = page?.title ?? "Status";
}, [page?.title]);
return (
<div className="page-wrapper" style={{ minHeight: "100vh" }}>
<div className="container-tight py-4" style={{ maxWidth: 640, margin: "0 auto", paddingLeft: 16, paddingRight: 16 }}>
{state === "dead" ? (
<div className="card">
<div className="card-body text-center py-5">
<div className="h3 mb-1">This link doesn't work any more</div>
<div className="text-secondary">It may have ended or been taken back. Ask whoever gave it to you for a new one.</div>
</div>
</div>
) : !page ? (
<div className="text-center text-secondary py-5">{state === "unreachable" ? "Can't reach the server right now. Trying again…" : "Loading…"}</div>
) : (
<>
<h1 className="h2 mb-3">{page.title}</h1>
<div className={`alert ${BANNER[page.level].alert} mb-3`} role="status">
<div className="d-flex gap-2 align-items-center">
{BANNER[page.level].icon}
<strong>{headline(page)}</strong>
</div>
</div>
{page.message && (
<div className="card mb-3">
<div className="card-body" style={{ whiteSpace: "pre-wrap" }}>
{page.message}
</div>
</div>
)}
{page.items.length > 0 && (
<div className="card">
<div className="list-group list-group-flush">
{page.items.map((it) => (
<div className="list-group-item d-flex flex-wrap align-items-center gap-2" key={it.id}>
<span className="fw-bold flex-fill">{it.label}</span>
{it.uptime30d !== null && <span className="text-secondary small">{it.uptime30d}% over 30 days</span>}
<span className={`badge ${STATE[it.state].badge}`}>{STATE[it.state].label}</span>
</div>
))}
</div>
</div>
)}
<div className="text-secondary small text-center mt-3">
{updatedAt ? `Checked ${formatDateTime(updatedAt)}` : ""} · looks again every 30 seconds
{state === "unreachable" ? " · can't reach the server right now" : ""}
</div>
</>
)}
</div>
</div>
);
}
+7
View File
@@ -149,6 +149,13 @@ export default function ApiSettings() {
<code>{origin}/metrics</code> answers in Prometheus's text format — whether each server is up, its load, memory, disks and waiting updates, the alert counts, which integrations work, maintenance, and things about to expire — so a <code>{origin}/metrics</code> answers in Prometheus's text format — whether each server is up, its load, memory, disks and waiting updates, the alert counts, which integrations work, maintenance, and things about to expire — so a
Grafana dashboard or Prometheus alert can use it. It is read-only and opens with a token sent as <code>Authorization: Bearer …</code>; a token in the address isn't accepted. It reads what the app already knows, so a scrape every 15 seconds is cheap. Grafana dashboard or Prometheus alert can use it. It is read-only and opens with a token sent as <code>Authorization: Bearer …</code>; a token in the address isn't accepted. It reads what the app already knows, so a scrape every 15 seconds is cheap.
</p> </p>
<p className="text-secondary">
For Grafana there is a ready-made dashboard — what needs attention, servers, disks, backups and the quieter things — that asks only for these series.{" "}
<a href="/api/metrics-tokens/grafana-dashboard.json" download>
Download the dashboard
</a>
, then in Grafana choose Dashboards → New → Import and pick your Prometheus when asked.
</p>
{newSecret && ( {newSecret && (
<div className="border border-success rounded p-3 mb-3"> <div className="border border-success rounded p-3 mb-3">
<div className="fw-bold mb-1">Token for {newSecret.label}</div> <div className="fw-bold mb-1">Token for {newSecret.label}</div>
+62 -14
View File
@@ -1,5 +1,6 @@
import { useEffect, useState } from "react"; import { useEffect, useState } from "react";
import { api, type ShareLink, type ShareLinkDetail } from "../../api/client"; import { api, type ShareLink, type ShareLinkDetail, type ShareLinkKind } from "../../api/client";
import StatusPageEditor from "../../components/StatusPageEditor";
import CopyButton from "../../components/CopyButton"; import CopyButton from "../../components/CopyButton";
import TimeAgo from "../../components/TimeAgo"; import TimeAgo from "../../components/TimeAgo";
import { ErrorNotice } from "../../components/Notice"; import { ErrorNotice } from "../../components/Notice";
@@ -27,6 +28,11 @@ export default function ShareSettings() {
const [error, setError] = useState<string | null>(null); const [error, setError] = useState<string | null>(null);
const [label, setLabel] = useState(""); const [label, setLabel] = useState("");
const [detail, setDetail] = useState<ShareLinkDetail>("summary"); const [detail, setDetail] = useState<ShareLinkDetail>("summary");
// What the link opens: the wall display, or a status page (heading and message are the page's own, and the things on it are chosen after).
const [kind, setKind] = useState<ShareLinkKind>("wall");
const [title, setTitle] = useState("");
const [message, setMessage] = useState("");
const [editing, setEditing] = useState<{ id: number; label: string } | null>(null);
const [days, setDays] = useState<number | null>(null); const [days, setDays] = useState<number | null>(null);
const [busy, setBusy] = useState(false); const [busy, setBusy] = useState(false);
const [created, setCreated] = useState<{ label: string; url: string } | null>(null); const [created, setCreated] = useState<{ label: string; url: string } | null>(null);
@@ -44,10 +50,14 @@ export default function ShareSettings() {
setError(null); setError(null);
setBusy(true); setBusy(true);
try { try {
const res = await api.shareLinks.create({ label: label.trim(), detail, expiresInDays: days }); const res = await api.shareLinks.create(kind === "status" ? { label: label.trim(), kind, title: title.trim() || undefined, message: message.trim() || undefined, expiresInDays: days } : { label: label.trim(), kind, detail, expiresInDays: days });
setCreated({ label: res.link.label, url: `${window.location.origin}${res.path}` }); setCreated({ label: res.link.label, url: window.location.origin + res.path });
setLabel(""); setLabel("");
setTitle("");
setMessage("");
load(); load();
// A status page with nothing on it isn't much use: go straight to choosing what it shows.
if (res.link.kind === "status") setEditing({ id: res.link.id, label: res.link.label });
} catch (err) { } catch (err) {
setError(readableError(err)); setError(readableError(err));
} finally { } finally {
@@ -70,7 +80,7 @@ export default function ShareSettings() {
<> <>
<h3 className="mb-3">Share links</h3> <h3 className="mb-3">Share links</h3>
<p className="text-secondary"> <p className="text-secondary">
A share link opens the wall display — how things are, on one screen — <strong>without signing in</strong>, for a TV in the hall or someone who only wants to know whether things are up. It can only look; it can't change anything. A share link opens a page <strong>without signing in</strong>: the <strong>wall display</strong> — how things are, on one screen, for a TV in the hall — or a <strong>status page</strong> — whether each of the things you choose is working, with names people at home will recognise, for family or housemates who only want to know "is the movie server up?". It can only look; it can't change anything.
</p> </p>
<div className="alert alert-warning"> <div className="alert alert-warning">
Anyone who has the address can open it, so treat it like a password: give it only to people and screens you trust, and remove it when it isn't needed. The address is shown once, when you make it. Anyone who has the address can open it, so treat it like a password: give it only to people and screens you trust, and remove it when it isn't needed. The address is shown once, when you make it.
@@ -110,14 +120,41 @@ export default function ShareSettings() {
<input id="share-label" className="form-control" required maxLength={60} placeholder="e.g. Hall TV" value={label} onChange={(e) => setLabel(e.target.value)} /> <input id="share-label" className="form-control" required maxLength={60} placeholder="e.g. Hall TV" value={label} onChange={(e) => setLabel(e.target.value)} />
</div> </div>
<div className="col-md-4"> <div className="col-md-4">
<label className="form-label" htmlFor="share-detail"> <label className="form-label" htmlFor="share-kind">
What it shows What it opens
</label> </label>
<select id="share-detail" className="form-select" value={detail} onChange={(e) => setDetail(e.target.value as ShareLinkDetail)}> <select id="share-kind" className="form-select" value={kind} onChange={(e) => setKind(e.target.value as ShareLinkKind)}>
<option value="summary">Numbers only — servers online, alerts, maintenance</option> <option value="wall">The wall display — how things are</option>
<option value="names">With names — also what is wrong, and the integrations</option> <option value="status">A status page — is each thing I choose working</option>
</select> </select>
</div> </div>
{kind === "wall" && (
<div className="col-md-4">
<label className="form-label" htmlFor="share-detail">
How much it shows
</label>
<select id="share-detail" className="form-select" value={detail} onChange={(e) => setDetail(e.target.value as ShareLinkDetail)}>
<option value="summary">Numbers only — servers online, alerts, maintenance</option>
<option value="names">With names — also what is wrong, and the integrations</option>
</select>
</div>
)}
{kind === "status" && (
<>
<div className="col-md-6">
<label className="form-label" htmlFor="share-title">
Heading <span className="text-secondary">(optional)</span>
</label>
<input id="share-title" className="form-control" maxLength={60} placeholder="Defaults to the name above" value={title} onChange={(e) => setTitle(e.target.value)} />
</div>
<div className="col-md-6">
<label className="form-label" htmlFor="share-message">
Message <span className="text-secondary">(optional)</span>
</label>
<input id="share-message" className="form-control" maxLength={300} placeholder="e.g. Movies are being updated tonight" value={message} onChange={(e) => setMessage(e.target.value)} />
</div>
</>
)}
<div className="col-md-4"> <div className="col-md-4">
<label className="form-label" htmlFor="share-lasts"> <label className="form-label" htmlFor="share-lasts">
How long it works How long it works
@@ -131,7 +168,9 @@ export default function ShareSettings() {
</select> </select>
</div> </div>
<div className="col-12 text-secondary small"> <div className="col-12 text-secondary small">
“Numbers only” never shows a name. “With names” shows the text of the alerts (which can mention server names, disks and secrets), what is in maintenance, and the names of your integrations — never addresses, tokens or settings. {kind === "wall"
? "“Numbers only” never shows a name. “With names” shows the text of the alerts (which can mention server names, disks and secrets), what is in maintenance, and the names of your integrations — never addresses, tokens or settings."
: "A status page shows only the name you give each thing and whether it is working, being worked on, or can't be told — and, where known, how it has done over 30 days. Never an address, an alert, or what the thing really is. You choose what is on it right after making it."}
</div> </div>
</div> </div>
<div className="card-footer"> <div className="card-footer">
@@ -167,16 +206,23 @@ export default function ShareSettings() {
<td> <td>
{l.label} <span className="text-secondary small">{l.tokenPrefix}…</span> {l.label} <span className="text-secondary small">{l.tokenPrefix}…</span>
</td> </td>
<td>{DETAIL_WORDS[l.detail]}</td> <td>{l.kind === "status" ? "Status page · " + l.itemCount + (l.itemCount === 1 ? " thing" : " things") : "Wall · " + DETAIL_WORDS[l.detail].toLowerCase()}</td>
<td className="text-secondary"> <td className="text-secondary">
{l.createdBy ?? "—"}, <TimeAgo value={l.createdAt} fromDb /> {l.createdBy ?? "—"}, <TimeAgo value={l.createdAt} fromDb />
</td> </td>
<td>{l.expired ? <span className="badge bg-red-lt text-red">Ended</span> : l.expiresAt ? formatDateTime(new Date(l.expiresAt)) : "Until removed"}</td> <td>{l.expired ? <span className="badge bg-red-lt text-red">Ended</span> : l.expiresAt ? formatDateTime(new Date(l.expiresAt)) : "Until removed"}</td>
<td className="text-secondary">{l.lastUsedAt ? <TimeAgo value={l.lastUsedAt} /> : "Never"}</td> <td className="text-secondary">{l.lastUsedAt ? <TimeAgo value={l.lastUsedAt} /> : "Never"}</td>
<td> <td>
<button className="btn btn-sm btn-outline-danger" onClick={() => remove(l)}> <div className="btn-list flex-nowrap">
Remove {l.kind === "status" && (
</button> <button className="btn btn-sm btn-outline-secondary" onClick={() => setEditing({ id: l.id, label: l.label })}>
Choose what it shows…
</button>
)}
<button className="btn btn-sm btn-outline-danger" onClick={() => remove(l)}>
Remove
</button>
</div>
</td> </td>
</tr> </tr>
))} ))}
@@ -198,6 +244,8 @@ export default function ShareSettings() {
</table> </table>
</div> </div>
</div> </div>
{editing && <StatusPageEditor linkId={editing.id} linkLabel={editing.label} onClose={() => setEditing(null)} onSaved={load} />}
</> </>
); );
} }