Add Proxmox snapshots: list, take, roll back, delete

A guest's drawer on the Proxmox page now has a Snapshots section. Everyone
signed in sees them, operators take them, administrators roll back and delete
(each behind a confirmation). Proxmox does each as a task, followed for up to
20 seconds. Audit log and change log entries for all three. An http:// Proxmox
address is now allowed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-11-10 23:25:47 +01:00
1 parent 12e9fee7af
commit 97df28c6dc
11 files changed
+733 -11

No files matched your search

+110 -9
View File
@@ -19,8 +19,12 @@
*
* Proxmox commonly runs with a self-signed certificate in homelab setups, so
* (like the cPanel DNS adapter) this uses node:https directly rather than
* fetch, to support an "insecure" opt-out of certificate verification.
* fetch, to support an "insecure" opt-out of certificate verification (an address that says http:// is spoken to over plain HTTP, as for a proxy in front of it).
*
* Snapshots: GET/POST /nodes/{node}/{qemu,lxc}/{vmid}/snapshot, POST …/snapshot/{name}/rollback and DELETE …/snapshot/{name} (VM.Audit to list, VM.Snapshot to take or delete, VM.Snapshot.Rollback
* to roll back). Each of the last three answers with a task id (UPID), which is followed with GET /nodes/{node}/tasks/{upid}/status until it has stopped.
*/
import * as http from "node:http";
import * as https from "node:https";
import { withDiagLogging } from "../../services/diagLog.js";
import { ID_PATTERNS, InvalidIdentifierError, numericSegment, pathSegment } from "../../utils/pathSegment.js";
@@ -113,6 +117,28 @@ export interface ProxmoxBackupJob {
exclude: string | null;
}
/** One snapshot of a guest, as Proxmox lists it (its "current" line, which is the guest as it is now, is not one). */
export interface ProxmoxSnapshot {
name: string;
description: string;
/** ISO; null when Proxmox did not say. */
takenAt: string | null;
/** A VM's snapshot that includes its memory, so a rollback brings it back running. */
withRam: boolean;
/** The snapshot this one was taken after; null for the first. */
parent: string | null;
}
/** How a task ended: whether it has stopped, and if so whether it worked and what Proxmox said. */
export interface ProxmoxTaskResult {
/** True once the task has stopped (it may still be running when the wait ran out). */
done: boolean;
ok: boolean | null;
/** Proxmox's own word for how it ended ("OK", or the error). */
message: string | null;
upid: string;
}
export interface ProxmoxBackupTask {
node: string;
upid: string;
@@ -164,6 +190,12 @@ export interface ProxmoxAdapter {
restartGuest(node: string, type: ProxmoxGuestType, vmid: number): Promise<void>;
/** Graceful shutdown (ACPI power event for a VM, SIGTERM-then-wait for a container) — unlike stopGuest, this asks the guest OS to shut itself down. */
shutdownGuest(node: string, type: ProxmoxGuestType, vmid: number): Promise<void>;
listSnapshots(node: string, type: ProxmoxGuestType, vmid: number): Promise<ProxmoxSnapshot[]>;
/** Takes a snapshot; answers with the task that makes it (followed for a while, so it says how it went when it was quick). */
createSnapshot(node: string, type: ProxmoxGuestType, vmid: number, options: { name: string; description?: string; includeRam?: boolean }, waitMs?: number): Promise<ProxmoxTaskResult>;
/** Rolls a guest back to a snapshot: everything since it was taken is lost. */
rollbackSnapshot(node: string, type: ProxmoxGuestType, vmid: number, name: string, waitMs?: number): Promise<ProxmoxTaskResult>;
deleteSnapshot(node: string, type: ProxmoxGuestType, vmid: number, name: string, waitMs?: number): Promise<ProxmoxTaskResult>;
listBackupJobs(): Promise<ProxmoxBackupJob[]>;
/** Most recent vzdump task runs across every online node, newest first. */
listRecentBackupTasks(limitPerNode?: number): Promise<ProxmoxBackupTask[]>;
@@ -196,17 +228,23 @@ interface RawResponse {
text: () => string;
}
function request(url: string, insecure: boolean, options: { method?: string; headers?: Record<string, string> } = {}): Promise<RawResponse> {
function request(url: string, insecure: boolean, options: { method?: string; headers?: Record<string, string>; body?: string } = {}): Promise<RawResponse> {
return new Promise((resolve, reject) => {
const parsed = new URL(url);
const req = https.request(
const plain = parsed.protocol === "http:";
const headers: Record<string, string | number> = { ...(options.headers || {}) };
if (options.body !== undefined) {
headers["Content-Type"] = "application/x-www-form-urlencoded";
headers["Content-Length"] = Buffer.byteLength(options.body);
}
const req = (plain ? http : https).request(
{
hostname: parsed.hostname,
port: parsed.port || 8006,
port: parsed.port || (plain ? 80 : 8006),
path: parsed.pathname + parsed.search,
method: options.method || "GET",
headers: options.headers || {},
rejectUnauthorized: !insecure,
headers,
...(plain ? {} : { rejectUnauthorized: !insecure }),
},
(res) => {
let body = "";
@@ -218,7 +256,7 @@ function request(url: string, insecure: boolean, options: { method?: string; hea
},
);
req.on("error", reject);
req.end();
req.end(options.body);
});
}
@@ -244,8 +282,9 @@ export function createProxmoxAdapter(config: ProxmoxConfig): ProxmoxAdapter {
};
}
async function api(method: string, path: string): Promise<any> {
const res = await request(`${base()}/api2/json${path}`, insecure, { method, headers: headers() });
async function api(method: string, path: string, params?: Record<string, string | number>): Promise<any> {
const body = params && Object.keys(params).length > 0 ? new URLSearchParams(Object.entries(params).map(([k, v]) => [k, String(v)])).toString() : undefined;
const res = await request(`${base()}/api2/json${path}`, insecure, { method, headers: headers(), body });
let data: any = null;
try {
data = res.text() ? JSON.parse(res.text()) : null;
@@ -537,6 +576,64 @@ export function createProxmoxAdapter(config: ProxmoxConfig): ProxmoxAdapter {
const restartGuest = (node: string, type: ProxmoxGuestType, vmid: number) => statusAction(node, type, vmid, "reboot");
const shutdownGuest = (node: string, type: ProxmoxGuestType, vmid: number) => statusAction(node, type, vmid, "shutdown");
const guestPath = (node: string, type: ProxmoxGuestType, vmid: number) => `/nodes/${nodeSeg(node)}/${typeSeg(type)}/${vmidSeg(vmid)}`;
const snapSeg = (name: string) => pathSegment(name, "snapshot name", ID_PATTERNS.proxmoxSnapshot);
const taskSeg = (upid: string) => pathSegment(upid, "task id", ID_PATTERNS.proxmoxTask);
async function listSnapshots(node: string, type: ProxmoxGuestType, vmid: number): Promise<ProxmoxSnapshot[]> {
const data = await api("GET", `${guestPath(node, type, vmid)}/snapshot`);
return (Array.isArray(data) ? data : [])
.filter((s: any) => typeof s?.name === "string" && s.name !== "current")
.map((s: any) => ({
name: s.name as string,
description: typeof s.description === "string" ? s.description.trim() : "",
takenAt: typeof s.snaptime === "number" && s.snaptime > 0 ? new Date(s.snaptime * 1000).toISOString() : null,
withRam: s.vmstate === 1 || s.vmstate === "1",
parent: typeof s.parent === "string" && s.parent !== "" ? s.parent : null,
}))
.sort((a, b) => (a.takenAt ?? "").localeCompare(b.takenAt ?? "") || a.name.localeCompare(b.name));
}
/** Follows a task until it has stopped, or for as long as it is allowed to, and says how it stands. */
async function followTask(node: string, upid: string, waitMs: number, everyMs = 1000): Promise<ProxmoxTaskResult> {
const until = Date.now() + waitMs;
for (;;) {
const status = await api("GET", `/nodes/${nodeSeg(node)}/tasks/${taskSeg(upid)}/status`);
if (status?.status === "stopped") {
const exit = typeof status.exitstatus === "string" ? status.exitstatus : null;
return { done: true, ok: exit === "OK", message: exit, upid };
}
if (Date.now() >= until) return { done: false, ok: null, message: null, upid };
await new Promise((r) => setTimeout(r, Math.min(everyMs, Math.max(0, until - Date.now()))));
}
}
/** A call that starts a task answers with the task's id. */
const upidOf = (data: unknown): string => {
if (typeof data !== "string" || !ID_PATTERNS.proxmoxTask.test(data)) throw new Error("Proxmox did not say which task it started.");
return data;
};
async function createSnapshot(node: string, type: ProxmoxGuestType, vmid: number, options: { name: string; description?: string; includeRam?: boolean }, waitMs = 0): Promise<ProxmoxTaskResult> {
snapSeg(options.name);
const params: Record<string, string | number> = { snapname: options.name };
if (options.description?.trim()) params.description = options.description.trim();
// Memory can only be kept for a virtual machine (a container has none to keep).
if (options.includeRam && type === "qemu") params.vmstate = 1;
const upid = upidOf(await api("POST", `${guestPath(node, type, vmid)}/snapshot`, params));
return followTask(node, upid, waitMs);
}
async function rollbackSnapshot(node: string, type: ProxmoxGuestType, vmid: number, name: string, waitMs = 0): Promise<ProxmoxTaskResult> {
const upid = upidOf(await api("POST", `${guestPath(node, type, vmid)}/snapshot/${snapSeg(name)}/rollback`));
return followTask(node, upid, waitMs);
}
async function deleteSnapshot(node: string, type: ProxmoxGuestType, vmid: number, name: string, waitMs = 0): Promise<ProxmoxTaskResult> {
const upid = upidOf(await api("DELETE", `${guestPath(node, type, vmid)}/snapshot/${snapSeg(name)}`));
return followTask(node, upid, waitMs);
}
async function ping(): Promise<{ ok: boolean; latencyMs?: number; error?: string }> {
const start = Date.now();
try {
@@ -556,6 +653,10 @@ export function createProxmoxAdapter(config: ProxmoxConfig): ProxmoxAdapter {
stopGuest,
restartGuest,
shutdownGuest,
listSnapshots,
createSnapshot,
rollbackSnapshot,
deleteSnapshot,
listBackupJobs,
listRecentBackupTasks,
});
+80
View File
@@ -871,6 +871,86 @@ integrationsRouter.get("/:id/proxmox/backups", asyncHandler(async (req, res) =>
}
}));
// ── Proxmox snapshots ─────────────────────────────────────────────────────
// Listing is for everyone signed in (like the guests); taking one is an operator's; rolling back and deleting one are an administrator's — a rollback throws away everything the guest has done since.
/** How long a request waits for Proxmox's task to finish before saying it is still going (the page then looks again). */
export const SNAPSHOT_WAIT_MS = 20_000;
/** The wait, which a test (or a very slow storage) can change with PROXMOX_TASK_WAIT_MS. */
const snapshotWaitMs = () => (Number(process.env.PROXMOX_TASK_WAIT_MS) > 0 ? Number(process.env.PROXMOX_TASK_WAIT_MS) : SNAPSHOT_WAIT_MS);
const snapshotBody = z.object({
name: z.string().trim().regex(ID_PATTERNS.proxmoxSnapshot, "A snapshot name starts with a letter, then letters, digits, - and _, at most 40 characters.").optional(),
description: z.string().trim().max(200).optional(),
includeRam: z.boolean().optional(),
});
/** A snapshot name made from the time, when none was given. */
export const autoSnapshotName = (now: Date = new Date()): string => `hlm-${now.toISOString().slice(0, 19).replace(/[-:]/g, "").replace("T", "-")}`;
/** The guest a request is about, checked before anything is asked of Proxmox; null (and a refusal sent) when it is not one. */
function guestFromParams(req: Request, res: Response): { node: string; type: "qemu" | "lxc"; vmid: number } | null {
if (!isValidId(req.params.node, ID_PATTERNS.proxmoxNode)) return (rejectInvalidId(res, "node name"), null);
const vmid = Number(req.params.vmid);
if (!Number.isInteger(vmid) || vmid < 1) return (res.status(400).json({ error: "invalid_vmid" }), null);
const type = req.params.type;
if (type !== "qemu" && type !== "lxc") return (res.status(400).json({ error: "invalid_type" }), null);
return { node: req.params.node, type, vmid };
}
integrationsRouter.get("/:id/proxmox/nodes/:node/:type/:vmid/snapshots", asyncHandler(async (req, res) => {
const found = await requireProxmoxAdapter(req, res);
if (!found) return;
const guest = guestFromParams(req, res);
if (!guest) return;
try {
res.json({ snapshots: await found.adapter.listSnapshots(guest.node, guest.type, guest.vmid) });
} catch (err) {
res.status(502).json({ error: err instanceof Error ? err.message : String(err) });
}
}));
/** Runs one snapshot task, writes it down, and says how it went: a task that ended badly is an error with what Proxmox said, one that is still going is said to be. */
async function snapshotTask(req: Request, res: Response, what: "create" | "rollback" | "delete", run: (found: NonNullable<Awaited<ReturnType<typeof requireProxmoxAdapter>>>, guest: { node: string; type: "qemu" | "lxc"; vmid: number }) => Promise<{ done: boolean; ok: boolean | null; message: string | null; upid: string }>, snapshot: string, extra: Record<string, unknown> = {}) {
const found = await requireProxmoxAdapter(req, res);
if (!found) return;
const guest = guestFromParams(req, res);
if (!guest) return;
let result;
try {
result = await run(found, guest);
} catch (err) {
return res.status(502).json({ error: err instanceof Error ? err.message : String(err) });
}
await recordAudit({
actor: req.currentUser!,
category: "integration",
action: `${what}_snapshot`,
targetType: "proxmox_guest",
targetId: guest.vmid,
detail: { integrationId: found.integration.id, node: guest.node, vmid: guest.vmid, guestType: guest.type, snapshot, done: result.done, ok: result.ok, ...extra },
});
if (result.done && !result.ok) return res.status(502).json({ error: `Proxmox: ${result.message ?? "the task failed"}`, snapshot, upid: result.upid });
res.json({ snapshot, done: result.done, ok: result.ok, upid: result.upid });
}
integrationsRouter.post("/:id/proxmox/nodes/:node/:type/:vmid/snapshots", requireRole("operator"), asyncHandler(async (req, res) => {
const parsed = snapshotBody.safeParse(req.body ?? {});
if (!parsed.success) return res.status(400).json({ error: "invalid_body", message: parsed.error.issues[0]?.message ?? "That is not a snapshot." });
const name = parsed.data.name ?? autoSnapshotName();
await snapshotTask(req, res, "create", (f, g) => f.adapter.createSnapshot(g.node, g.type, g.vmid, { name, description: parsed.data.description, includeRam: parsed.data.includeRam }, snapshotWaitMs()), name, { withRam: parsed.data.includeRam === true && req.params.type === "qemu" });
}));
integrationsRouter.post("/:id/proxmox/nodes/:node/:type/:vmid/snapshots/:name/rollback", requireRole("admin"), asyncHandler(async (req, res) => {
if (!isValidId(req.params.name, ID_PATTERNS.proxmoxSnapshot)) return rejectInvalidId(res, "snapshot name");
await snapshotTask(req, res, "rollback", (f, g) => f.adapter.rollbackSnapshot(g.node, g.type, g.vmid, req.params.name, snapshotWaitMs()), req.params.name);
}));
integrationsRouter.delete("/:id/proxmox/nodes/:node/:type/:vmid/snapshots/:name", requireRole("admin"), asyncHandler(async (req, res) => {
if (!isValidId(req.params.name, ID_PATTERNS.proxmoxSnapshot)) return rejectInvalidId(res, "snapshot name");
await snapshotTask(req, res, "delete", (f, g) => f.adapter.deleteSnapshot(g.node, g.type, g.vmid, req.params.name, snapshotWaitMs()), req.params.name);
}));
const proxmoxActions = ["start", "stop", "restart", "shutdown"] as const;
for (const action of proxmoxActions) {
+13
View File
@@ -123,6 +123,13 @@ function settingsSummary(detail: Record<string, unknown>): string | null {
}
/** What is left of the detail once the name and what is already in the sentence are taken out. */
/** "guest 105 on pve1", from what an audit entry about a Proxmox guest says. */
function guestWords(detail: Record<string, unknown>): string {
const id = typeof detail.vmid === "number" ? ` ${detail.vmid}` : "";
const node = typeof detail.node === "string" ? ` on ${detail.node}` : "";
return `guest${id}${node}`;
}
function genericSummary(detail: Record<string, unknown>, 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))
@@ -195,6 +202,12 @@ export function describeChange(category: string, action: string, detail: Record<
return { title: `${typeof detail.changed === "number" ? detail.changed : "Several"} snoozed alert${detail.changed === 1 ? "" : "s"} woken at once`, 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 "integration/create_snapshot":
return { title: `A snapshot was taken of ${guestWords(detail)}`, tone: "neutral", detail: str(detail.snapshot) ? `${str(detail.snapshot)}${detail.withRam ? " (with memory)" : ""}` : null };
case "integration/rollback_snapshot":
return { title: `${guestWords(detail)[0].toUpperCase()}${guestWords(detail).slice(1)} was rolled back to a snapshot`, tone: "bad", detail: str(detail.snapshot) };
case "integration/delete_snapshot":
return { title: `A snapshot was deleted from ${guestWords(detail)}`, tone: "neutral", detail: str(detail.snapshot) };
case "notification/resend":
return { title: "A notification was sent again", tone: "neutral", detail: null };
case "webhook/retry":
+4
View File
@@ -23,6 +23,10 @@ export const ID_PATTERNS = {
tailscaleDevice: /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/,
/** Proxmox node names are hostnames. */
proxmoxNode: /^[A-Za-z0-9][A-Za-z0-9.-]{0,62}$/,
/** A Proxmox snapshot name: starts with a letter, then letters, digits, "-" and "_", at most 40 characters (Proxmox's own rule). */
proxmoxSnapshot: /^[A-Za-z][A-Za-z0-9_-]{0,39}$/,
/** A Proxmox task id (a "UPID"): UPID:node:hex:hex:hex:type:id:user: — letters, digits and the few marks it is made of. */
proxmoxTask: /^UPID:[A-Za-z0-9._@!:-]{1,250}$/,
/** Gitea user/organisation and repository names. */
giteaName: /^(?!\.{1,2}$)[A-Za-z0-9._-]{1,100}$/,
/** Docker container IDs and names. */
+310
View File
@@ -0,0 +1,310 @@
/**
* Proxmox snapshots: listing them, taking one (with or without memory), rolling back and deleting, each a Proxmox task that is followed until it stops; what is refused before Proxmox is asked,
* who may do which, and that every one is written in the audit log. Against a pretend Proxmox.
*
* Run with: npm test --workspace server
*/
import { test, describe, before, after, beforeEach } from "node:test";
import assert from "node:assert/strict";
import { createServer as createHttpServer, type Server } from "node:http";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { AddressInfo } from "node:net";
const dir = mkdtempSync(join(tmpdir(), "hm-pvesnap-"));
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.PROXMOX_TASK_WAIT_MS = "300";
const express = (await import("express")).default;
const { db } = await import("../src/db/client.js");
const { users, integrations, auditLog } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const { createProxmoxAdapter } = await import("../src/integrations/proxmox/adapter.js");
const { integrationsRouter, autoSnapshotName } = await import("../src/routes/integrations.js");
const { ID_PATTERNS } = await import("../src/utils/pathSegment.js");
const { subjectOfConditionKey } = await import("../src/services/maintenance.js");
const { snapshotDepths } = await import("../../web/src/utils/proxmoxSnapshots.js");
await runMigrations();
const UPID = "UPID:pve1:00001A2B:0003C4D5:67890ABC:qmsnapshot:100:root@pam:";
let seen: { method: string; path: string; body: string; auth: string }[] = [];
/** How the task ends: how many times it answers "running" first, and the exit status once it has stopped (null: it never stops). */
let task: { runningFirst: number; exit: string | null } = { runningFirst: 0, exit: "OK" };
let polls = 0;
let listAnswer: unknown[] = [];
let apiFailure: number | null = null;
let badUpid = false;
let pve: Server;
let pveUrl = "";
before(async () => {
pve = createHttpServer((req, res) => {
let body = "";
req.on("data", (c) => (body += c));
req.on("end", () => {
const u = new URL(req.url ?? "", "http://x");
seen.push({ method: req.method ?? "", path: u.pathname, body, auth: String(req.headers.authorization ?? "") });
const send = (status: number, json: unknown) => {
res.writeHead(status, { "content-type": "application/json" });
res.end(JSON.stringify(json));
};
if (apiFailure !== null) return send(apiFailure, { errors: { snapname: "bad" }, message: "no good" });
if (/\/tasks\/[^/]+\/status$/.test(u.pathname)) {
polls++;
return send(200, { data: polls <= task.runningFirst || task.exit === null ? { status: "running" } : { status: "stopped", exitstatus: task.exit } });
}
if (/\/snapshot$/.test(u.pathname) && req.method === "GET") return send(200, { data: listAnswer });
if (/\/snapshot(\/[^/]+(\/rollback)?)?$/.test(u.pathname)) return send(200, { data: badUpid ? { not: "a task" } : UPID });
send(404, { message: "no such thing" });
});
});
await new Promise<void>((resolve) => pve.listen(0, "127.0.0.1", resolve));
pveUrl = `http://127.0.0.1:${(pve.address() as AddressInfo).port}`;
});
beforeEach(() => {
seen = [];
polls = 0;
task = { runningFirst: 0, exit: "OK" };
apiFailure = null;
badUpid = false;
listAnswer = [];
});
after(() => {
pve.close();
});
const adapter = () => createProxmoxAdapter({ url: pveUrl, tokenId: "root@pam!lab", tokenSecret: "s3cret", insecure: true });
describe("listing", () => {
test("the snapshots of a guest, oldest first, without the line that is the guest as it is now", async () => {
listAnswer = [
{ name: "after-update", description: " after the update ", snaptime: 1_760_000_100, vmstate: 1, parent: "before-update" },
{ name: "current", description: "You are here!", parent: "after-update" },
{ name: "before-update", description: "", snaptime: 1_760_000_000, vmstate: 0 },
];
const list = await adapter().listSnapshots("pve1", "qemu", 100);
assert.deepEqual(list.map((s) => [s.name, s.description, s.withRam, s.parent]), [["before-update", "", false, null], ["after-update", "after the update", true, "before-update"]]);
assert.equal(list[0].takenAt, new Date(1_760_000_000_000).toISOString());
assert.deepEqual(seen.map((s) => [s.method, s.path, s.auth]), [["GET", "/api2/json/nodes/pve1/qemu/100/snapshot", "PVEAPIToken=root@pam!lab=s3cret"]]);
});
test("a guest with none, a time Proxmox did not give, and an answer that is not a list", async () => {
assert.deepEqual(await adapter().listSnapshots("pve1", "lxc", 200), []);
listAnswer = [{ name: "odd" }];
assert.equal((await adapter().listSnapshots("pve1", "lxc", 200))[0].takenAt, null);
listAnswer = {} as never;
assert.deepEqual(await adapter().listSnapshots("pve1", "qemu", 1), [], "an answer that is not a list is none");
});
});
describe("taking one", () => {
test("the name goes as a form, with the description, and the memory only for a virtual machine that asked for it", async () => {
await adapter().createSnapshot("pve1", "qemu", 100, { name: "before-upgrade", description: " before the upgrade ", includeRam: true });
assert.equal(seen[0].method, "POST");
assert.equal(seen[0].path, "/api2/json/nodes/pve1/qemu/100/snapshot");
assert.deepEqual(Object.fromEntries(new URLSearchParams(seen[0].body)), { snapname: "before-upgrade", description: "before the upgrade", vmstate: "1" });
seen = [];
await adapter().createSnapshot("pve1", "qemu", 100, { name: "plain" });
assert.deepEqual(Object.fromEntries(new URLSearchParams(seen[0].body)), { snapname: "plain" });
seen = [];
await adapter().createSnapshot("pve1", "lxc", 200, { name: "ct", includeRam: true, description: " " });
assert.deepEqual(Object.fromEntries(new URLSearchParams(seen[0].body)), { snapname: "ct" }, "a container has no memory to keep, and a blank description is none");
});
test("with no time to wait it answers with the task and says it has not finished; with time it follows it to the end", async () => {
task = { runningFirst: 2, exit: "OK" };
const quick = await adapter().createSnapshot("pve1", "qemu", 100, { name: "a" });
assert.deepEqual([quick.done, quick.ok, quick.upid], [false, null, UPID]);
polls = 0;
const waited = await adapter().createSnapshot("pve1", "qemu", 100, { name: "b" }, 5000);
assert.deepEqual([waited.done, waited.ok, waited.message], [true, true, "OK"]);
assert.ok(polls >= 3, "it asked more than once");
});
test("a task that ends badly says what Proxmox said; one that never ends is left running when the wait is over", async () => {
task = { runningFirst: 0, exit: "snapshot feature is not available" };
const bad = await adapter().createSnapshot("pve1", "qemu", 100, { name: "c" }, 2000);
assert.deepEqual([bad.done, bad.ok, bad.message], [true, false, "snapshot feature is not available"]);
task = { runningFirst: 0, exit: null };
const slow = await adapter().createSnapshot("pve1", "qemu", 100, { name: "d" }, 150);
assert.deepEqual([slow.done, slow.ok], [false, null]);
});
});
describe("rolling back and deleting", () => {
test("a rollback is a POST to the snapshot's rollback, a deletion a DELETE of it, each followed as a task", async () => {
const back = await adapter().rollbackSnapshot("pve1", "lxc", 200, "before-upgrade", 2000);
const gone = await adapter().deleteSnapshot("pve1", "lxc", 200, "before-upgrade", 2000);
assert.deepEqual([back.ok, gone.ok], [true, true]);
const calls = seen.filter((s) => !/\/tasks\//.test(s.path)).map((s) => [s.method, s.path]);
assert.deepEqual(calls, [["POST", "/api2/json/nodes/pve1/lxc/200/snapshot/before-upgrade/rollback"], ["DELETE", "/api2/json/nodes/pve1/lxc/200/snapshot/before-upgrade"]]);
assert.ok(seen.some((s) => s.path.includes("/tasks/UPID%3Apve1") && s.path.endsWith("/status")), "and the task was asked after");
});
});
describe("what is refused before Proxmox is asked", () => {
test("a snapshot name that Proxmox would not take, or that is a path, never goes out", async () => {
for (const bad of ["1starts-with-digit", "../../x", "a b", "a/b", "", "x".repeat(41), "name?x=1", "%2e%2e", "-dash"]) {
await assert.rejects(() => adapter().createSnapshot("pve1", "qemu", 100, { name: bad }), /snapshot name/, JSON.stringify(bad));
await assert.rejects(() => adapter().rollbackSnapshot("pve1", "qemu", 100, bad), /snapshot name/);
await assert.rejects(() => adapter().deleteSnapshot("pve1", "qemu", 100, bad), /snapshot name/);
}
assert.deepEqual(seen, []);
for (const ok of ["a", "Before_upgrade-2", "x".repeat(40)]) assert.match(ok, ID_PATTERNS.proxmoxSnapshot);
});
test("a node, a guest type and a number are checked as for the power actions; an answer with no task is an error", async () => {
await assert.rejects(() => adapter().listSnapshots("../etc", "qemu", 1), /node name/);
await assert.rejects(() => adapter().listSnapshots("pve1", "vm" as never, 1), /guest type/);
await assert.rejects(() => adapter().listSnapshots("pve1", "qemu", 1.5), /VM ID/);
assert.deepEqual(seen, []);
badUpid = true;
await assert.rejects(() => adapter().createSnapshot("pve1", "qemu", 100, { name: "z" }), /did not say which task/);
});
test("an error from Proxmox is the error: what it said", async () => {
apiFailure = 403;
await assert.rejects(() => adapter().listSnapshots("pve1", "qemu", 100), /snapname|no good/);
});
});
describe("how the page indents them", () => {
const snap = (name: string, parent: string | null) => ({ name, parent });
test("a chain, each taken after the one before, is all at the left edge", () => {
assert.deepEqual(snapshotDepths([snap("a", null), snap("b", "a"), snap("c", "b")]), { a: 0, b: 0, c: 0 });
});
test("a branch — two taken after the same one — is indented, and what follows it with it", () => {
const d = snapshotDepths([snap("a", null), snap("b", "a"), snap("c", "a"), snap("d", "c")]);
assert.deepEqual(d, { a: 0, b: 1, c: 1, d: 1 });
});
test("a parent that is not in the list is the top, and a loop cannot hang it", () => {
assert.deepEqual(snapshotDepths([snap("x", "gone")]), { x: 0 });
assert.deepEqual(snapshotDepths([snap("a", "b"), snap("b", "a")]), { a: 0, b: 0 });
assert.deepEqual(snapshotDepths([]), {});
});
});
describe("through the routes", () => {
let app: Server;
let base = "";
let who = "operator";
let id = 0;
const call = (method: string, path: string, body?: unknown) =>
fetch(`${base}/${id}/proxmox/nodes/pve1/qemu/100/snapshots${path}`, { method, headers: { "content-type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
const audits = async (action: string) => (await db.select().from(auditLog)).filter((e) => e.action === action);
before(async () => {
await db.insert(users).values([
{ oidcSub: "admin", name: "Ada", role: "admin" },
{ oidcSub: "operator", name: "Olle", role: "operator" },
{ oidcSub: "viewer", name: "Vic", role: "viewer" },
]);
id = (await db.insert(integrations).values({ type: "proxmox", name: "pve", baseUrl: pveUrl, config: JSON.stringify({ url: pveUrl, tokenId: "root@pam!lab", tokenSecret: "s3cret", insecure: true }) }).returning({ id: integrations.id }))[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/integrations", integrationsRouter);
app = await new Promise<Server>((resolve) => {
const s = a.listen(0, "127.0.0.1", () => resolve(s));
});
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/integrations`;
});
after(() => {
app.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows keeps the database file locked until the process exits.
}
});
test("anyone signed in can list; the list is what the adapter read", async () => {
who = "viewer";
listAnswer = [{ name: "one", snaptime: 1_760_000_000 }];
const res = await call("GET", "");
assert.equal(res.status, 200);
assert.deepEqual(((await res.json()) as { snapshots: { name: string }[] }).snapshots.map((s) => s.name), ["one"]);
});
test("an operator takes one: it is named from the time when no name is given, checked when it is, done, and written down; a viewer may not", async () => {
who = "viewer";
assert.equal((await call("POST", "", {})).status, 403);
assert.deepEqual(seen, []);
who = "operator";
const res = await call("POST", "", { description: "before the upgrade", includeRam: true });
assert.equal(res.status, 200);
const body = (await res.json()) as { snapshot: string; done: boolean; ok: boolean };
assert.match(body.snapshot, /^hlm-\d{8}-\d{6}$/);
assert.deepEqual([body.done, body.ok], [true, true]);
assert.equal(new URLSearchParams(seen.find((s) => s.method === "POST" && s.path.endsWith("/snapshot"))!.body).get("snapname"), body.snapshot);
const [entry] = await audits("create_snapshot");
const detail = JSON.parse(entry.detail ?? "{}");
assert.deepEqual([entry.category, entry.targetType, entry.targetId, detail.snapshot, detail.vmid, detail.node, detail.withRam, detail.ok], ["integration", "proxmox_guest", "100", body.snapshot, 100, "pve1", true, true]);
assert.match(autoSnapshotName(new Date("2026-11-10T12:34:56Z")), /^hlm-20261110-123456$/);
});
test("a name that is not one is refused with why, and a description that is too long; nothing is asked of Proxmox", async () => {
who = "operator";
seen = [];
const name = await call("POST", "", { name: "1bad" });
assert.equal(name.status, 400);
assert.match(((await name.json()) as { message: string }).message, /starts with a letter/);
assert.equal((await call("POST", "", { description: "x".repeat(201) })).status, 400);
assert.deepEqual(seen, []);
});
test("a task that is slow is said to be still going; one that fails is an error with what Proxmox said", async () => {
who = "operator";
task = { runningFirst: 0, exit: null };
const slow = (await (await call("POST", "", { name: "slow" })).json()) as { done: boolean; ok: boolean | null; upid: string };
assert.deepEqual([slow.done, slow.ok, slow.upid], [false, null, UPID]);
task = { runningFirst: 0, exit: "VM is locked (backup)" };
const failed = await call("POST", "", { name: "locked" });
assert.equal(failed.status, 502);
assert.match(((await failed.json()) as { error: string }).error, /Proxmox: VM is locked \(backup\)/);
});
test("rolling back and deleting are an administrator's, each checked, done and written down", async () => {
who = "operator";
assert.equal((await call("POST", "/before-upgrade/rollback")).status, 403);
assert.equal((await call("DELETE", "/before-upgrade")).status, 403);
who = "admin";
seen = [];
assert.equal((await call("POST", "/1bad/rollback")).status, 400);
assert.equal((await call("DELETE", "/..%2Fx")).status, 400);
assert.deepEqual(seen, [], "nothing was asked of Proxmox");
assert.equal((await call("POST", "/before-upgrade/rollback")).status, 200);
assert.equal((await call("DELETE", "/before-upgrade")).status, 200);
assert.equal((await audits("rollback_snapshot")).length, 1);
assert.equal(JSON.parse((await audits("delete_snapshot"))[0].detail ?? "{}").snapshot, "before-upgrade");
});
test("a guest that is not one, and an integration of another kind, are refused", async () => {
who = "admin";
seen = [];
for (const path of ["/nodes/..%2Fx/qemu/100/snapshots", "/nodes/pve1/vm/100/snapshots", "/nodes/pve1/qemu/abc/snapshots", "/nodes/pve1/qemu/0/snapshots"]) {
const res = await fetch(`${base}/${id}/proxmox${path}`);
assert.equal(res.status, 400, path);
}
assert.deepEqual(seen, []);
const other = (await db.insert(integrations).values({ type: "gitea", name: "g", baseUrl: "http://g", config: JSON.stringify({}) }).returning({ id: integrations.id }))[0].id;
assert.equal((await fetch(`${base}/${other}/proxmox/nodes/pve1/qemu/100/snapshots`)).status, 400);
});
test("the change log says what happened in words, and the maintenance key is not involved", async () => {
const { describeChange } = await import("../src/services/changeLog.js");
const sentence = (action: string) => describeChange("integration", action, { vmid: 100, node: "pve1", snapshot: "s1", withRam: true });
assert.equal(sentence("create_snapshot").title, "A snapshot was taken of guest 100 on pve1");
assert.match(sentence("create_snapshot").detail ?? "", /s1 \(with memory\)/);
assert.equal(sentence("rollback_snapshot").title, "Guest 100 on pve1 was rolled back to a snapshot");
assert.equal(sentence("delete_snapshot").title, "A snapshot was deleted from guest 100 on pve1");
assert.equal(subjectOfConditionKey("not-a-snapshot-key"), null);
});
});