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

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

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

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

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

No files matched your search

+46
View File
@@ -0,0 +1,46 @@
import { Router } from "express";
import { z } from "zod";
import { requireAuth } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { createApiToken, EXPIRY_CHOICES, listApiTokens, MAX_TOKENS_PER_PERSON, publicApiToken, removeApiToken, TokenLimitError } from "../services/apiTokens.js";
import { asyncHandler } from "../utils/asyncHandler.js";
/** A person's own API tokens: anyone signed in makes, sees and removes theirs — never anybody else's. */
export const apiTokensRouter = Router();
apiTokensRouter.use(requireAuth);
const createSchema = z.object({
label: z.string().trim().min(1).max(60),
// Days until it stops working; null (or left out) for until it is removed.
expiresInDays: z.union([z.literal(30), z.literal(90), z.literal(365)]).nullable().optional(),
});
apiTokensRouter.get("/", asyncHandler(async (req, res) => {
const rows = await listApiTokens(req.currentUser!.id);
res.json({ tokens: rows.map((r) => publicApiToken(r)), max: MAX_TOKENS_PER_PERSON, expiryChoices: EXPIRY_CHOICES });
}));
// The secret is in this answer and nowhere else, ever.
apiTokensRouter.post("/", asyncHandler(async (req, res) => {
const parsed = createSchema.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: "invalid_body", message: "Give the token a name, like Home Assistant, and choose 30, 90 or 365 days or no end." });
const actor = req.currentUser!;
try {
const { row, token } = await createApiToken({ userId: actor.id, label: parsed.data.label, expiresInDays: parsed.data.expiresInDays ?? null });
await recordAudit({ actor, category: "api_token", action: "create", targetType: "api_token", targetId: row.id, detail: { label: row.label, expiresAt: row.expiresAt } });
res.status(201).json({ token: publicApiToken(row), secret: token });
} catch (err) {
if (err instanceof TokenLimitError) return res.status(400).json({ error: "too_many", message: err.message });
throw err;
}
}));
apiTokensRouter.delete("/:id", asyncHandler(async (req, res) => {
const id = /^\d+$/.test(req.params.id) ? Number(req.params.id) : NaN;
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const actor = req.currentUser!;
const removed = await removeApiToken(actor.id, id);
if (!removed) return res.status(404).json({ error: "not_found" });
await recordAudit({ actor, category: "api_token", action: "delete", targetType: "api_token", targetId: id, detail: { label: removed.label } });
res.status(204).end();
}));
+12 -1
View File
@@ -6,7 +6,7 @@ import { endpointChecks, servers } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { invalidateAlertsCache } from "../services/alerts.js";
import { CHECK_KINDS, isStatusSpec, loadStats, runCheck } from "../services/endpointChecks.js";
import { CHECK_KINDS, getEndpointHistory, isStatusSpec, loadStats, runCheck } from "../services/endpointChecks.js";
import { loadDismissed, loadSuggestions, saveDismissed } from "../services/endpointSuggestions.js";
import { asyncHandler } from "../utils/asyncHandler.js";
@@ -63,6 +63,17 @@ endpointsRouter.get("/", asyncHandler(async (_req, res) => {
});
}));
// How one check has done over a day, a week, a month, three months or a year: availability and answer times, for the chart on its page.
endpointsRouter.get("/:id/history", asyncHandler(async (req, res) => {
const id = /^\d+$/.test(req.params.id) ? Number(req.params.id) : NaN;
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const [check] = await db.select({ id: endpointChecks.id, name: endpointChecks.name }).from(endpointChecks).where(eq(endpointChecks.id, id)).limit(1);
if (!check) return res.status(404).json({ error: "not_found" });
const requested = Number(req.query.days);
const days = Number.isFinite(requested) ? Math.min(365, Math.max(1, Math.round(requested))) : 7;
res.json({ check, ...(await getEndpointHistory(id, days)) });
}));
function valuesOf(d: z.infer<typeof checkSchema>) {
return {
name: d.name,
+4 -63
View File
@@ -2,12 +2,11 @@ import { Router } from "express";
import { eq } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { integrations, networkDevices, networkSegments, networkServerLinks, servers } from "../db/schema.js";
import { integrations } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { invalidateAlertsCache } from "../services/alerts.js";
import { dependentsOf, loadGraph, needsOfNode, nodeKey } from "../services/dependencies.js";
import { activeSubjects } from "../services/maintenance.js";
import { syncAllUnifi, syncStatuses, syncUnifiIntegration } from "../services/unifiSync.js";
import { buildNetworkOverview } from "../services/networkOverview.js";
import { syncAllUnifi, syncUnifiIntegration } from "../services/unifiSync.js";
import { asyncHandler } from "../utils/asyncHandler.js";
export const networkRouter = Router();
@@ -19,65 +18,7 @@ networkRouter.use(requireAuth);
* names. Everyone signed in can see it (it is the same picture the dependency map and the alerts draw on); only starting a fresh read needs more.
*/
networkRouter.get("/", asyncHandler(async (_req, res) => {
const [intRows, devices, segments, statuses, graph, silenced, linkRows, serverRows] = await Promise.all([
db.select({ id: integrations.id, name: integrations.name, enabled: integrations.enabled }).from(integrations).where(eq(integrations.type, "unifi")),
db.select().from(networkDevices),
db.select().from(networkSegments),
syncStatuses(),
loadGraph(),
activeSubjects(),
db.select().from(networkServerLinks),
db.select({ id: servers.id, name: servers.name }).from(servers),
]);
const serverName = new Map(serverRows.map((s) => [s.id, s.name]));
const intName = new Map(intRows.map((i) => [i.id, i.name]));
const byExternal = new Map(devices.map((d) => [`${d.integrationId}:${d.externalId}`, d]));
// The servers plugged into each device, by what the controller says is connected (see unifiSync.matchClientsToServers).
const plugged = new Map<number, { serverId: number; serverName: string; port: number | null; wired: boolean }[]>();
const serverLinks: { serverId: number; serverName: string; deviceId: number; deviceName: string; port: number | null; wired: boolean }[] = [];
for (const l of linkRows) {
const device = byExternal.get(`${l.integrationId}:${l.deviceExternalId}`);
const name = serverName.get(l.serverId);
if (!device || !name) continue;
plugged.set(device.id, [...(plugged.get(device.id) ?? []), { serverId: l.serverId, serverName: name, port: l.port, wired: l.wired }]);
serverLinks.push({ serverId: l.serverId, serverName: name, deviceId: device.id, deviceName: device.name, port: l.port, wired: l.wired });
}
res.json({
serverLinks,
integrations: intRows.map((i) => ({ id: i.id, name: i.name, enabled: i.enabled, status: statuses[i.id] ?? null })),
devices: devices
.map((d) => {
const key = nodeKey("device", d.id);
const uplink = d.uplinkExternalId ? byExternal.get(`${d.integrationId}:${d.uplinkExternalId}`) : undefined;
return {
id: d.id,
integrationId: d.integrationId,
integrationName: intName.get(d.integrationId) ?? "UniFi",
siteName: d.siteName,
name: d.name,
model: d.model,
kind: d.kind,
ip: d.ip,
mac: d.mac,
state: d.state,
uptimeSeconds: d.uptimeSeconds,
firmware: d.firmware,
firmwareUpdatable: d.firmwareUpdatable,
uplink: uplink ? { id: uplink.id, name: uplink.name } : null,
offlineSince: d.offlineSince,
lastOnlineAt: d.lastOnlineAt,
updatedAt: d.updatedAt,
// How many things depend on it (directly or through others), and how many it needs: what the dependency map says about it.
dependents: dependentsOf(graph.edges, key).length,
needs: needsOfNode(graph.edges, key).length,
inMaintenance: silenced.has(key),
servers: (plugged.get(d.id) ?? []).sort((a, b) => a.serverName.localeCompare(b.serverName)),
};
})
.sort((a, b) => a.name.localeCompare(b.name)),
networks: segments.filter((s) => s.kind === "network").map(({ kind: _k, ...s }) => ({ ...s, integrationName: intName.get(s.integrationId) ?? "UniFi" })).sort((a, b) => (a.vlanId ?? 0) - (b.vlanId ?? 0) || a.name.localeCompare(b.name)),
ssids: segments.filter((s) => s.kind === "ssid").map(({ kind: _k, ...s }) => ({ ...s, integrationName: intName.get(s.integrationId) ?? "UniFi" })).sort((a, b) => a.name.localeCompare(b.name)),
});
res.json(await buildNetworkOverview());
}));
const syncSchema = z.object({ integrationId: z.number().int().positive().optional() });
+165
View File
@@ -0,0 +1,165 @@
import { Router, type NextFunction, type Request, type Response } from "express";
import { eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { endpointChecks, servers } from "../db/schema.js";
import { resolveApiToken, type ApiTokenRow, type ApiTokenUser } from "../services/apiTokens.js";
import { getEndpointHistory } from "../services/endpointChecks.js";
import { getIncident, listIncidents } from "../services/incidents.js";
import { buildNetworkOverview } from "../services/networkOverview.js";
import { alertsV1, endpointsV1, inventoryV1, maintenanceV1, oneServerV1, serversV1 } from "../services/publicApi.js";
import { getServerMetrics, MAX_RANGE_DAYS } from "../services/serverMetrics.js";
import { asyncHandler } from "../utils/asyncHandler.js";
import { rateLimit } from "../utils/rateLimit.js";
/**
* The read API: JSON about servers, alerts, incidents, inventory, network equipment, endpoint checks and maintenance, for scripts and things like Home Assistant.
* A personal token in the Authorization header (never the address, which ends up in logs); GET only; and nothing here writes anything.
*/
export const publicApiRouter = Router();
declare module "express-serve-static-core" {
interface Request {
apiToken?: { token: ApiTokenRow; user: ApiTokenUser };
}
}
const limiter = rateLimit({ windowMs: 60_000, max: 300, message: "Too many requests." });
publicApiRouter.use(limiter);
publicApiRouter.use((req: Request, res: Response, next: NextFunction) => {
res.setHeader("Cache-Control", "no-store");
if (req.method !== "GET" && req.method !== "HEAD") {
res.setHeader("Allow", "GET, HEAD");
return res.status(405).json({ error: "read_only", message: "This API only reads. It has no way to change anything." });
}
next();
});
publicApiRouter.use(
asyncHandler(async (req, res, next) => {
const match = /^Bearer\s+(\S+)$/i.exec(req.get("authorization") ?? "");
const found = match ? await resolveApiToken(match[1]) : null;
if (!found) {
// The same answer for no token, a wrong one, an expired one and a removed one.
res.setHeader("WWW-Authenticate", 'Bearer realm="homelab-manager"');
return res.status(401).json({ error: "unauthorized", message: "A token is needed: send it as 'Authorization: Bearer <token>'. Make one from the user menu → API tokens." });
}
req.apiToken = found;
next();
}),
);
const idOf = (v: string) => (/^\d+$/.test(v) ? Number(v) : NaN);
const daysOf = (v: unknown, fallback: number) => {
const n = Number(v);
return Number.isFinite(n) ? Math.min(MAX_RANGE_DAYS, Math.max(1, Math.round(n))) : fallback;
};
publicApiRouter.get("/", (_req, res) => {
res.json({
name: "Homelab Manager read API",
version: 1,
endpoints: [
"GET /api/v1/me",
"GET /api/v1/servers?tag=&status=",
"GET /api/v1/servers/:id",
"GET /api/v1/servers/:id/metrics?days=",
"GET /api/v1/alerts?severity=&category=&acknowledged=&silenced=",
"GET /api/v1/incidents?status=&limit=",
"GET /api/v1/incidents/:id",
"GET /api/v1/inventory",
"GET /api/v1/network",
"GET /api/v1/endpoints",
"GET /api/v1/endpoints/:id/history?days=",
"GET /api/v1/maintenance",
],
});
});
publicApiRouter.get("/me", (req, res) => {
const { token, user } = req.apiToken!;
res.json({ user: { id: user.id, name: user.name, email: user.email, role: user.role }, token: { id: token.id, label: token.label, expiresAt: token.expiresAt } });
});
publicApiRouter.get("/servers", asyncHandler(async (req, res) => {
let list = await serversV1();
if (typeof req.query.tag === "string" && req.query.tag) {
const tag = req.query.tag.toLowerCase();
list = list.filter((s) => s.tags.includes(tag));
}
if (req.query.status === "online" || req.query.status === "offline" || req.query.status === "unknown") list = list.filter((s) => s.status === req.query.status);
res.json({ servers: list });
}));
publicApiRouter.get("/servers/:id", asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const server = await oneServerV1(id);
if (!server) return res.status(404).json({ error: "not_found" });
res.json({ server });
}));
publicApiRouter.get("/servers/:id/metrics", asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const [row] = await db.select({ id: servers.id }).from(servers).where(eq(servers.id, id)).limit(1);
if (!row) return res.status(404).json({ error: "not_found" });
const days = daysOf(req.query.days, 7);
res.json({ days, series: await getServerMetrics(id, days) });
}));
publicApiRouter.get("/alerts", asyncHandler(async (req, res) => {
const report = await alertsV1();
let alerts = report.alerts;
const q = req.query;
if (typeof q.severity === "string") alerts = alerts.filter((a) => a.severity === q.severity);
if (typeof q.category === "string") alerts = alerts.filter((a) => a.category === q.category);
if (q.acknowledged === "true" || q.acknowledged === "false") alerts = alerts.filter((a) => (a.acknowledgement !== null) === (q.acknowledged === "true"));
if (q.silenced === "true" || q.silenced === "false") alerts = alerts.filter((a) => a.silenced === (q.silenced === "true"));
res.json({ ...report, alerts });
}));
publicApiRouter.get("/incidents", asyncHandler(async (req, res) => {
const limit = Math.min(500, Math.max(1, Math.round(Number(req.query.limit)) || 100));
let list = await listIncidents({ limit });
if (req.query.status === "open") list = list.filter((i) => i.open);
else if (req.query.status === "resolved") list = list.filter((i) => !i.open);
res.json({ incidents: list });
}));
publicApiRouter.get("/incidents/:id", asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const detail = await getIncident(id);
if (!detail) return res.status(404).json({ error: "not_found" });
res.json(detail);
}));
publicApiRouter.get("/inventory", asyncHandler(async (_req, res) => {
res.json({ assets: await inventoryV1() });
}));
publicApiRouter.get("/network", asyncHandler(async (_req, res) => {
const overview = await buildNetworkOverview();
res.json({ devices: overview.devices, networks: overview.networks, ssids: overview.ssids, serverLinks: overview.serverLinks });
}));
publicApiRouter.get("/endpoints", asyncHandler(async (_req, res) => {
res.json({ endpoints: await endpointsV1() });
}));
publicApiRouter.get("/endpoints/:id/history", asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const [check] = await db.select({ id: endpointChecks.id, name: endpointChecks.name }).from(endpointChecks).where(eq(endpointChecks.id, id)).limit(1);
if (!check) return res.status(404).json({ error: "not_found" });
res.json({ check, ...(await getEndpointHistory(id, daysOf(req.query.days, 7))) });
}));
publicApiRouter.get("/maintenance", asyncHandler(async (_req, res) => {
res.json(await maintenanceV1());
}));
publicApiRouter.use((_req, res) => {
res.status(404).json({ error: "not_found", message: "No such address. GET /api/v1 lists them." });
});
+2 -2
View File
@@ -12,7 +12,7 @@ import { markIgnoredServices, parseHostHealth } from "../services/hostHealth.js"
import { describeDiagnostics, parseDiagnostics } from "../services/agentDiagnostics.js";
import { checkThresholds, parseThresholds } from "../services/serverThresholds.js";
import { latestAgentVersions } from "../services/agentVersions.js";
import { getServerMetrics, RETENTION_DAYS } from "../services/serverMetrics.js";
import { getServerMetrics, MAX_RANGE_DAYS } from "../services/serverMetrics.js";
import { getServerActivity } from "../services/serverActivity.js";
import { asyncHandler } from "../utils/asyncHandler.js";
import { ID_PATTERNS } from "../utils/pathSegment.js";
@@ -272,7 +272,7 @@ serversRouter.get("/:id/metrics", asyncHandler(async (req, res) => {
const [server] = await db.select({ id: servers.id }).from(servers).where(eq(servers.id, id)).limit(1);
if (!server) return res.status(404).json({ error: "not_found" });
const requested = Number(req.query.days);
const days = Number.isFinite(requested) ? Math.min(RETENTION_DAYS, Math.max(1, Math.round(requested))) : 7;
const days = Number.isFinite(requested) ? Math.min(MAX_RANGE_DAYS, Math.max(1, Math.round(requested))) : 7;
res.json({ days, series: await getServerMetrics(id, days) });
}));
+5 -2
View File
@@ -6,6 +6,9 @@ import { getUptime } from "../services/uptimeHistory.js";
export const uptimeRouter = Router();
// Anyone signed in who can see the server and integration lists can see how those have been doing.
uptimeRouter.get("/", requireAuth, asyncHandler(async (_req, res) => {
res.json(await getUptime());
// `?days=` is 30 by default and at most a year (as far back as the audit log it is worked out from goes).
uptimeRouter.get("/", requireAuth, asyncHandler(async (req, res) => {
const requested = Number(req.query.days);
const days = Number.isFinite(requested) ? Math.min(365, Math.max(1, Math.round(requested))) : undefined;
res.json(await getUptime(new Date(), days));
}));