Add Back up now for Fragnet game servers
Operators can ask the game panel for a backup of a server whose plan has room for backups (Back up on the row, Back up now beside its backups). The panel makes it in the background; the page re-reads every 20 s until it is done. Refused here for a plan with no room, a suspended server, one already being backed up, or the same server within 30 s; the panel's own refusals (plan full, rate limit, permission) are shown in its words. Written to the audit log. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
31f4debb9a
commit
f9991a49af
9 files changed
+326
-11
No files matched your search
@@ -6,7 +6,7 @@
|
||||
*
|
||||
* Reading: the servers of the account (`GET /api/client`, paged, with the game — the egg — and the addresses) and, for each, `…/resources` (running or not, memory, CPU, disk, uptime), `…/backups`,
|
||||
* `…/schedules` and `…/databases`. A part that cannot be read (a sub-user without that permission gets a 403) is null for that server, which is not the same as none. The only thing ever
|
||||
* written is a **power signal** (`POST …/power`: start, stop, restart or kill), and only when someone asks for it on the page.
|
||||
* written are a **power signal** (`POST …/power`: start, stop, restart or kill) and a **backup** (`POST …/backups`: make one now, with a name that says it was asked for here), each only when someone asks for it on the page.
|
||||
*
|
||||
* Endpoints and field names are from Pterodactyl's source (ServerTransformer, StatsTransformer, BackupTransformer, ScheduleTransformer) and the panel's own documentation (docs.fragnet.net),
|
||||
* not from a live account: Fragnet's fork may differ, so every field is read defensively. The panel allows a limited number of requests a minute (429); a pass makes four per server.
|
||||
@@ -114,6 +114,8 @@ export interface FragnetAdapter {
|
||||
ping(): Promise<{ ok: boolean; latencyMs?: number; error?: string }>;
|
||||
read(): Promise<FragnetRead>;
|
||||
power(serverId: string, signal: PowerSignal): Promise<void>;
|
||||
/** Asks the panel to make a backup now (it is made in the background: what comes back is the one being made, with no completion time yet). Throws what the panel says when it refuses. */
|
||||
backup(serverId: string, name: string): Promise<FragnetBackup | null>;
|
||||
}
|
||||
|
||||
const PER_PAGE = 50;
|
||||
@@ -229,6 +231,16 @@ export function parseBackups(raw: unknown): FragnetBackup[] {
|
||||
return out.sort((x, y) => (y.createdAt ?? "").localeCompare(x.createdAt ?? ""));
|
||||
}
|
||||
|
||||
/** Pure: what a refusing panel says in its own words — the first of its `errors`. */
|
||||
export function panelDetail(raw: unknown): string | null {
|
||||
return str(obj(arr(obj(raw).errors)[0]).detail);
|
||||
}
|
||||
|
||||
/** Pure: the backup a `POST …/backups` made, as the panel answers (one backup, not a list). */
|
||||
export function parseNewBackup(raw: unknown): FragnetBackup | null {
|
||||
return parseBackups({ data: [raw] })[0] ?? null;
|
||||
}
|
||||
|
||||
/** Pure: `…/schedules` — the tasks that run on their own (a restart every night, a backup every Sunday). */
|
||||
export function parseSchedules(raw: unknown): FragnetSchedule[] {
|
||||
const out: FragnetSchedule[] = [];
|
||||
@@ -343,6 +355,24 @@ export function createFragnetAdapter(config: FragnetConfig): FragnetAdapter {
|
||||
if (res.status < 200 || res.status >= 300) throw new Error(`The panel answered with an error: HTTP ${res.status}`);
|
||||
}
|
||||
|
||||
async function backup(serverId: string, name: string): Promise<FragnetBackup | null> {
|
||||
if (!SERVER_ID.test(serverId)) throw new Error("That isn't a server id of the panel");
|
||||
const label = name.trim().slice(0, 100);
|
||||
if (label === "") throw new Error("A backup needs a name");
|
||||
const res = await requestJson(`${base}/servers/${serverId}/backups`, { method: "POST", headers, body: { name: label } });
|
||||
const said = panelDetail(res.json);
|
||||
if (res.status === 429) throw new Error("The panel only lets a few backups be made in a short while (HTTP 429) — try again in ten minutes");
|
||||
if (res.status === 401) throw refusal(401, true) as Error;
|
||||
// 403 here is this server's permission for the key's user (a sub-user), not a key the panel refuses.
|
||||
if (res.status === 403) throw new Error("The account may not make backups on this server (HTTP 403) — as a sub-user it needs the Backups → Create permission");
|
||||
if (res.status === 409) throw new Error("The panel says the server is busy (HTTP 409) — it is being installed, transferred or restored, or is suspended");
|
||||
if (res.status === 404) throw new Error("The panel does not know that server (HTTP 404)");
|
||||
// A server that is at the number of backups its plan allows is refused with a 400 that says so.
|
||||
if (res.status === 400) throw new Error(`The panel refused to make a backup: ${said ?? "HTTP 400"}`);
|
||||
if (res.status < 200 || res.status >= 300) throw new Error(`The panel answered with an error: HTTP ${res.status}${said ? ` — ${said}` : ""}`);
|
||||
return parseNewBackup(res.json);
|
||||
}
|
||||
|
||||
async function ping(): Promise<{ ok: boolean; latencyMs?: number; error?: string }> {
|
||||
const start = Date.now();
|
||||
try {
|
||||
@@ -355,5 +385,5 @@ export function createFragnetAdapter(config: FragnetConfig): FragnetAdapter {
|
||||
}
|
||||
}
|
||||
|
||||
return withDiagLogging("fragnet", { ping, read, power });
|
||||
return withDiagLogging("fragnet", { ping, read, power, backup });
|
||||
}
|
||||
@@ -62,6 +62,60 @@ fragnetRouter.post("/:id/refresh", requireRole("operator"), asyncHandler(async (
|
||||
res.json({ status });
|
||||
}));
|
||||
|
||||
/** A server that has just been asked for a backup is not asked again for this long (the panel itself allows only two in ten minutes, and a double click must not use one up). */
|
||||
export const BACKUP_COOLDOWN_MS = 30_000;
|
||||
const lastBackupAsked = new Map<string, number>();
|
||||
/** A backup that has been "being made" for longer than this is taken to have failed or been lost, and no longer stops another being asked for. */
|
||||
const BACKUP_STALE_MS = 2 * 60 * 60_000;
|
||||
|
||||
/**
|
||||
* Asks the panel to make a backup of one game server now — before a risky change, say. Only a server the last read found can be backed up, as with a power signal. Refused here, before the panel is
|
||||
* asked, when its plan has no room for backups, or one is already being made. The backup is made by the panel in the background (the page reads again a little later to show it); a server at the number
|
||||
* of backups its plan allows is refused by the panel, which says so.
|
||||
*/
|
||||
fragnetRouter.post("/:id/servers/:server/backup", requireRole("operator"), asyncHandler(async (req, res) => {
|
||||
const id = Number(req.params.id);
|
||||
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
|
||||
const serverId = String(req.params.server);
|
||||
if (!SERVER_ID.test(serverId)) return res.status(400).json({ error: "invalid_server" });
|
||||
const loaded = await loadIntegrationConfig(id);
|
||||
if (!loaded) return res.status(404).json({ error: "not_found" });
|
||||
if (loaded.integration.type !== "fragnet") return res.status(400).json({ error: "wrong_type" });
|
||||
if (!loaded.integration.enabled) return res.status(400).json({ error: "integration_disabled" });
|
||||
const [state] = await db.select().from(fragnetState).where(eq(fragnetState.integrationId, id)).limit(1);
|
||||
const server = state ? serversOf(state).find((s) => s.id === serverId) : undefined;
|
||||
if (!server) return res.status(404).json({ error: "server_not_found" });
|
||||
if (!server.backupLimit) return res.status(400).json({ error: "no_backups_on_plan", message: `${server.name}'s plan has no room for backups.` });
|
||||
if (server.suspended || server.installing) return res.status(409).json({ error: "server_busy", message: `${server.name} is suspended or being installed.` });
|
||||
const now = Date.now();
|
||||
if ((server.backups ?? []).some((b) => b.completedAt === null && now - Date.parse(b.createdAt ?? "") < BACKUP_STALE_MS)) return res.status(409).json({ error: "already_being_made", message: `A backup of ${server.name} is already being made.` });
|
||||
const key = `${id}:${serverId}`;
|
||||
const before = lastBackupAsked.get(key);
|
||||
if (before !== undefined && now - before < BACKUP_COOLDOWN_MS) {
|
||||
const retryAfterSeconds = Math.ceil((BACKUP_COOLDOWN_MS - (now - before)) / 1000);
|
||||
return res.status(429).set("Retry-After", String(retryAfterSeconds)).json({ error: "too_soon", message: `A backup of ${server.name} was just asked for — try again in ${retryAfterSeconds} s.`, retryAfterSeconds });
|
||||
}
|
||||
lastBackupAsked.set(key, now);
|
||||
const name = `Homelab Manager — ${new Date(now).toISOString().slice(0, 16).replace("T", " ")} UTC`;
|
||||
let made;
|
||||
try {
|
||||
made = await createFragnetAdapter(loaded.config as never).backup(serverId, name);
|
||||
} catch (err) {
|
||||
// Nothing was made, so nothing is held against the next try.
|
||||
lastBackupAsked.delete(key);
|
||||
return res.status(502).json({ error: err instanceof Error ? err.message : String(err) });
|
||||
}
|
||||
await recordAudit({
|
||||
actor: req.currentUser!,
|
||||
category: "integration",
|
||||
action: "backup_game_server",
|
||||
targetType: "fragnet_server",
|
||||
targetId: serverId,
|
||||
detail: { integrationId: id, name: server.name, game: server.game, backupName: name, backup: made?.uuid ?? null },
|
||||
});
|
||||
res.status(201).json({ name, uuid: made?.uuid ?? null });
|
||||
}));
|
||||
|
||||
/** Sends a power signal (start, stop, restart or kill) to one game server. Only a server the last read found can be signalled — what is typed in the address is never put into a call to the panel. */
|
||||
fragnetRouter.post("/:id/servers/:server/power", requireRole("operator"), asyncHandler(async (req, res) => {
|
||||
const id = Number(req.params.id);
|
||||
|
||||
@@ -149,6 +149,8 @@ describe("what the panel's API says", () => {
|
||||
let databasesStatus = 200;
|
||||
let rejectIncludes = false;
|
||||
let powerStatus = 204;
|
||||
let backupStatus = 200;
|
||||
let backupDetail = "";
|
||||
const seen: { method: string | undefined; path: string; auth: string | undefined; body: string }[] = [];
|
||||
before(async () => {
|
||||
fake = createHttpServer((req, res) => {
|
||||
@@ -171,6 +173,7 @@ describe("what the panel's API says", () => {
|
||||
const m = /^\/api\/client\/servers\/([a-z0-9]{8})\/(resources|backups|schedules|databases|power)$/.exec(u.pathname);
|
||||
if (!m) return send(404, {});
|
||||
if (m[2] === "power") return req.method === "POST" ? send(powerStatus, {}) : send(405, {});
|
||||
if (m[2] === "backups" && req.method === "POST") return backupStatus === 200 ? send(200, apiBackup("new-backup", "2026-06-10T12:00:00Z", null, false)) : send(backupStatus, { errors: [{ code: "Refused", status: String(backupStatus), detail: backupDetail }] });
|
||||
if (m[2] === "resources") return send(200, apiResources(m[1] === "abcd1234" ? "running" : "offline"));
|
||||
if (m[2] === "backups") return send(200, { object: "list", data: [apiBackup("b1", "2026-06-01T00:00:00Z", "2026-06-01T00:03:00Z")], meta: { pagination: { current_page: 1, total_pages: 1 } } });
|
||||
if (m[2] === "schedules") return send(200, { object: "list", data: [{ attributes: { id: 1, name: "Restart", cron: { minute: "0", hour: "4", day_of_month: "*", month: "*", day_of_week: "*" }, is_active: true } }] });
|
||||
@@ -222,6 +225,51 @@ describe("what the panel's API says", () => {
|
||||
assert.equal((await adapter.createFragnetAdapter({ token: "t", url: "http://127.0.0.1:1" }).ping()).ok, false);
|
||||
});
|
||||
|
||||
test("a backup is a POST of a name to that server's backups; what comes back is the one being made, and what the panel says when it refuses is said", async () => {
|
||||
seen.length = 0;
|
||||
const made = await adapter.createFragnetAdapter({ token: "t", url }).backup("abcd1234", " Homelab Manager — test ");
|
||||
assert.deepEqual(seen.map((x) => [x.method, x.path, x.body]), [["POST", "/api/client/servers/abcd1234/backups", JSON.stringify({ name: "Homelab Manager — test" })]]);
|
||||
assert.deepEqual([made?.uuid, made?.completedAt, made?.successful], ["new-backup", null, false], "being made: no completion time yet");
|
||||
const refuse = async (status: number, detail = "") => {
|
||||
backupStatus = status;
|
||||
backupDetail = detail;
|
||||
try {
|
||||
await adapter.createFragnetAdapter({ token: "t", url }).backup("abcd1234", "x");
|
||||
return "";
|
||||
} catch (err) {
|
||||
return (err as Error).message;
|
||||
} finally {
|
||||
backupStatus = 200;
|
||||
}
|
||||
};
|
||||
assert.equal(await refuse(400, "Cannot create a new backup, this server has reached its limit of 3 backups."), "The panel refused to make a backup: Cannot create a new backup, this server has reached its limit of 3 backups.");
|
||||
assert.match(await refuse(400), /refused to make a backup: HTTP 400/);
|
||||
assert.match(await refuse(403), /may not make backups on this server \(HTTP 403\).*Backups → Create/);
|
||||
assert.match(await refuse(429), /only lets a few backups be made in a short while \(HTTP 429\)/);
|
||||
assert.match(await refuse(409), /busy \(HTTP 409\)/);
|
||||
assert.match(await refuse(404), /does not know that server/);
|
||||
assert.match(await refuse(500, "boom"), /HTTP 500 — boom/);
|
||||
keyOk = false;
|
||||
assert.match(await refuse(200), /did not accept the key \(HTTP 401\)/);
|
||||
keyOk = true;
|
||||
});
|
||||
|
||||
test("nothing but a server id of the panel and a name is accepted for a backup", async () => {
|
||||
seen.length = 0;
|
||||
await assert.rejects(() => adapter.createFragnetAdapter({ token: "t", url }).backup("../../x", "n"), /isn't a server id/);
|
||||
await assert.rejects(() => adapter.createFragnetAdapter({ token: "t", url }).backup("abcd1234", " "), /needs a name/);
|
||||
assert.deepEqual(seen, []);
|
||||
assert.equal((await adapter.createFragnetAdapter({ token: "t", url }).backup("abcd1234", "n".repeat(300)))?.uuid, "new-backup");
|
||||
assert.equal(JSON.parse(seen[0].body).name.length, 100, "cut to 100 characters");
|
||||
});
|
||||
|
||||
test("the panel's own words and a new backup are read from what it sends", () => {
|
||||
assert.equal(adapter.panelDetail({ errors: [{ code: "TooManyBackupsException", detail: "limit reached" }] }), "limit reached");
|
||||
assert.equal(adapter.panelDetail({ errors: [] }), null);
|
||||
assert.equal(adapter.panelDetail(null), null);
|
||||
assert.equal(adapter.parseNewBackup({ object: "backup", attributes: { name: "no uuid" } }), null);
|
||||
});
|
||||
|
||||
test("a power signal is a POST of exactly that signal to that server; a busy server and an unknown one are said; nothing else is accepted", async () => {
|
||||
seen.length = 0;
|
||||
await adapter.createFragnetAdapter({ token: "t", url }).power("abcd1234", "restart");
|
||||
@@ -503,3 +551,123 @@ describe("the health pass, the page, the power signals and /metrics", () => {
|
||||
assert.deepEqual(await db.select().from(fragnetState).where(eq(fragnetState.integrationId, fgId)), []);
|
||||
});
|
||||
});
|
||||
|
||||
describe("back up now", () => {
|
||||
let app: Server;
|
||||
let panel: Server;
|
||||
let base = "";
|
||||
let id = 0;
|
||||
let panelStatus = 200;
|
||||
let panelDetailText = "";
|
||||
const asked: string[] = [];
|
||||
const post = (sub: string, server: string, integration = id) => fetch(`${base}/${integration}/servers/${server}/backup`, { method: "POST", headers: { "x-sub": sub } });
|
||||
|
||||
before(async () => {
|
||||
panel = createHttpServer((req, res) => {
|
||||
let body = "";
|
||||
req.on("data", (c) => (body += c));
|
||||
req.on("end", () => {
|
||||
asked.push(`${req.method} ${req.url} ${body}`);
|
||||
res.writeHead(panelStatus, { "content-type": "application/json" });
|
||||
res.end(JSON.stringify(panelStatus === 200 ? apiBackup("made-1", new Date().toISOString(), null, false) : { errors: [{ code: "Refused", detail: panelDetailText }] }));
|
||||
});
|
||||
});
|
||||
await new Promise<void>((resolve) => panel.listen(0, "127.0.0.1", resolve));
|
||||
const panelUrl = `http://127.0.0.1:${(panel.address() as AddressInfo).port}`;
|
||||
id = (await db.insert(integrations).values({ type: "fragnet", name: "Backups account", baseUrl: panelUrl, config: JSON.stringify({ token: "ptlc_x", url: panelUrl }) }).returning({ id: integrations.id }))[0].id;
|
||||
const now = Date.now();
|
||||
await fn.storeRead(
|
||||
id,
|
||||
read(
|
||||
server({ id: "aaaa1111", name: "fine", backups: [okBackup(DAY)] }),
|
||||
server({ id: "bbbb2222", name: "no-room", backupLimit: 0 }),
|
||||
server({ id: "cccc3333", name: "busy", backups: [okBackup(DAY), { uuid: "going", name: null, bytes: 0, createdAt: iso(now - 10 * MIN), completedAt: null, successful: false, locked: false }] }),
|
||||
server({ id: "dddd4444", name: "stale", backups: [{ uuid: "lost", name: null, bytes: 0, createdAt: iso(now - 3 * HOUR), completedAt: null, successful: false, locked: false }] }),
|
||||
server({ id: "eeee5555", name: "suspended", suspended: true }),
|
||||
server({ id: "ffff6666", name: "refused" }),
|
||||
server({ id: "gggg7777", name: "twice" }),
|
||||
),
|
||||
new Date(),
|
||||
);
|
||||
const a = express();
|
||||
a.use((req, _res, next) => {
|
||||
(req as unknown as { session: unknown }).session = { user: { sub: String(req.headers["x-sub"] ?? "viewer") } };
|
||||
next();
|
||||
});
|
||||
a.use("/api/fragnet", fragnetRouter);
|
||||
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/fragnet`;
|
||||
});
|
||||
after(() => {
|
||||
app.close();
|
||||
panel.close();
|
||||
});
|
||||
|
||||
test("an operator may, a viewer may not; the panel is asked for a backup with a name that says it was asked for here, and the audit log has it", async () => {
|
||||
assert.equal((await post("viewer", "aaaa1111")).status, 403);
|
||||
assert.deepEqual(asked, []);
|
||||
const res = await post("operator", "aaaa1111");
|
||||
assert.equal(res.status, 201);
|
||||
const body = (await res.json()) as { name: string; uuid: string | null };
|
||||
assert.match(body.name, /^Homelab Manager — \d{4}-\d{2}-\d{2} \d{2}:\d{2} UTC$/);
|
||||
assert.equal(body.uuid, "made-1");
|
||||
assert.deepEqual(asked, [`POST /api/client/servers/aaaa1111/backups ${JSON.stringify({ name: body.name })}`]);
|
||||
const entry = (await db.select().from(auditLog)).filter((e) => e.action === "backup_game_server").pop()!;
|
||||
assert.deepEqual([entry.category, entry.targetType, entry.targetId], ["integration", "fragnet_server", "aaaa1111"]);
|
||||
assert.match(entry.detail ?? "", /"name":"fine"/);
|
||||
assert.match(entry.detail ?? "", /"backup":"made-1"/);
|
||||
});
|
||||
|
||||
test("a server asked for a backup a moment ago is not asked again — and is, once the wait is over; another server is not held up", async () => {
|
||||
asked.length = 0;
|
||||
assert.equal((await post("operator", "gggg7777")).status, 201);
|
||||
const again = await post("operator", "gggg7777");
|
||||
assert.equal(again.status, 429);
|
||||
const body = (await again.json()) as { error: string; retryAfterSeconds: number };
|
||||
assert.equal(body.error, "too_soon");
|
||||
assert.ok(body.retryAfterSeconds >= 1 && body.retryAfterSeconds <= 30);
|
||||
assert.equal(again.headers.get("retry-after"), String(body.retryAfterSeconds));
|
||||
assert.equal(asked.length, 1, "the panel was not asked the second time");
|
||||
const { BACKUP_COOLDOWN_MS } = await import("../src/routes/fragnet.js");
|
||||
assert.equal(BACKUP_COOLDOWN_MS, 30_000);
|
||||
});
|
||||
|
||||
test("a plan with no room for backups, a backup already being made, and a server that is suspended are refused before the panel is asked — a backup lost long ago is not in the way", async () => {
|
||||
asked.length = 0;
|
||||
const noRoom = await post("operator", "bbbb2222");
|
||||
assert.deepEqual([noRoom.status, ((await noRoom.json()) as { error: string }).error], [400, "no_backups_on_plan"]);
|
||||
const busy = await post("operator", "cccc3333");
|
||||
assert.deepEqual([busy.status, ((await busy.json()) as { error: string }).error], [409, "already_being_made"]);
|
||||
const suspended = await post("operator", "eeee5555");
|
||||
assert.deepEqual([suspended.status, ((await suspended.json()) as { error: string }).error], [409, "server_busy"]);
|
||||
assert.deepEqual(asked, []);
|
||||
assert.equal((await post("operator", "dddd4444")).status, 201, "one 'being made' for three hours is taken to be lost");
|
||||
});
|
||||
|
||||
test("what the panel says when it refuses is the answer, and a refusal is not held against the next try", async () => {
|
||||
asked.length = 0;
|
||||
panelStatus = 400;
|
||||
panelDetailText = "Cannot create a new backup, this server has reached its limit of 3 backups.";
|
||||
const refused = await post("operator", "ffff6666");
|
||||
assert.equal(refused.status, 502);
|
||||
assert.match(((await refused.json()) as { error: string }).error, /reached its limit of 3 backups/);
|
||||
panelStatus = 200;
|
||||
assert.equal((await post("operator", "ffff6666")).status, 201, "nothing was made, so there is no wait");
|
||||
assert.equal(asked.length, 2);
|
||||
const refusalsLogged = (await db.select().from(auditLog)).filter((e) => e.action === "backup_game_server" && /ffff6666/.test(e.targetId ?? ""));
|
||||
assert.equal(refusalsLogged.length, 1, "only the backup that was asked for is in the audit log");
|
||||
});
|
||||
|
||||
test("only a server the last read found, and only a well-formed id, an integration that is there and one of this kind are accepted", async () => {
|
||||
asked.length = 0;
|
||||
assert.equal((await post("operator", "zzzz9999")).status, 404);
|
||||
assert.equal((await post("operator", "..%2F..%2Fx")).status, 400);
|
||||
assert.equal((await post("operator", "aaaa1111", 999999)).status, 404);
|
||||
const other = (await db.insert(integrations).values({ type: "hetzner", name: "Other", baseUrl: "https://api.hetzner.cloud", config: JSON.stringify({}) }).returning({ id: integrations.id }))[0].id;
|
||||
assert.equal((await post("operator", "aaaa1111", other)).status, 400);
|
||||
await db.delete(integrations).where(eq(integrations.id, other));
|
||||
assert.deepEqual(asked, []);
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user