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:
bobbanandClaude Sonnet 5.5 committed 2026-11-06 19:48:46 +01:00
1 parent 31f4debb9a
commit f9991a49af
9 files changed
+326 -11

No files matched your search

+2 -1
View File
@@ -471,7 +471,8 @@ osTicket's API cannot close a ticket, so this is the one place in the app that *
- **Config fields:** the account's **API key** (panel.fragnet.net → your profile → *API Credentials* → create one; it starts with **`ptlc_`** and is shown only once; stored encrypted). It must be the account's own key — an *Application* key (`ptla_`) is for panel administrators and does not work, and the app says so. Optional: the **panel address** (`https://panel.fragnet.net` when left out — fill it in for another Pterodactyl panel, since Fragnet's is a fork of Pterodactyl and this speaks its *client* API), **warn when the newest backup is older than** *n* days (7; 0 turns backups off), **warn when disk or memory is fuller than** *n* % (90) and **servers whose backups are not judged** (names, comma-separated). A key may be limited to certain addresses in the panel; if so, allow the app's.
- **Required access:** `panel.fragnet.net` (HTTPS) reachable from the app. The panel limits the requests per minute (429 when over); a read is four requests for each game server, every five minutes.
- **What it does:** every **five minutes** each game server of the account (also those shared with it) is read — the game (the panel's *egg*, for example *Minecraft: Paper*), every IP address and port, SFTP, the plan's memory, disk and CPU limits and its room for backups and databases, whether it is running, what it uses, its backups, schedules and databases. **Infrastructure → Game servers** shows them; a row opens to show every address (click to copy), the backups, the schedules and a link to the server in the game panel.
- **Power:** operators can **start, stop, restart and kill** a server from the page (a confirmation first; kill says it loses unsaved progress). It sends exactly that signal to the panel and writes it to the audit log (`start_game_server` …). The page reads again a few seconds later. It is the only thing this integration ever sends but reads, and only a server the last read found can be signalled.
- **Power:** operators can **start, stop, restart and kill** a server from the page (a confirmation first; kill says it loses unsaved progress). It sends exactly that signal to the panel and writes it to the audit log (`start_game_server` …). The page reads again a few seconds later. Beside backups, it is the only thing this integration ever sends but reads, and only a server the last read found can be signalled.
- **Back up now:** operators can ask for a backup of a server whose plan has room for backups (*Back up* on its row, or *Back up now* beside its backups; a confirmation first, which says how many the plan allows and how many are made). It is `POST /api/client/servers/{id}/backups` with a name that says it was asked for here (`Homelab Manager — 2026-11-04 14:30 UTC`) and nothing else — no file is left out, nothing is locked. The panel makes it in the background; the page reads the account again after a few seconds and then every twenty seconds until the backup has finished. It is written to the audit log (`backup_game_server`, with the backup's id). **Refused here before the panel is asked:** a plan with no room for backups, a server that is suspended or being installed, one for which a backup is already being made (one that has been "being made" for more than two hours is taken to be lost and does not count), and the same server asked again within 30 seconds (HTTP 429). **Refused by the panel, and said in its words:** a server at the number of backups its plan allows (delete one in the panel first — the app never deletes a backup), the panel's own limit of a couple of backups in ten minutes (429), an account that may not make backups on a shared server (403 — it needs the *Backups → Create* permission) and a server that is busy (409). A refusal costs no wait before the next try.
- **Alerts** (source *Fragnet*; held back by maintenance on the integration): a server whose plan allows backups and whose **newest successful backup is older** than the limit (or has none, once the app has known it for that long; a backup that failed does not count, and the message says when the newest attempt failed); **disk** over the limit (critical from 98%); **memory** over the limit while it runs. A server that is **stopped** is not an alert. See [MONITORING.md](docs/MONITORING.md#game-servers-fragnet).
- If the panel cannot be read for 20 minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other. A part that cannot be read for one server (a sub-user without the *database* permission, say) is shown as *could not be listed*, never as none.
- `/metrics` has `homelab_fragnet_server_running`, `homelab_fragnet_disk_used_bytes`, `homelab_fragnet_disk_limit_bytes`, `homelab_fragnet_memory_used_bytes`, `homelab_fragnet_memory_limit_bytes` and `homelab_fragnet_newest_backup_timestamp_seconds`.
+1 -1
View File
@@ -552,7 +552,7 @@ The page also shows the users, the files and the app updates waiting. Whether it
**Hetzner Robot** (Infrastructure → Hetzner Robot). Hetzner's dedicated servers and storage boxes — Robot is the other Hetzner, next to the Cloud. Add a webservice user (Robot → Settings → Webservice and app settings) and its password and the app lists the account's dedicated servers (product, data centre, addresses, traffic plan, status, whether the rescue system is on, and what is paid until or when a cancelled one shuts down) and its storage boxes. It warns when **a server or storage box is cancelled and about to shut down** (within 30 days; critical within 7 — the data goes with it), when **a storage box is locked**, when **a rescue system has been left on** (two hours — the next boot is into it) and when **a server is still "in process"** a day after it was first seen so. Nothing is reset, ordered or cancelled. See INTEGRATIONS.md and docs/MONITORING.md.
**Game servers** (Infrastructure → Game servers, for Fragnet's game panel). Add an account's API key and the app lists its game servers: the game, the IP addresses and ports (click one to copy it), whether each is running, its memory and disk against the plan, its backups, schedules and databases. It warns when a server's **newest backup is late** (7 days by default, or none at all — a server can be left out by name) and when **disk or memory is nearly full** (90% by default); a server that is merely stopped is not an alert, since game servers are often stopped on purpose. Operators can **start, stop, restart and kill** a server from the page (asked first, written to the audit log); nothing else at Fragnet is changed. Fragnet's panel is a fork of Pterodactyl, so the same integration reads any Pterodactyl panel (give its address). See INTEGRATIONS.md and docs/MONITORING.md.
**Game servers** (Infrastructure → Game servers, for Fragnet's game panel). Add an account's API key and the app lists its game servers: the game, the IP addresses and ports (click one to copy it), whether each is running, its memory and disk against the plan, its backups, schedules and databases. It warns when a server's **newest backup is late** (7 days by default, or none at all — a server can be left out by name) and when **disk or memory is nearly full** (90% by default); a server that is merely stopped is not an alert, since game servers are often stopped on purpose. Operators can **start, stop, restart and kill** a server from the page, and **back it up now** (asked first, written to the audit log) — the panel makes the backup in the background and the page shows it as being made, then done; nothing else at Fragnet is changed. Fragnet's panel is a fork of Pterodactyl, so the same integration reads any Pterodactyl panel (give its address). See INTEGRATIONS.md and docs/MONITORING.md.
**Media managers** (Apps → Media managers). Add Sonarr, Radarr, Prowlarr, Lidarr and Readarr with their address and API key and the app shows, for each, what the application says is wrong with itself, its download queue (what is stuck or failed, and why), the disks it fills, how many wanted items have no file and, for Prowlarr, which indexers have failed. It warns when an application reports a **warning or error** (a download client that cannot be reached, indexers switched off), when **downloads have been stuck for two hours**, and when a **disk is nearly full**. Nothing is searched, grabbed or changed. See INTEGRATIONS.md and docs/MONITORING.md.
+1 -1
View File
@@ -159,7 +159,7 @@ even further, to admin only:
*Check now* needs operator.
- **Hetzner Robot** (Infrastructure → Hetzner Robot, for dedicated servers and storage boxes): everyone signed in sees the servers, their addresses, rescue state and what is paid until; adding one (a webservice user and its password) is an administrator's job, like any integration. Nothing on the page resets, orders or cancels anything.
- **Hetzner Cloud** (Infrastructure → Hetzner Cloud, and the card on a server's page): everyone signed in sees the servers, their addresses, traffic and cost estimate, volumes and snapshots; adding a project (its API token) is an administrator's job, like any integration. Nothing on the page changes anything at Hetzner.
- **Game servers** (Infrastructure → Game servers, Fragnet): everyone signed in sees the servers, their games, addresses, use, backups and schedules; **start, stop, restart and kill** need operator (each is written to the audit log); adding the account (its API key) is an administrator's job, like any integration.
- **Game servers** (Infrastructure → Game servers, Fragnet): everyone signed in sees the servers, their games, addresses, use, backups and schedules; **start, stop, restart and kill**, and **Back up now**, need operator (each is written to the audit log); adding the account (its API key) is an administrator's job, like any integration.
- **Speedtest** (Monitoring → Speedtest): everyone signed in sees the speeds, their history and what is wrong; adding one (its address, an API token, and what the line is sold at) is an administrator's job, like any integration. Nothing here starts a speed test.
- **Costs** (Records → Costs): everyone signed in sees what is paid for, the estimates read from Hetzner and the totals; adding, changing and removing an item is an administrator's. The **History** card (what it cost each month, and what changed) is seen by everyone signed in; it is kept by the app itself, so changing an item is what writes to it.
- **Nextcloud, NetBox and n8n** (Apps → Nextcloud, Network → NetBox, Automation → n8n): everyone signed in sees the status, the counts and what is wrong — for NetBox, the names and addresses of the servers that are not in it; for n8n, the names of the workflows; adding one (its address and a login, token or key) is an administrator's job, like any integration.
+1 -1
View File
@@ -337,7 +337,7 @@ Maintenance on the integration holds the alerts; a reading older than 20 minutes
## Game servers (Fragnet)
An integration of type *Fragnet game servers* ([INTEGRATIONS.md](../INTEGRATIONS.md#fragnet-game-servers)) is one account on Fragnet's game panel (a Pterodactyl fork), read every five minutes, and **Infrastructure → Game servers** shows its servers: the game, every address and port, whether it runs, memory and disk against the plan, the newest backup, and (opened) the backups, schedules and SFTP address. Operators can start, stop, restart and kill a server there.
An integration of type *Fragnet game servers* ([INTEGRATIONS.md](../INTEGRATIONS.md#fragnet-game-servers)) is one account on Fragnet's game panel (a Pterodactyl fork), read every five minutes, and **Infrastructure → Game servers** shows its servers: the game, every address and port, whether it runs, memory and disk against the plan, the newest backup, and (opened) the backups, schedules and SFTP address. Operators can start, stop, restart and kill a server there, and ask for a backup now (*Back up* on the row, or *Back up now* beside the server's backups): the panel makes it in the background, the page reads the account again every twenty seconds until it is done, and a successful one counts for the *backup late* alert like any other. A backup that is still "being made" does not count until it has finished.
| Alert | When | Severity |
|---|---|---|
+32 -2
View File
@@ -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 });
}
+54
View File
@@ -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);
+168
View File
@@ -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, []);
});
});
+2
View File
@@ -3674,6 +3674,8 @@ export const api = {
fragnet: {
list: () => request<{ accounts: FragnetAccount[] }>("/api/fragnet"),
power: (integrationId: number, serverId: string, signal: FragnetSignal) => request<void>(`/api/fragnet/${integrationId}/servers/${serverId}/power`, { method: "POST", body: JSON.stringify({ signal }) }),
/** Asks the panel to make a backup of one game server now. It is made in the background. */
backup: (integrationId: number, serverId: string) => request<{ name: string; uuid: string | null }>(`/api/fragnet/${integrationId}/servers/${serverId}/backup`, { method: "POST" }),
refresh: (integrationId: number) => request<{ status: { ok: boolean; error: string | null } }>(`/api/fragnet/${integrationId}/refresh`, { method: "POST" }),
},
hetzner: {
+65 -5
View File
@@ -80,8 +80,14 @@ const SIGNAL_TEXT: Record<FragnetSignal, { verb: string; done: string; confirm:
kill: { verb: "Kill", done: "kill", confirm: "Kill {name}? It is stopped at once, without saving — unsaved progress is lost. Use it only when Stop does not work.", danger: true },
};
function Details({ s, panelUrl, canAct, onSignal }: { s: Server; panelUrl: string; canAct: boolean; onSignal: (s: Server, signal: FragnetSignal) => void }) {
/** Whether a backup of this server is being made now (one the panel has begun and not finished, from the last two hours). */
function backupInProgress(s: Server): boolean {
return (s.backups ?? []).some((b) => b.completedAt === null && Date.now() - Date.parse(b.createdAt ?? "") < 2 * 60 * 60_000);
}
function Details({ s, panelUrl, canAct, onSignal, onBackup, busy }: { s: Server; panelUrl: string; canAct: boolean; onSignal: (s: Server, signal: FragnetSignal) => void; onBackup: (s: Server) => void; busy: boolean }) {
const backups = s.backups ?? [];
const making = backupInProgress(s);
return (
<div className="row g-3">
<div className="col-lg-4">
@@ -127,7 +133,14 @@ function Details({ s, panelUrl, canAct, onSignal }: { s: Server; panelUrl: strin
</div>
</div>
<div className="col-lg-4">
<h5>Backups{s.backupLimit ? ` (${backups.filter((b) => b.completedAt !== null).length} of ${s.backupLimit})` : ""}</h5>
<div className="d-flex align-items-center gap-2 mb-2">
<h5 className="mb-0">Backups{s.backupLimit ? ` (${backups.filter((b) => b.completedAt !== null).length} of ${s.backupLimit})` : ""}</h5>
{canAct && s.backupLimit ? (
<button className="btn btn-sm ms-auto" disabled={busy || making} onClick={() => onBackup(s)} title={making ? "One is already being made" : "Ask the panel to make a backup now"}>
{making ? "Being made…" : "Back up now"}
</button>
) : null}
</div>
{s.backups === null && <div className="text-secondary small">They could not be listed (the key may not be allowed to).</div>}
{s.backups !== null && backups.length === 0 && <div className="text-secondary small">{s.backupLimit ? "None has been made." : "This plan has none."}</div>}
<ul className="list-unstyled mb-0">
@@ -176,7 +189,7 @@ function Details({ s, panelUrl, canAct, onSignal }: { s: Server; panelUrl: strin
);
}
function ServerRow({ a, s, readAt, canAct, open, onToggle, onSignal, busy }: { a: FragnetAccount; s: Server; readAt: string; canAct: boolean; open: boolean; onToggle: () => void; onSignal: (s: Server, signal: FragnetSignal) => void; busy: boolean }) {
function ServerRow({ a, s, readAt, canAct, open, onToggle, onSignal, onBackup, busy }: { a: FragnetAccount; s: Server; readAt: string; canAct: boolean; open: boolean; onToggle: () => void; onSignal: (s: Server, signal: FragnetSignal) => void; onBackup: (s: Server) => void; busy: boolean }) {
const main = s.allocations[0];
const problems = a.problems.filter((p) => p.serverId === s.id);
const running = s.state === "running" || s.state === "starting" || s.state === "stopping";
@@ -246,6 +259,11 @@ function ServerRow({ a, s, readAt, canAct, open, onToggle, onSignal, busy }: { a
</button>
</>
)}
{s.backupLimit ? (
<button className="btn btn-sm" disabled={busy || backupInProgress(s)} onClick={() => onBackup(s)} title={backupInProgress(s) ? "One is already being made" : "Ask the panel to make a backup now"}>
{backupInProgress(s) ? "Backing up…" : "Back up"}
</button>
) : null}
</div>
)}
</td>
@@ -253,7 +271,7 @@ function ServerRow({ a, s, readAt, canAct, open, onToggle, onSignal, busy }: { a
{open && (
<tr>
<td colSpan={6} className="bg-body-tertiary">
<Details s={s} panelUrl={a.panelUrl} canAct={movable} onSignal={onSignal} />
<Details s={s} panelUrl={a.panelUrl} canAct={movable} onSignal={onSignal} onBackup={onBackup} busy={busy} />
</td>
</tr>
)}
@@ -291,6 +309,48 @@ function Card({ a, canAct, reload }: { a: FragnetAccount; canAct: boolean; reloa
}
}
// While a backup is being made, read the account again every twenty seconds, so the page shows when it is done (how long it takes depends on the game).
const making = !!s?.servers.some(backupInProgress);
useEffect(() => {
if (!canAct || !making) return;
const t = setInterval(() => {
void api.fragnet
.refresh(a.id)
.catch(() => undefined)
.finally(reload);
}, 20_000);
return () => clearInterval(t);
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [canAct, making, a.id]);
async function backUp(server: Server) {
const used = server.backups?.filter((b) => b.completedAt !== null).length ?? null;
const ok = await confirmDialog({
title: `Back up ${server.name}`,
message: `Ask the game panel to make a backup of ${server.name} now? It is made in the background while the game keeps running, and a large one can take a few minutes.${server.backupLimit ? ` It counts towards the ${server.backupLimit} the plan allows${used !== null ? ` (${used} made)` : ""} — if the plan is full the panel will refuse, and one has to be deleted in the panel first.` : ""}`,
confirmLabel: "Back up now",
});
if (!ok) return;
setBusy(true);
try {
await api.fragnet.backup(a.id, server.id);
toast.success(`Asked the panel to back up ${server.name}.`);
// It shows as "being made" once the panel has begun it; the effect above keeps reading until it is done.
setTimeout(() => {
void api.fragnet
.refresh(a.id)
.catch(() => undefined)
.finally(() => {
setBusy(false);
reload();
});
}, 4000);
} catch (err) {
setBusy(false);
toast.error(readableError(err));
}
}
return (
<div className="card mb-3">
<div className="card-header">
@@ -366,7 +426,7 @@ function Card({ a, canAct, reload }: { a: FragnetAccount; canAct: boolean; reloa
</thead>
<tbody>
{s.servers.map((x) => (
<ServerRow key={x.id} a={a} s={x} readAt={s.updatedAt} canAct={canAct} open={open === x.id} onToggle={() => setOpen(open === x.id ? null : x.id)} onSignal={(sv, sig) => void signal(sv, sig)} busy={busy} />
<ServerRow key={x.id} a={a} s={x} readAt={s.updatedAt} canAct={canAct} open={open === x.id} onToggle={() => setOpen(open === x.id ? null : x.id)} onSignal={(sv, sig) => void signal(sv, sig)} onBackup={(sv) => void backUp(sv)} busy={busy} />
))}
{s.servers.length === 0 && (
<tr>