Files
Homelab-manager/server/src/routes/dbBackups.ts
T
bobbanandClaude Sonnet 5.5 2744a84719 Acknowledge and hand over alerts, incident timelines, and built-in database backups
- Alerts can be acknowledged (note, assignee, duration); acknowledged alerts are left out of what
  needs attention (sidebar, dashboard strip, cards) but stay raised and counted by /metrics
- Incidents: each time an alert is raised and goes away is recorded (alert_acks, alert_incidents,
  incident_notes, migration 0032), with a timeline of acks, maintenance, changes, update runs,
  related alerts and notes; Incidents page and a digest section
- Backups of Homelab Manager's own database: daily checked VACUUM INTO copies, retention, download,
  check, upload, delete, and restore staged and applied at start-up before the database opens
  (pre-restore copy kept); alerts and /metrics for stale or failing backups
- Docs: README, BACKUP, DATABASE, NOTIFICATIONS, ROLES, API; tests

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-18 02:21:08 +02:00

136 lines
6.0 KiB
TypeScript

import express, { Router } from "express";
import { z } from "zod";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { getSettings, updateSettings } from "../services/settingsStore.js";
import {
backupDir,
cancelStagedRestore,
checkSnapshotFile,
createSnapshot,
deleteSnapshot,
dismissLastRestore,
importUploaded,
lastAttempt,
lastRestore,
listSnapshots,
pruneSnapshots,
snapshotPath,
stageRestore,
stagedRestore,
} from "../services/selfBackup.js";
import { nextBackupRun, scheduleSelfBackup } from "../services/selfBackupScheduler.js";
import { asyncHandler } from "../utils/asyncHandler.js";
export const dbBackupsRouter = Router();
// A backup holds everything the app knows — the audit log, every server's address, the hashed agent tokens and all the stored credentials
// (encrypted) — so all of it, looking and doing, is for administrators.
dbBackupsRouter.use(requireAuth, requireRole("admin"));
/** A database file is far bigger than anything else this app is sent, and is only ever read from an administrator. */
const UPLOAD_LIMIT = "1gb";
const settingsSchema = z.object({
enabled: z.boolean(),
time: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "Use a time like 03:30"),
keep: z.number().int().min(1).max(90),
});
const actorName = (req: express.Request) => req.currentUser!.name ?? req.currentUser!.email ?? req.currentUser!.oidcSub;
async function overview() {
const { selfBackup } = await getSettings();
return {
settings: selfBackup,
snapshots: listSnapshots(),
staged: stagedRestore(),
lastRestore: lastRestore(),
lastAttempt: await lastAttempt(),
nextRun: nextBackupRun()?.toISOString() ?? null,
folder: backupDir(),
};
}
dbBackupsRouter.get("/", asyncHandler(async (_req, res) => {
res.json(await overview());
}));
dbBackupsRouter.put("/settings", asyncHandler(async (req, res) => {
const parsed = settingsSchema.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: "invalid_body", message: parsed.error.issues[0]?.message ?? "A time and how many to keep.", details: parsed.error.flatten() });
const before = (await getSettings()).selfBackup;
await updateSettings({ selfBackup: parsed.data });
await scheduleSelfBackup();
pruneSnapshots(parsed.data.keep);
await recordAudit({ actor: req.currentUser!, category: "db_backup", action: "settings", targetType: "settings", detail: { from: before, to: parsed.data } });
res.json(await overview());
}));
// Take one now. It is checked as it is made, and pruned like the scheduled ones.
dbBackupsRouter.post("/", asyncHandler(async (req, res) => {
try {
const { info, check } = await createSnapshot("manual");
pruneSnapshots((await getSettings()).selfBackup.keep);
await recordAudit({ actor: req.currentUser!, category: "db_backup", action: "create", targetType: "db_backup", targetId: info.name, detail: { sizeBytes: info.sizeBytes } });
res.status(201).json({ snapshot: info, check });
} catch (err) {
res.status(500).json({ error: "backup_failed", message: err instanceof Error ? err.message : String(err) });
}
}));
// A backup somebody has (from another machine, from the script in BACKUP.md): kept if it checks out, and can then be restored like any other.
dbBackupsRouter.post("/upload", express.raw({ type: () => true, limit: UPLOAD_LIMIT }), asyncHandler(async (req, res) => {
if (!Buffer.isBuffer(req.body) || req.body.length === 0) return res.status(400).json({ error: "no_file", message: "Choose a backup file to upload." });
try {
const { info, check } = await importUploaded(req.body);
await recordAudit({ actor: req.currentUser!, category: "db_backup", action: "upload", targetType: "db_backup", targetId: info.name, detail: { sizeBytes: info.sizeBytes } });
res.status(201).json({ snapshot: info, check });
} catch (err) {
res.status(400).json({ error: "unusable", message: err instanceof Error ? err.message : String(err) });
}
}));
dbBackupsRouter.post("/restore/cancel", asyncHandler(async (req, res) => {
const had = cancelStagedRestore();
if (had) await recordAudit({ actor: req.currentUser!, category: "db_backup", action: "restore_cancelled" });
res.json({ cancelled: had });
}));
dbBackupsRouter.post("/restore-result/dismiss", asyncHandler(async (_req, res) => {
dismissLastRestore();
res.json({ ok: true });
}));
dbBackupsRouter.post("/:name/check", asyncHandler(async (req, res) => {
const file = snapshotPath(req.params.name);
if (!file) return res.status(404).json({ error: "not_found" });
res.json({ check: await checkSnapshotFile(file) });
}));
dbBackupsRouter.get("/:name/download", asyncHandler(async (req, res) => {
const file = snapshotPath(req.params.name);
if (!file) return res.status(404).json({ error: "not_found" });
await recordAudit({ actor: req.currentUser!, category: "db_backup", action: "download", targetType: "db_backup", targetId: req.params.name });
res.setHeader("Cache-Control", "no-store");
res.download(file, req.params.name);
}));
// Checks the backup and stages it to replace the database the next time the app starts. Nothing changes until then, and the database in
// use is kept (as a "pre-restore" backup) when it does.
dbBackupsRouter.post("/:name/restore", asyncHandler(async (req, res) => {
try {
const check = await stageRestore(req.params.name, actorName(req));
await recordAudit({ actor: req.currentUser!, category: "db_backup", action: "restore_staged", targetType: "db_backup", targetId: req.params.name });
res.json({ staged: stagedRestore(), check });
} catch (err) {
res.status(400).json({ error: "cannot_restore", message: err instanceof Error ? err.message : String(err) });
}
}));
dbBackupsRouter.delete("/:name", asyncHandler(async (req, res) => {
if (!deleteSnapshot(req.params.name)) return res.status(404).json({ error: "not_found" });
await recordAudit({ actor: req.currentUser!, category: "db_backup", action: "delete", targetType: "db_backup", targetId: req.params.name });
res.status(204).end();
}));