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:
1 parent
12e9fee7af
commit
97df28c6dc
11 files changed
+733
-11
No files matched your search
@@ -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,
|
||||
});
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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":
|
||||
|
||||
@@ -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. */
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user