/** * The change log: one timeline of what has changed in the homelab and in this app — agents updated, settings changed, maintenance started and * ended, dependencies edited, hardware added, endpoints set up, alerts raised and cleared — each in a sentence, newest first, and filterable * by what kind of thing it was, by server, by time and by a word. It is made from the audit log and the incident record, so it needs nothing * of its own; the Audit Log page remains the raw table behind it. */ import { and, desc, gte, or, lte } from "drizzle-orm"; import { db } from "../db/client.js"; import { alertIncidents, auditLog, endpointChecks, integrations, servers } from "../db/schema.js"; import { auditTimeToIso, describeAudit, type ActivityTone } from "./serverActivity.js"; export const CHANGE_KINDS = ["servers", "maintenance", "alerts", "settings", "integrations", "dependencies", "inventory", "backups", "endpoints", "other"] as const; export type ChangeKind = (typeof CHANGE_KINDS)[number]; export const KIND_LABELS: Record = { servers: "Servers and agents", maintenance: "Maintenance", alerts: "Alerts and incidents", settings: "Settings and access", integrations: "Integrations, DNS and secrets", dependencies: "Dependencies", inventory: "Inventory", backups: "Backups and restore tests", endpoints: "Endpoint checks and heartbeats", other: "Other", }; const KIND_OF_CATEGORY: Record = { server: "servers", task: "servers", update_run: "servers", tag: "servers", maintenance: "maintenance", alert: "alerts", incident: "alerts", alert_ticket: "alerts", settings: "settings", user: "settings", push: "settings", share_link: "settings", metrics_token: "settings", api_token: "settings", todo: "other", note: "servers", webhook: "settings", integration: "integrations", dns: "integrations", secret: "integrations", domain: "integrations", ipam: "integrations", network: "integrations", consistency: "integrations", dependency: "dependencies", inventory: "inventory", runbook: "other", db_backup: "backups", restore_test: "backups", endpoint: "endpoints", heartbeat: "endpoints", patch_plan: "servers", report: "other", }; /** Sign-ins and a person's own data export are not changes to the homelab; the diagnostic log has its own page. */ const LEFT_OUT = new Set(["session", "privacy", "diag_log"]); export interface ChangeEntry { /** Stable, so a row can be keyed on it. */ id: string; /** ISO. */ at: string; kind: ChangeKind; tone: ActivityTone; title: string; detail: string | null; /** A person's name, or "system" for the app's own checks; null when nobody did it. */ actor: string | null; /** What it is about, and where to read more. */ target: { type: string; id: string | null; name: string | null } | null; link: string | null; /** The server it concerns, when it concerns one (so the log can be narrowed to a server). */ serverId: number | null; } const humanize = (s: string) => { const t = s.replace(/[_-]+/g, " "); return t.charAt(0).toUpperCase() + t.slice(1); }; function parseDetail(detail: string | null): Record { if (!detail) return {}; try { const v = JSON.parse(detail); return v && typeof v === "object" && !Array.isArray(v) ? (v as Record) : {}; } catch { return {}; } } const str = (v: unknown) => (typeof v === "string" && v ? v : null); const MAX_SUMMARY = 220; /** "notifications: healthAlerts true → false" for a settings update; nothing for what is only a name. */ function settingsSummary(detail: Record): string | null { const changes = detail.changes; if (!changes || typeof changes !== "object") return null; const parts: string[] = []; for (const [section, fields] of Object.entries(changes as Record>)) { for (const [field, change] of Object.entries(fields ?? {})) { if (change && typeof change === "object" && "to" in (change as object)) { const c = change as { from: unknown; to: unknown }; parts.push(`${section}.${field}: ${JSON.stringify(c.from)} → ${JSON.stringify(c.to)}`); } else parts.push(`${section}.${field} changed`); } } const text = parts.join(" · "); return text.length > MAX_SUMMARY ? `${text.slice(0, MAX_SUMMARY)}…` : text || null; } /** What is left of the detail once the name and what is already in the sentence are taken out. */ function genericSummary(detail: Record, skip: string[] = []): string | null { const parts = Object.entries(detail) .filter(([k, v]) => !["name", "message", ...skip].includes(k) && v !== null && v !== undefined && v !== "" && !(Array.isArray(v) && v.length === 0)) .map(([k, v]) => `${k}: ${typeof v === "object" ? JSON.stringify(v) : String(v)}`); const text = parts.join(" · "); return text.length > MAX_SUMMARY ? `${text.slice(0, MAX_SUMMARY)}…` : text || null; } /** One sentence for an audit entry. Servers, alerts and update runs have their own wording (the same as a server's Activity card); the rest is made here. */ export function describeChange(category: string, action: string, detail: Record): { title: string; tone: ActivityTone; detail: string | null } { const name = str(detail.name); const minutes = typeof detail.minutes === "number" ? detail.minutes : null; const forHow = minutes !== null ? (minutes >= 120 ? `${Math.round(minutes / 60)} h` : `${minutes} min`) : null; switch (`${category}/${action}`) { case "maintenance/start": return { title: `Maintenance started${name ? ` on ${name}` : ""}`, tone: "info", detail: [forHow && `for ${forHow}`, str(detail.reason)].filter(Boolean).join(" · ") || null }; case "maintenance/extend": return { title: `Maintenance extended${name ? ` on ${name}` : ""}`, tone: "info", detail: [forHow && `for ${forHow} from now`, str(detail.reason)].filter(Boolean).join(" · ") || null }; case "maintenance/end": return { title: `Maintenance ended${name ? ` on ${name}` : ""}`, tone: "info", detail: null }; case "maintenance/start_bulk": return { title: "Maintenance started on many at once", tone: "info", detail: genericSummary(detail) }; case "dependency/create": return { title: `${str(detail.from) ?? "Something"} now needs ${str(detail.to) ?? "something"}`, tone: "neutral", detail: null }; case "dependency/delete": return { title: `${str(detail.from) ?? "Something"} no longer needs ${str(detail.to) ?? "something"}`, tone: "neutral", detail: null }; case "inventory/create": return { title: `Hardware added${name ? `: ${name}` : ""}`, tone: "neutral", detail: genericSummary(detail, ["kind"]) }; case "inventory/update": return { title: `Hardware changed${name ? `: ${name}` : ""}`, tone: "neutral", detail: genericSummary(detail) }; case "inventory/delete": return { title: `Hardware removed${name ? `: ${name}` : ""}`, tone: "neutral", detail: null }; case "inventory/refresh_from_agent": return { title: `Hardware details taken from the agent${name ? `: ${name}` : ""}`, tone: "neutral", detail: null }; case "inventory/update_config": return { title: "Price of power changed", tone: "neutral", detail: null }; case "endpoint/create": return { title: `Endpoint check added${name ? `: ${name}` : ""}`, tone: "neutral", detail: [str(detail.kind), str(detail.target)].filter(Boolean).join(" · ") || null }; case "endpoint/update": return { title: `Endpoint check changed${name ? `: ${name}` : ""}`, tone: "neutral", detail: [str(detail.kind), str(detail.target)].filter(Boolean).join(" · ") || null }; case "endpoint/delete": return { title: `Endpoint check removed${name ? `: ${name}` : ""}`, tone: "neutral", detail: null }; case "server/bulk_tag": { const n = typeof detail.changed === "number" ? detail.changed : null; return { title: detail.change === "undo" ? "A tag change on several servers was undone" : `${str(detail.change) === "remove_tag" ? "Tag taken off" : "Tag added to"} ${n ?? "several"} server${n === 1 ? "" : "s"}${str(detail.tag) ? `: ${str(detail.tag)}` : ""}`, tone: "neutral", detail: null }; } case "server/bulk_runs_on": return { title: detail.change === "undo" ? "A change of which server others run on was undone" : `Which server ${typeof detail.changed === "number" ? detail.changed : "several"} run on was changed`, tone: "neutral", detail: null }; case "maintenance/bulk_start": return { title: `Maintenance started on several at once${Array.isArray(detail.servers ?? detail.targets) ? `: ${((detail.servers ?? detail.targets) as unknown[]).slice(0, 4).join(", ")}` : ""}`, tone: "neutral", detail: typeof detail.reason === "string" ? detail.reason : null }; case "maintenance/bulk_undo": return { title: "Maintenance started on several at once was undone", tone: "neutral", detail: null }; case "alert/bulk_ack": return { title: `${typeof detail.changed === "number" ? detail.changed : "Several"} alert${detail.changed === 1 ? "" : "s"} acknowledged at once`, tone: "neutral", detail: typeof detail.note === "string" && detail.note ? detail.note : null }; case "alert/bulk_unack": return { title: `Acknowledgement taken off ${typeof detail.changed === "number" ? detail.changed : "several"} alert${detail.changed === 1 ? "" : "s"}`, tone: "neutral", detail: null }; case "alert/bulk_undo": return { title: "Acknowledging several alerts at once was undone", tone: "neutral", detail: null }; case "inventory/bulk_change": return { title: detail.change === "undo" ? "A change to several pieces of hardware was undone" : `${typeof detail.changed === "number" ? detail.changed : "Several"} piece${detail.changed === 1 ? "" : "s"} of hardware changed at once`, tone: "neutral", detail: genericSummary(detail, ["ids", "changed", "change"]) }; case "alert/flapping_started": return { title: `Alert began flapping${str(detail.message) ? `: ${str(detail.message)}` : ""}`, tone: "bad", detail: typeof detail.raises === "number" ? `raised ${detail.raises} times within an hour; its messages are held back` : null }; case "alert/flapping_ended": return { title: `Alert settled${str(detail.message) ? `: ${str(detail.message)}` : ""}`, tone: detail.active === true ? "bad" : "good", detail: detail.active === true ? "steady for an hour, and still active" : "steady for an hour, and cleared" }; case "report/send_monthly": return { title: `Monthly report sent${str(detail.month) ? ` (${str(detail.month)})` : ""}`, tone: "neutral", detail: null }; case "patch_plan/create": return { title: `Patch plan added${name ? `: ${name}` : ""}`, tone: "neutral", detail: null }; case "patch_plan/update": return { title: `Patch plan changed${name ? `: ${name}` : ""}`, tone: "neutral", detail: null }; case "patch_plan/delete": return { title: `Patch plan removed${name ? `: ${name}` : ""}`, tone: "neutral", detail: null }; case "patch_plan/run": return { title: `Patch plan started${name ? `: ${name}` : ""}`, tone: "neutral", detail: str(detail.trigger) === "schedule" ? "by its schedule" : str(detail.by) ? `by ${str(detail.by)}` : null }; case "patch_plan/finished": return { title: `Patch plan finished${name ? `: ${name}` : ""}`, tone: "good", detail: str(detail.message) }; case "patch_plan/failed": return { title: `Patch plan didn't finish cleanly${name ? `: ${name}` : ""}`, tone: "bad", detail: str(detail.message) }; case "patch_plan/cancelled": return { title: `Patch plan stopped${name ? `: ${name}` : ""}`, tone: "neutral", detail: str(detail.message) }; case "heartbeat/create": return { title: `Heartbeat added${name ? `: ${name}` : ""}`, tone: "neutral", detail: typeof detail.periodMinutes === "number" ? `expected every ${detail.periodMinutes} min` : null }; case "heartbeat/update": return { title: `Heartbeat changed${name ? `: ${name}` : ""}`, tone: "neutral", detail: typeof detail.periodMinutes === "number" ? `expected every ${detail.periodMinutes} min` : null }; case "heartbeat/new_address": return { title: `Heartbeat given a new address${name ? `: ${name}` : ""}`, tone: "neutral", detail: "the old address no longer works" }; case "heartbeat/delete": return { title: `Heartbeat removed${name ? `: ${name}` : ""}`, tone: "neutral", detail: null }; case "restore_test/record": { const result = str(detail.result); const tone: ActivityTone = result === "failed" ? "bad" : result === "not_needed" ? "neutral" : "good"; const said = result === "ok" ? "passed" : result === "partial" ? "partly worked" : result === "failed" ? "failed" : "marked as not needed"; return { title: `Restore test of ${name ?? "something"} ${said}`, tone, detail: [str(detail.testedAt), str(detail.note)].filter(Boolean).join(" · ") || null }; } case "restore_test/delete": return { title: `A restore test of ${name ?? "something"} was removed`, tone: "neutral", detail: str(detail.testedAt) }; case "settings/update": { const sections = Array.isArray(detail.sections) ? (detail.sections as string[]).join(", ") : null; return { title: `Settings changed${sections ? `: ${sections}` : ""}`, tone: "neutral", detail: settingsSummary(detail) }; } case "push/subscribe": return { title: `A browser was added for push notifications${str(detail.label) ? `: ${str(detail.label)}` : ""}`, tone: "neutral", detail: null }; case "push/unsubscribe": return { title: `A browser was removed from push notifications${str(detail.label) ? `: ${str(detail.label)}` : ""}`, tone: "neutral", detail: null }; case "alert/escalate": return { title: "An alert nobody had acknowledged was escalated", tone: "bad", detail: [str(detail.message), typeof detail.afterMinutes === "number" ? `step after ${detail.afterMinutes} min` : null].filter(Boolean).join(" · ") || null }; } if (category === "server" || category === "alert" || category === "update_run") { const d = describeAudit(category, action, detail); return { title: d.title, tone: d.tone, detail: d.detail }; } return { title: `${humanize(category)}: ${action.replace(/_/g, " ")}${name ? ` — ${name}` : ""}`, tone: "neutral", detail: genericSummary(detail) }; } export interface ChangeQuery { /** How far back, in days (default 7). */ days?: number; kind?: ChangeKind; serverId?: number; /** A word or two that must all appear somewhere in the entry. */ q?: string; /** Only entries older than this (ISO), for the next page. */ before?: string; limit?: number; now?: Date; } const sqlTime = (d: Date) => d.toISOString().slice(0, 19).replace("T", " "); function serverIdOf(targetType: string | null, targetId: string | null, detail: Record): number | null { if (targetType === "server" && targetId && /^\d+$/.test(targetId)) return Number(targetId); // Some entries about something else name the servers they touch by key ("server:3"). for (const k of ["fromKey", "toKey", "key"]) { const m = /^server:(\d+)$/.exec(typeof detail[k] === "string" ? (detail[k] as string) : ""); if (m) return Number(m[1]); } return null; } const touchesServer = (e: ChangeEntry, id: number, detail: Record) => e.serverId === id || ["fromKey", "toKey"].some((k) => detail[k] === `server:${id}`); /** The log, newest first, narrowed as asked. `more` says whether older entries are left beyond the ones returned. */ export async function getChangeLog(query: ChangeQuery = {}): Promise<{ entries: ChangeEntry[]; more: boolean }> { const now = query.now ?? new Date(); const days = Math.min(Math.max(query.days ?? 7, 1), 400); const limit = Math.min(Math.max(query.limit ?? 200, 1), 500); const since = new Date(now.getTime() - days * 86_400_000); const until = query.before ? new Date(query.before) : null; const [serverRows, integrationRows, endpointRows] = await Promise.all([ db.select({ id: servers.id, name: servers.name }).from(servers), db.select({ id: integrations.id, name: integrations.name }).from(integrations), db.select({ id: endpointChecks.id, name: endpointChecks.name }).from(endpointChecks), ]); const serverName = new Map(serverRows.map((s) => [s.id, s.name])); const integrationName = new Map(integrationRows.map((i) => [i.id, i.name])); const endpointName = new Map(endpointRows.map((e) => [e.id, e.name])); const entries: { entry: ChangeEntry; detail: Record }[] = []; const audits = await db .select() .from(auditLog) .where(until ? and(gte(auditLog.createdAt, sqlTime(since)), lte(auditLog.createdAt, sqlTime(until))) : gte(auditLog.createdAt, sqlTime(since))) .orderBy(desc(auditLog.createdAt), desc(auditLog.id)) .limit(5000); for (const a of audits) { if (LEFT_OUT.has(a.category)) continue; const detail = parseDetail(a.detail); const d = describeChange(a.category, a.action, detail); const serverId = serverIdOf(a.targetType, a.targetId, detail); const idNum = a.targetId && /^\d+$/.test(a.targetId) ? Number(a.targetId) : null; let targetName = str(detail.name); let link: string | null = null; if (a.targetType === "server" && idNum !== null) { targetName = serverName.get(idNum) ?? targetName; link = serverName.has(idNum) ? `/servers/${idNum}` : null; } else if (a.targetType === "integration" && idNum !== null) { targetName = integrationName.get(idNum) ?? targetName; link = "/integrations"; } else if (a.targetType === "endpoint" && idNum !== null) { targetName = endpointName.get(idNum) ?? targetName; link = "/endpoints"; } else if (a.targetType === "heartbeat") link = "/heartbeats"; else if (a.targetType === "patch_plan") link = "/updates?view=plans"; else if (a.targetType === "asset" && idNum !== null) link = `/inventory?asset=${idNum}`; else if (a.targetType === "restore_test") link = "/backups"; else if (a.targetType === "dependency") link = "/map?view=dependencies"; else if (a.targetType === "settings") link = "/settings/notifications"; entries.push({ detail, entry: { id: `audit-${a.id}`, at: auditTimeToIso(a.createdAt), kind: KIND_OF_CATEGORY[a.category] ?? "other", tone: d.tone, title: d.title, detail: d.detail, actor: a.actorLabel, target: a.targetType ? { type: a.targetType, id: a.targetId, name: targetName } : null, link, serverId, }, }); } // Alerts raised and cleared, from the incident record. const incidents = await db .select() .from(alertIncidents) .where(or(gte(alertIncidents.openedAt, since.toISOString()), gte(alertIncidents.resolvedAt, since.toISOString()))) .orderBy(desc(alertIncidents.openedAt)) .limit(1000); for (const i of incidents) { const serverId = i.targetType === "server" ? i.targetId : null; const base = { kind: "alerts" as const, actor: null, target: i.targetType ? { type: i.targetType, id: i.targetId === null ? null : String(i.targetId), name: i.targetName } : null, link: `/alerts/incidents/${i.id}`, serverId }; if (i.openedAt >= since.toISOString() && (!until || i.openedAt <= until.toISOString())) { entries.push({ detail: {}, entry: { ...base, id: `incident-open-${i.id}`, at: i.openedAt, tone: i.peakSeverity === "critical" ? "bad" : "info", title: `Alert raised: ${i.message}`, detail: i.causedBy ? `explained by ${i.causedBy}` : null } }); } if (i.resolvedAt && i.resolvedAt >= since.toISOString() && (!until || i.resolvedAt <= until.toISOString())) { entries.push({ detail: {}, entry: { ...base, id: `incident-close-${i.id}`, at: i.resolvedAt, tone: "good", title: `Alert cleared: ${i.message}`, detail: null } }); } } const terms = (query.q ?? "").toLowerCase().split(/\s+/).filter(Boolean); const kept = entries .filter(({ entry, detail }) => { if (query.kind && entry.kind !== query.kind) return false; if (query.serverId !== undefined && !touchesServer(entry, query.serverId, detail)) return false; if (until && entry.at >= until.toISOString()) return false; // strictly older than the cursor if (terms.length > 0) { const hay = `${entry.title} ${entry.detail ?? ""} ${entry.actor ?? ""} ${entry.target?.name ?? ""} ${KIND_LABELS[entry.kind]}`.toLowerCase(); if (!terms.every((t) => hay.includes(t))) return false; } return true; }) .map((e) => e.entry) .sort((a, b) => b.at.localeCompare(a.at) || b.id.localeCompare(a.id)); return { entries: kept.slice(0, limit), more: kept.length > limit }; }