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:
1 parent
5e26e77340
commit
68b41b5586
47 files changed
+12360
-247
No files matched your search
@@ -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();
|
||||
}));
|
||||
@@ -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,
|
||||
|
||||
@@ -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() });
|
||||
|
||||
@@ -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." });
|
||||
});
|
||||
@@ -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) });
|
||||
}));
|
||||
|
||||
|
||||
@@ -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));
|
||||
}));
|
||||
Reference in new issue
Block a user