Add qBittorrent and SABnzbd: a Download clients page with stuck, disconnected, paused and full-disk alerts

Each client is read every five minutes (read-only; qBittorrent's sign-in is the only POST): speed, queue and item states, network connection or paused queue, free space, SABnzbd's failures and warnings. Shared adapter, sync service, download_state table, /api/downloads, metrics and docs.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-11-04 23:13:03 +01:00
1 parent c7775e5dd9
commit 7618bf0f0a
32 files changed
+10715 -12

No files matched your search

+584
View File
@@ -0,0 +1,584 @@
/**
* qBittorrent and SABnzbd: reading what their APIs say, what is stored, what is wrong (stuck downloads, no connection, a queue left paused or getting nothing, a disk nearly full), the health
* pass, the alerts, the page's data and /metrics.
*
* Run with: npm test --workspace server
*/
import { test, describe, before, after } from "node:test";
import assert from "node:assert/strict";
import { createServer as createHttpServer, type IncomingMessage, 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-downloads-"));
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.HEALTH_STARTUP_GRACE_MS = "0";
const express = (await import("express")).default;
const { db } = await import("../src/db/client.js");
const { users, integrations, downloadState } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const adapter = await import("../src/integrations/downloads/adapter.js");
const dl = await import("../src/services/downloadsSync.js");
const { evaluateHealth, collectSnapshot } = await import("../src/services/healthMonitor.js");
const { subjectOfConditionKey } = await import("../src/services/maintenance.js");
const { getAlerts, invalidateAlertsCache } = await import("../src/services/alerts.js");
const { downloadsRouter } = await import("../src/routes/downloads.js");
const { buildMetrics } = await import("../src/services/metrics.js");
const { setInternalFlag } = await import("../src/services/settingsStore.js");
const { INTEGRATION_FIELDS, validateIntegrationConfig, splitIntegrationConfig } = await import("../src/integrations/fieldSchemas.js");
const { createIntegrationAdapter } = await import("../src/integrations/registry.js");
const { eq } = await import("drizzle-orm");
await runMigrations();
const MIN = 60_000;
const HOUR = 60 * MIN;
const DAY = 24 * HOUR;
const GB = 1024 ** 3;
const iso = (ms: number) => new Date(ms).toISOString();
type Item = import("../src/integrations/downloads/adapter.js").DownloadItem;
type Read = import("../src/integrations/downloads/adapter.js").DownloadRead;
const item = (extra: Partial<Item> = {}): Item => ({ id: "h1", name: "Some.Download", state: "downloading", rawState: "downloading", progress: 0.5, size: 1000, left: 500, speed: 100, eta: 60, addedAt: iso(Date.now() - HOUR), activityAt: iso(Date.now() - MIN), category: "tv", message: null, ...extra });
/** A read built from its items, the way the adapter builds one. */
const read = (items: Item[] = [item()], extra: Partial<Read> = {}): Read => ({
version: "4.6.2",
speedDown: 1000,
speedUp: 10,
paused: false,
connection: "connected",
...adapter.summarise(items),
failed: null,
disks: [{ label: "Download folder", free: 500 * GB, total: null }],
warnings: null,
...extra,
});
describe("what the APIs say", () => {
test("a torrent: its state in the shared words, progress, size, speed, 'never' as no ETA, the times, the category", () => {
const t = adapter.parseTorrent({ hash: "abc", name: "Linux ISO", state: "stalledDL", progress: 0.25, size: 1000, amount_left: 750, dlspeed: 0, eta: 8640000, added_on: 1780000000, last_activity: 1780000500, category: "iso" })!;
assert.deepEqual([t.id, t.name, t.state, t.rawState, t.progress, t.size, t.left, t.speed, t.eta, t.category], ["abc", "Linux ISO", "stalled", "stalledDL", 0.25, 1000, 750, 0, null, "iso"]);
assert.deepEqual([t.addedAt, t.activityAt], [new Date(1780000000 * 1000).toISOString(), new Date(1780000500 * 1000).toISOString()]);
assert.equal(adapter.parseTorrent({ hash: "a", state: "downloading", eta: 90 })!.eta, 90);
assert.equal(adapter.parseTorrent({ hash: "a", state: "downloading", progress: 1.4 })!.progress, 1);
assert.equal(adapter.parseTorrent({ hash: "a", last_activity: 0 })!.activityAt, null, "0 is never");
assert.equal(adapter.parseTorrent({ name: "no hash" }), null);
});
test("every state qBittorrent has is placed; one it does not know is 'other'", () => {
const state = (s: string) => adapter.parseTorrent({ hash: "a", state: s })!.state;
const expected: Record<string, string> = {
error: "error", missingFiles: "error", downloading: "downloading", forcedDL: "downloading", metaDL: "downloading", stalledDL: "stalled", queuedDL: "queued", pausedDL: "paused", stoppedDL: "paused",
checkingDL: "processing", checkingUP: "processing", checkingResumeData: "processing", allocating: "processing", moving: "processing", uploading: "seeding", forcedUP: "seeding", stalledUP: "seeding", queuedUP: "seeding", pausedUP: "completed", stoppedUP: "completed", somethingNew: "other",
};
for (const [raw, shared] of Object.entries(expected)) assert.equal(state(raw), shared, raw);
});
test("maindata: its torrents are keyed by hash, and the numbers about itself are read the same from server_state or transfer/info", () => {
const items = adapter.parseMaindataTorrents({ torrents: { h1: { name: "A", state: "downloading" }, h2: { name: "B", state: "uploading" } } });
assert.deepEqual(items.map((i) => [i.id, i.name, i.state]), [["h1", "A", "downloading"], ["h2", "B", "seeding"]]);
assert.deepEqual(adapter.parseMaindataTorrents({}), []);
assert.deepEqual(adapter.parseTransfer({ dl_info_speed: 5, up_info_speed: 2, connection_status: "Firewalled", free_space_on_disk: 42 }), { speedDown: 5, speedUp: 2, connection: "firewalled", free: 42 });
assert.deepEqual(adapter.parseTransfer({ connection_status: "nonsense", free_space_on_disk: -1 }), { speedDown: null, speedUp: null, connection: null, free: null });
});
test("the summary counts everything, and lists only what is not finished and idle — the ones with something to say first", () => {
const all = [item({ id: "1", state: "seeding", name: "s" }), item({ id: "2", state: "downloading", name: "d" }), item({ id: "3", state: "error", name: "e" }), item({ id: "4", state: "completed", name: "c" }), item({ id: "5", state: "stalled", name: "t" }), item({ id: "6", state: "queued", name: "q" })];
const s = adapter.summarise(all);
assert.equal(s.total, 6);
assert.deepEqual([s.counts.seeding, s.counts.completed, s.counts.error, s.counts.downloading, s.counts.stalled, s.counts.queued], [1, 1, 1, 1, 1, 1]);
assert.deepEqual(s.items.map((i) => i.name), ["e", "t", "d", "q"]);
assert.equal(adapter.summarise(Array.from({ length: 150 }, (_, n) => item({ id: String(n), name: `n${n}` }))).items.length, adapter.MAX_ITEMS);
});
test("a SABnzbd slot: its figures are text in megabytes; '*' is no category; 'propagating' waits; an estimate of 0 is none", () => {
const s = adapter.parseSabSlot({ nzo_id: "SABnzbd_nzo_1", filename: "Show.S01E01", status: "Downloading", percentage: "40", mb: "1000.0", mbleft: "600.0", cat: "*", timeleft: "0:10:00" })!;
assert.deepEqual([s.id, s.name, s.state, s.progress, s.size, s.left, s.category, s.eta], ["SABnzbd_nzo_1", "Show.S01E01", "downloading", 0.4, 1000 * 1024 ** 2, 600 * 1024 ** 2, null, 600]);
assert.equal(adapter.parseSabSlot({ nzo_id: "x", status: "Propagating" })!.state, "waiting");
assert.equal(adapter.parseSabSlot({ nzo_id: "x", status: "Verifying" })!.state, "processing");
assert.equal(adapter.parseSabSlot({ nzo_id: "x", status: "Paused", cat: "tv" })!.category, "tv");
assert.equal(adapter.parseSabSlot({ nzo_id: "x", mb: "100", mbleft: "25" })!.progress, 0.75, "without a percentage, from what is left");
assert.equal(adapter.parseSabSlot({ filename: "no id" }), null);
assert.deepEqual([adapter.parseTimeLeft("0:00:00"), adapter.parseTimeLeft("1:02:03"), adapter.parseTimeLeft("1:00:00:10"), adapter.parseTimeLeft("soon"), adapter.parseTimeLeft(null)], [null, 3723, 86410, null, null]);
});
test("the SABnzbd queue: version, paused or not, speed in bytes, the slots, and the two folders' disks — the same disk once", () => {
const q = adapter.parseSabQueue({ queue: { version: "4.3.2", paused: false, status: "Downloading", kbpersec: "1500.5", diskspace1: "100.0", diskspacetotal1: "1000.0", diskspace2: "250.0", diskspacetotal2: "500.0", slots: [{ nzo_id: "a", filename: "A", status: "Queued" }, { filename: "no id" }] } });
assert.deepEqual([q.version, q.paused, q.speedDown, q.items.map((i) => i.id)], ["4.3.2", false, Math.round(1500.5 * 1024), ["a"]]);
assert.deepEqual(q.disks, [{ label: "Incomplete folder", free: 100 * GB, total: 1000 * GB }, { label: "Complete folder", free: 250 * GB, total: 500 * GB }]);
const same = adapter.parseSabQueue({ queue: { diskspace1: "100", diskspacetotal1: "1000", diskspace2: "100", diskspacetotal2: "1000", slots: [] } });
assert.deepEqual(same.disks?.map((d) => d.label), ["Incomplete folder"]);
assert.equal(adapter.parseSabQueue({ queue: { paused: true } }).paused, true);
assert.equal(adapter.parseSabQueue({ queue: { status: "Paused" } }).paused, true);
assert.deepEqual([adapter.parseSabQueue({}).items, adapter.parseSabQueue({}).disks, adapter.parseSabQueue({}).speedDown], [[], null, null]);
});
test("the SABnzbd history: only what failed, the newest first, with why; its warnings are lines or objects", () => {
const f = adapter.parseSabFailed({ history: { slots: [{ nzo_id: "a", name: "Old", status: "Failed", fail_message: "Aborted, cannot be completed", completed: 1780000000, bytes: 5, category: "*" }, { nzo_id: "b", name: "Fine", status: "Completed", completed: 1780000900 }, { nzo_id: "c", name: "New", status: "Failed", completed: 1780000800 }] } });
assert.deepEqual(f.map((x) => [x.name, x.state, x.message, x.category]), [["New", "failed", null, null], ["Old", "failed", "Aborted, cannot be completed", null]]);
const w = adapter.parseSabWarnings({ warnings: ["first", { text: "second line", type: "WARNING" }, 5, { text: "third" }] });
assert.deepEqual([w.count, w.recent], [3, ["third", "second line", "first"]]);
assert.deepEqual(adapter.parseSabWarnings(null), { count: 0, recent: [] });
});
describe("qBittorrent, answering", () => {
let fake: Server;
let url = "";
let password = "secret";
let banned = false;
let maindata = true;
const seen: { method: string | undefined; path: string; cookie: string | undefined; referer: string | undefined; body: string }[] = [];
const body = (req: IncomingMessage) =>
new Promise<string>((resolve) => {
let text = "";
req.on("data", (c) => (text += c));
req.on("end", () => resolve(text));
});
before(async () => {
fake = createHttpServer(async (req, res) => {
const b = await body(req);
const u = new URL(req.url ?? "", "http://x");
seen.push({ method: req.method, path: u.pathname + u.search, cookie: req.headers.cookie, referer: req.headers.referer as string | undefined, body: b });
const text = (code: number, t: string, headers: Record<string, string> = {}) => {
res.writeHead(code, { "content-type": "text/plain", ...headers });
res.end(t);
};
const json = (code: number, v: unknown) => {
res.writeHead(code, { "content-type": "application/json" });
res.end(JSON.stringify(v));
};
if (u.pathname === "/api/v2/auth/login") {
if (banned) return text(403, "Your IP address has been banned after too many failed authentication attempts.");
const form = new URLSearchParams(b);
return form.get("username") === "admin" && form.get("password") === password ? text(200, "Ok.", { "set-cookie": "SID=abc123; HttpOnly; path=/" }) : text(200, "Fails.");
}
if (u.pathname === "/api/v2/auth/logout") return text(200, "");
if (req.headers.cookie !== "SID=abc123") return text(403, "Forbidden");
if (u.pathname === "/api/v2/app/version") return text(200, "v4.6.2");
if (u.pathname === "/api/v2/sync/maindata")
return maindata
? json(200, {
rid: 1,
full_update: true,
torrents: {
h1: { name: "Linux ISO", state: "downloading", progress: 0.5, size: 2000, amount_left: 1000, dlspeed: 1000, eta: 600, added_on: 1780000000, last_activity: 1780000500 },
h2: { name: "Stuck one", state: "stalledDL", progress: 0.1, size: 100, amount_left: 90, last_activity: 1700000000 },
h3: { name: "Seeded", state: "uploading", progress: 1, size: 50 },
h4: { name: "Broken", state: "missingFiles", progress: 0.3, size: 70 },
},
server_state: { free_space_on_disk: 50 * GB, dl_info_speed: 5000, up_info_speed: 200, connection_status: "connected" },
})
: text(404, "");
if (u.pathname === "/api/v2/torrents/info") return json(200, [{ hash: "z1", name: "Fallback", state: "downloading", progress: 0.2, size: 10 }]);
if (u.pathname === "/api/v2/transfer/info") return json(200, { dl_info_speed: 7, up_info_speed: 3, connection_status: "firewalled" });
text(404, "");
});
await new Promise<void>((resolve) => fake.listen(0, "127.0.0.1", resolve));
url = `http://127.0.0.1:${(fake.address() as AddressInfo).port}`;
});
after(() => fake.close());
test("it signs in with the form, sends the cookie and its own address as the referer, reads everything, and signs out", async () => {
seen.length = 0;
const r = await adapter.createDownloadAdapter("qbittorrent", { url, username: "admin", password: "secret" }).read();
assert.deepEqual([r.version, r.speedDown, r.speedUp, r.connection, r.total, r.paused], ["4.6.2", 5000, 200, "connected", 4, false]);
assert.deepEqual([r.counts.downloading, r.counts.stalled, r.counts.seeding, r.counts.error], [1, 1, 1, 1]);
assert.deepEqual(r.items.map((i) => i.name), ["Broken", "Stuck one", "Linux ISO"], "the seeding one is not listed");
assert.deepEqual(r.disks, [{ label: "Download folder", free: 50 * GB, total: null }]);
assert.equal(r.failed, null);
const login = seen[0];
assert.deepEqual([login.method, login.path, login.referer], ["POST", "/api/v2/auth/login", `${url}/`]);
assert.equal(new URLSearchParams(login.body).get("password"), "secret");
assert.ok(seen.slice(1, -1).every((s) => s.method === "GET" && s.cookie === "SID=abc123"), "everything after is a GET with the cookie");
assert.equal(seen[seen.length - 1].path, "/api/v2/auth/logout");
});
test("without a user name it does not sign in at all (an address it lets in), and a refusal then says what to do", async () => {
seen.length = 0;
await assert.rejects(() => adapter.createDownloadAdapter("qbittorrent", { url }).read(), /did not let this address in \(HTTP 403\).*user name and password/);
assert.ok(!seen.some((s) => s.path.includes("auth/login")));
});
test("when maindata is not answered, the torrents are asked for on their own, and the numbers come from transfer/info", async () => {
maindata = false;
const r = await adapter.createDownloadAdapter("qbittorrent", { url, username: "admin", password: "secret" }).read();
assert.deepEqual([r.items.map((i) => i.name), r.speedDown, r.connection, r.disks], [["Fallback"], 7, "firewalled", null]);
maindata = true;
});
test("a wrong password, a ban, and an address that is not qBittorrent are said — and a wrong password is said before anything is read", async () => {
seen.length = 0;
const bad = adapter.createDownloadAdapter("qbittorrent", { url, username: "admin", password: "nope" });
assert.match((await bad.ping()).error ?? "", /did not accept the user name and password/);
assert.equal(seen.length, 1);
banned = true;
assert.match((await bad.ping()).error ?? "", /refused the sign-in \(HTTP 403\).*bans an address/);
banned = false;
assert.equal((await adapter.createDownloadAdapter("qbittorrent", { url, username: "admin", password: "secret" }).ping()).ok, true);
assert.equal((await adapter.createDownloadAdapter("qbittorrent", { url: "http://127.0.0.1:1", username: "a", password: "b" }).ping()).ok, false);
});
});
describe("SABnzbd, answering", () => {
let fake: Server;
let url = "";
let historyStatus = 200;
const seen: { path: string; key: string | null; mode: string | null }[] = [];
before(async () => {
fake = createHttpServer((req, res) => {
const u = new URL(req.url ?? "", "http://x");
seen.push({ path: u.pathname, key: u.searchParams.get("apikey"), mode: u.searchParams.get("mode") });
const send = (code: number, v: unknown) => {
res.writeHead(code, { "content-type": "application/json" });
res.end(JSON.stringify(v));
};
if (u.pathname !== "/api") return send(404, {});
if (u.searchParams.get("apikey") !== "good") return send(200, { status: false, error: "API Key Incorrect" });
const mode = u.searchParams.get("mode");
if (mode === "queue") return send(200, { queue: { version: "4.3.2", paused: true, status: "Paused", kbpersec: "0.00", diskspace1: "80.0", diskspacetotal1: "1000.0", diskspace2: "80.0", diskspacetotal2: "1000.0", slots: [{ nzo_id: "a", filename: "Waiting.One", status: "Queued", mb: "100", mbleft: "100", percentage: "0" }] } });
if (mode === "history") return historyStatus === 200 ? send(200, { history: { slots: [{ nzo_id: "f", name: "Broken.Release", status: "Failed", fail_message: "Unpacking failed", completed: Math.floor(Date.now() / 1000) - 600 }] } }) : send(historyStatus, {});
if (mode === "warnings") return send(200, { warnings: ["Failed to connect to news.example.com"] });
send(200, {});
});
await new Promise<void>((resolve) => fake.listen(0, "127.0.0.1", resolve));
url = `http://127.0.0.1:${(fake.address() as AddressInfo).port}`;
});
after(() => fake.close());
test("the queue, what failed, the warnings and the disk — each read with the key, and nothing is asked that changes anything", async () => {
seen.length = 0;
const r = await adapter.createDownloadAdapter("sabnzbd", { url, apiKey: "good" }).read();
assert.deepEqual([r.version, r.paused, r.speedDown, r.speedUp, r.connection, r.total, r.items.map((i) => i.name)], ["4.3.2", true, 0, null, null, 1, ["Waiting.One"]]);
assert.deepEqual([r.failed?.map((f) => [f.name, f.message]), r.warnings?.count, r.disks?.length], [[["Broken.Release", "Unpacking failed"]], 1, 1]);
assert.deepEqual(seen.map((s) => s.mode).sort(), ["history", "queue", "warnings"]);
assert.ok(seen.every((s) => s.key === "good"));
});
test("a history that cannot be read is null, not empty; the queue is what must work", async () => {
historyStatus = 500;
const r = await adapter.createDownloadAdapter("sabnzbd", { url, apiKey: "good" }).read();
assert.deepEqual([r.failed, r.total], [null, 1]);
historyStatus = 200;
});
test("a key it refuses (answered with 200 and a status of false) and an address that is not SABnzbd are said", async () => {
const bad = await adapter.createDownloadAdapter("sabnzbd", { url, apiKey: "wrong" }).ping();
assert.equal(bad.ok, false);
assert.match(bad.error ?? "", /SABnzbd did not accept the API key.*API Key Incorrect.*not the NZB key/);
assert.equal((await adapter.createDownloadAdapter("sabnzbd", { url, apiKey: "good" }).ping()).ok, true);
await assert.rejects(() => adapter.createDownloadAdapter("sabnzbd", { url: `${url}/nowhere`, apiKey: "good" }).read(), /no API at this address/);
assert.equal((await adapter.createDownloadAdapter("sabnzbd", { url: "http://127.0.0.1:1", apiKey: "k" }).ping()).ok, false);
});
});
});
describe("adding one", () => {
test("qBittorrent needs only its address (a user name and password are for one that asks for them, and the password is kept secret); SABnzbd needs its API key", () => {
assert.deepEqual(validateIntegrationConfig("qbittorrent", { url: "http://qb:8080" }), []);
assert.deepEqual(validateIntegrationConfig("qbittorrent", {}), ["url"]);
assert.deepEqual(validateIntegrationConfig("sabnzbd", { url: "http://sab:8080" }), ["apiKey"]);
assert.deepEqual(validateIntegrationConfig("sabnzbd", { url: "http://sab:8080", apiKey: "k" }), []);
const { secretFields, nonSecretFields } = splitIntegrationConfig("qbittorrent", { url: "http://qb:8080", username: "admin", password: "pw", insecure: true });
assert.deepEqual(secretFields, { password: "pw" });
assert.deepEqual(nonSecretFields, { url: "http://qb:8080", username: "admin", insecure: true });
assert.equal(INTEGRATION_FIELDS.sabnzbd!.find((f) => f.key === "apiKey")!.secret, true);
});
test("both kinds get the shared adapter, from the registry, with its two calls", () => {
for (const kind of adapter.DOWNLOAD_KINDS) {
const a = createIntegrationAdapter(kind, { url: "http://x" } as never) as unknown as Record<string, unknown>;
assert.deepEqual([typeof a.ping, typeof a.read], ["function", "function"], kind);
}
assert.deepEqual(adapter.DOWNLOAD_KINDS, ["qbittorrent", "sabnzbd"]);
});
});
describe("what is wrong", () => {
const NOW = Date.parse("2026-06-10T12:00:00Z");
/** A stored state with nothing wrong, to change what a test is about. */
const state = (extra: Partial<import("../src/services/downloadsSync.js").StoredDownload> = {}): import("../src/services/downloadsSync.js").StoredDownload => ({
...read([item({ activityAt: iso(NOW - MIN) })], {}),
since: { pausedSince: null, disconnectedSince: null, idleSince: null },
updatedAt: iso(NOW),
...extra,
});
const keys = (list: ReturnType<typeof dl.downloadProblems>) => list.map((p) => `${p.key}=${p.severity}`);
const stalled = (extra: Partial<Item> = {}) => item({ id: "s", name: "Stalled.One", state: "stalled", rawState: "stalledDL", speed: 0, activityAt: iso(NOW - 2 * DAY), ...extra });
test("a client that is well says nothing", () => {
assert.deepEqual(dl.downloadProblems("qbittorrent", 1, "Torrents", state(), NOW), []);
assert.deepEqual(dl.downloadProblems("sabnzbd", 2, "Usenet", state({ speedDown: 0, counts: { ...adapter.emptyCounts() }, total: 0, items: [] }), NOW), []);
});
describe("stuck downloads", () => {
test("an error is stuck at once; stalled is stuck after a day without activity, not before; a download that moves is not", () => {
assert.equal(dl.isStuck(item({ state: "error", rawState: "error" }), NOW), true);
assert.equal(dl.isStuck(stalled(), NOW), true);
assert.equal(dl.isStuck(stalled({ activityAt: iso(NOW - 5 * HOUR) }), NOW), false);
assert.equal(dl.isStuck(item({ state: "downloading", activityAt: iso(NOW - 9 * DAY) }), NOW), false);
assert.equal(dl.isStuck(stalled({ activityAt: null, addedAt: iso(NOW - 3 * DAY) }), NOW), true, "added long ago, never any activity");
assert.equal(dl.isStuck(stalled({ activityAt: null, addedAt: null }), NOW), false, "one with no time cannot be called old");
});
test("one alert for the lot: how many, the first three by name, and why for the worst — an error first", () => {
const items = [stalled({ id: "1", name: "A" }), item({ id: "2", name: "B", state: "error", rawState: "missingFiles" }), stalled({ id: "3", name: "C", activityAt: iso(NOW - 5 * DAY) }), stalled({ id: "4", name: "D" }), item({ id: "5", name: "fine" })];
const p = dl.downloadProblems("qbittorrent", 1, "Torrents", state({ items, total: 5, counts: { ...adapter.emptyCounts(), stalled: 3, error: 1, downloading: 1 } }), NOW);
assert.deepEqual(keys(p), ["qbittorrent-stuck:1=warning"]);
assert.equal(p[0].message, "Torrents: 4 downloads are stuck — B; C; A; and 1 more (its files are missing)");
const one = dl.downloadProblems("qbittorrent", 1, "Torrents", state({ items: [stalled({ name: "A" })] }), NOW);
assert.equal(one[0].message, "Torrents: 1 download is stuck — A (nothing has moved for 2 days)");
});
});
describe("no connection", () => {
test("disconnected for a quarter of an hour, with torrents, is raised; less is not; firewalled never is", () => {
const at = (ago: number) => state({ connection: "disconnected", since: { pausedSince: null, disconnectedSince: iso(NOW - ago), idleSince: null } });
assert.deepEqual(keys(dl.downloadProblems("qbittorrent", 1, "T", at(20 * MIN), NOW)), ["qbittorrent-connection:1=warning"]);
assert.match(dl.downloadProblems("qbittorrent", 1, "T", at(2 * HOUR), NOW)[0].message, /^T: qBittorrent has had no connection to the network for 2 hours — if it is bound to a VPN/);
assert.deepEqual(dl.downloadProblems("qbittorrent", 1, "T", at(5 * MIN), NOW), []);
assert.deepEqual(dl.downloadProblems("qbittorrent", 1, "T", { ...at(2 * HOUR), connection: "firewalled" }, NOW), []);
});
});
describe("a queue left paused, and one getting nothing", () => {
const sabCounts = { ...adapter.emptyCounts(), queued: 2 };
test("paused for six hours with downloads waiting is raised; paused with nothing waiting, or for less, is not", () => {
const paused = (ago: number, total = 2) => state({ paused: true, speedDown: 0, total, counts: total ? sabCounts : adapter.emptyCounts(), since: { pausedSince: iso(NOW - ago), disconnectedSince: null, idleSince: null } });
const p = dl.downloadProblems("sabnzbd", 2, "Usenet", paused(7 * HOUR), NOW);
assert.deepEqual(keys(p), ["sabnzbd-paused:2=warning"]);
assert.equal(p[0].message, "Usenet: SABnzbd has been paused for 7 hours with 2 downloads waiting");
assert.deepEqual(dl.downloadProblems("sabnzbd", 2, "Usenet", paused(2 * HOUR), NOW), []);
assert.deepEqual(dl.downloadProblems("sabnzbd", 2, "Usenet", paused(9 * HOUR, 0), NOW), []);
});
test("work waiting and nothing coming in for an hour is raised, and says how much waits; a paused queue is the other alert's business", () => {
const idle = (ago: number, extra: Partial<import("../src/services/downloadsSync.js").StoredDownload> = {}) => state({ speedDown: 0, total: 2, counts: sabCounts, since: { pausedSince: null, disconnectedSince: null, idleSince: iso(NOW - ago) }, ...extra });
const p = dl.downloadProblems("sabnzbd", 2, "Usenet", idle(3 * HOUR), NOW);
assert.deepEqual(keys(p), ["sabnzbd-stalled:2=warning"]);
assert.equal(p[0].message, "Usenet: SABnzbd has downloaded nothing for 3 hours although 2 downloads are waiting — can it reach its news server?");
assert.deepEqual(dl.downloadProblems("sabnzbd", 2, "Usenet", idle(20 * MIN), NOW), []);
assert.deepEqual(dl.downloadProblems("sabnzbd", 2, "Usenet", idle(3 * HOUR, { paused: true }), NOW).filter((x) => x.key.includes("stalled")), []);
});
test("what is seen between reads: the clock starts at the first read that shows it, is kept while it goes on, and is dropped when it is over", () => {
const t0 = new Date(NOW);
const t1 = new Date(NOW + 10 * MIN);
const waiting = { total: 2, counts: sabCounts };
const first = dl.carrySince({ paused: false, connection: null, speedDown: 0, ...waiting }, null, t0);
assert.deepEqual(first, { pausedSince: null, disconnectedSince: null, idleSince: t0.toISOString() });
assert.equal(dl.carrySince({ paused: false, connection: null, speedDown: 0, ...waiting }, first, t1).idleSince, t0.toISOString());
assert.equal(dl.carrySince({ paused: false, connection: null, speedDown: 500, ...waiting }, first, t1).idleSince, null);
assert.equal(dl.carrySince({ paused: true, connection: null, speedDown: 0, ...waiting }, first, t1).pausedSince, t1.toISOString());
assert.equal(dl.carrySince({ paused: false, connection: "disconnected", speedDown: 0, total: 0, counts: adapter.emptyCounts() }, null, t0).disconnectedSince, null, "nothing loaded, nothing to be cut off from");
assert.equal(dl.carrySince({ paused: false, connection: "disconnected", speedDown: 0, total: 3, counts: adapter.emptyCounts() }, null, t0).disconnectedSince, t0.toISOString());
});
});
describe("disks", () => {
test("where the size is said: under 10% free is a warning, under 5% critical, a tiny disk is not judged", () => {
const d = (free: number, total = 1000) => state({ disks: [{ label: "Complete folder", free: free * GB, total: total * GB }] });
assert.deepEqual(dl.downloadProblems("sabnzbd", 2, "U", d(150), NOW), []);
const warn = dl.downloadProblems("sabnzbd", 2, "U", d(80), NOW);
assert.deepEqual(keys(warn), ["sabnzbd-disk:2:complete-folder=warning"]);
assert.equal(warn[0].message, "U: the complete folder of SABnzbd has 80.0 GB free of 1000 GB (8%)");
assert.deepEqual(keys(dl.downloadProblems("sabnzbd", 2, "U", d(30), NOW)), ["sabnzbd-disk:2:complete-folder=critical"]);
assert.deepEqual(dl.downloadProblems("sabnzbd", 2, "U", state({ disks: [{ label: "Tmp", free: 0, total: GB }] }), NOW), []);
});
test("where it is not (qBittorrent says only what is free): under 20 GB is a warning, under 5 GB critical; a disk that was not read says nothing", () => {
const d = (free: number) => state({ disks: [{ label: "Download folder", free: free * GB, total: null }] });
assert.deepEqual(dl.downloadProblems("qbittorrent", 1, "T", d(200), NOW), []);
assert.equal(dl.downloadProblems("qbittorrent", 1, "T", d(12), NOW)[0].message, "T: the download folder of qBittorrent has only 12.0 GB free");
assert.deepEqual(keys(dl.downloadProblems("qbittorrent", 1, "T", d(3), NOW)), ["qbittorrent-disk:1:download-folder=critical"]);
assert.deepEqual(dl.downloadProblems("qbittorrent", 1, "T", state({ disks: null }), NOW), []);
});
});
test("what failed in the last day is news; older is not", () => {
const failed = [item({ id: "n", state: "failed", activityAt: iso(NOW - 2 * HOUR) }), item({ id: "o", state: "failed", activityAt: iso(NOW - 3 * DAY) }), item({ id: "x", state: "failed", activityAt: null })];
assert.deepEqual(dl.recentFailed(failed, NOW).map((f) => f.id), ["n"]);
assert.deepEqual(dl.recentFailed(null, NOW), []);
});
});
describe("what is stored", () => {
let id = 0;
before(async () => {
id = (await db.insert(integrations).values({ type: "sabnzbd", name: "Usenet", baseUrl: "http://sab", config: JSON.stringify({}) }).returning({ id: integrations.id }))[0].id;
});
const row = async () => (await db.select().from(downloadState).where(eq(downloadState.integrationId, id)))[0];
after(async () => {
await dl.forgetDownload(id);
await db.delete(integrations).where(eq(integrations.id, id));
});
test("the state is replaced at each read; a part that could not be read is stored as null", async () => {
await dl.storeRead(id, read([item()], { disks: null, failed: null }), new Date());
let s = dl.storedOf(await row());
assert.deepEqual([s.disks, s.failed, s.total, s.items.length, s.counts.downloading], [null, null, 1, 1, 1]);
await dl.storeRead(id, read([item(), item({ id: "h2", state: "queued" })], { failed: [item({ id: "f", state: "failed" })] }), new Date());
s = dl.storedOf(await row());
assert.deepEqual([s.total, s.counts.queued, s.failed?.length], [2, 1, 1]);
});
test("since when it has been so is carried from read to read, and dropped when it is over", async () => {
const t0 = new Date(Date.now() - 8 * HOUR);
const paused = (extra: Partial<Read> = {}) => read([item({ state: "queued" })], { paused: true, speedDown: 0, ...extra });
await dl.storeRead(id, paused(), t0);
await dl.storeRead(id, paused(), new Date());
assert.equal(dl.storedOf(await row()).since.pausedSince, t0.toISOString());
await dl.storeRead(id, read(), new Date());
assert.equal(dl.storedOf(await row()).since.pausedSince, null);
});
test("a read that failed is said, and what was stored is left alone", async () => {
const ok = await dl.syncDownload(id, new Date(), async () => read([item()], { version: "kept" }));
assert.equal(ok.ok, true);
const failed = await dl.syncDownload(id, new Date(), async () => {
throw new Error("connection refused");
});
assert.deepEqual([failed.ok, failed.error], [false, "connection refused"]);
assert.equal(failed.at, ok.at);
assert.equal(dl.storedOf(await row()).version, "kept");
assert.equal(dl.isDownloadFresh((await dl.downloadSyncStatuses())[id], Date.now()), false);
});
test("the kind is what the read is asked for, and an integration of another type is not read", async () => {
const asked: string[] = [];
await dl.syncDownload(id, new Date(), async (kind) => {
asked.push(kind);
return read();
});
assert.deepEqual(asked, ["sabnzbd"]);
const other = (await db.insert(integrations).values({ type: "gitea", name: "G", baseUrl: "http://g", config: JSON.stringify({}) }).returning({ id: integrations.id }))[0].id;
const status = await dl.syncDownload(other, new Date(), async () => read());
assert.deepEqual([status.ok, status.error], [false, "not a qBittorrent or SABnzbd integration"]);
await dl.forgetDownload(other);
await db.delete(integrations).where(eq(integrations.id, other));
});
});
describe("the health pass, the page and /metrics", () => {
let qId = 0;
let sId = 0;
let app: Server;
let base = "";
const fresh = () => setInternalFlag("downloadsSync", JSON.stringify({ [qId]: { at: new Date().toISOString(), ok: true, error: null }, [sId]: { at: new Date().toISOString(), ok: true, error: null } }));
const stale = () => setInternalFlag("downloadsSync", JSON.stringify({ [qId]: { at: new Date(Date.now() - 30 * MIN).toISOString(), ok: true, error: null }, [sId]: { at: new Date().toISOString(), ok: true, error: null } }));
before(async () => {
await db.insert(users).values([{ oidcSub: "viewer", name: "Vic", role: "viewer" }]);
const mk = async (type: "qbittorrent" | "sabnzbd", name: string) => (await db.insert(integrations).values({ type, name, baseUrl: `http://${name}`, config: JSON.stringify({}) }).returning({ id: integrations.id }))[0].id;
qId = await mk("qbittorrent", "Torrents");
sId = await mk("sabnzbd", "Usenet");
const now = Date.now();
// Twenty minutes with no network, then still none; the client has an errored torrent, a stalled one, and 3 GB free.
const torrents = [item({ id: "e", name: "Broken", state: "error", rawState: "missingFiles" }), item({ id: "s", name: "Old.Stall", state: "stalled", rawState: "stalledDL", speed: 0, activityAt: iso(now - 3 * DAY) }), item({ id: "d", name: "Moving", state: "downloading" }), item({ id: "u", name: "Seeded", state: "seeding" })];
const q = (extra: Partial<Read> = {}) => read(torrents, { connection: "disconnected", disks: [{ label: "Download folder", free: 3 * GB, total: null }], ...extra });
await dl.storeRead(qId, q(), new Date(now - 20 * MIN));
await dl.storeRead(qId, q(), new Date(now));
// A queue paused for seven hours with two waiting, and a nearly full disk; one failure a minute ago and one last week.
const sab = (extra: Partial<Read> = {}) =>
read([item({ id: "a", name: "Waiting.1", state: "queued" }), item({ id: "b", name: "Waiting.2", state: "queued" })], {
paused: true,
speedDown: 0,
speedUp: null,
connection: null,
disks: [{ label: "Complete folder", free: 30 * GB, total: 1000 * GB }],
failed: [item({ id: "f1", name: "Failed.Now", state: "failed", message: "Unpacking failed", activityAt: iso(now - MIN) }), item({ id: "f2", name: "Failed.Then", state: "failed", activityAt: iso(now - 7 * DAY) })],
warnings: { count: 1, recent: ["Failed to connect to news.example.com"] },
...extra,
});
await dl.storeRead(sId, sab(), new Date(now - 7 * HOUR));
await dl.storeRead(sId, sab(), new Date(now));
await fresh();
const a = express();
a.use((req, _res, next) => {
(req as unknown as { session: unknown }).session = { user: { sub: "viewer" } };
next();
});
a.use("/api/downloads", downloadsRouter);
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/downloads`;
});
after(() => {
app.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows keeps the database file locked until the process exits.
}
});
test("the health pass judges each from what is stored, and holds one whose last read is old", async () => {
let { snapshot, held } = await collectSnapshot();
assert.deepEqual(snapshot.downloads?.map((d) => [d.kind, d.integrationId]).sort(), [["qbittorrent", qId], ["sabnzbd", sId]].sort());
const list = evaluateHealth(snapshot, { serverOfflineMinutes: 60, diskUsagePercent: 90 }, Date.now(), { skipServers: true });
const mine = list.filter((x) => /^(qbittorrent|sabnzbd)-/.test(x.key));
assert.deepEqual(
mine.map((x) => x.key).sort(),
[`qbittorrent-connection:${qId}`, `qbittorrent-disk:${qId}:download-folder`, `qbittorrent-stuck:${qId}`, `sabnzbd-disk:${sId}:complete-folder`, `sabnzbd-paused:${sId}`].sort(),
);
const disk = mine.find((x) => x.key === `qbittorrent-disk:${qId}:download-folder`)!;
assert.deepEqual([disk.severity, disk.source], ["critical", `qbittorrent:${qId}`]);
assert.match(mine.find((x) => x.key === `qbittorrent-stuck:${qId}`)!.message, /2 downloads are stuck — Broken; Old\.Stall/);
for (const k of ["stuck", "connection", "paused", "stalled", "disk"]) assert.equal(subjectOfConditionKey(`qbittorrent-${k}:${qId}:x`), `integration:${qId}`);
await stale();
({ snapshot, held } = await collectSnapshot());
assert.deepEqual([snapshot.downloads?.map((d) => d.integrationId), held.has(`qbittorrent:${qId}`)], [[sId], true]);
await fresh();
});
test("the Alerts page says where to look: the disk under Disk, the rest under Services, and the link is the download clients page", async () => {
invalidateAlertsCache();
const report = await getAlerts(true);
const stuck = report.alerts.find((x) => x.id.endsWith(`qbittorrent-stuck:${qId}`))!;
const disk = report.alerts.find((x) => x.id.endsWith(`sabnzbd-disk:${sId}:complete-folder`))!;
const paused = report.alerts.find((x) => x.id.endsWith(`sabnzbd-paused:${sId}`))!;
assert.deepEqual([stuck.category, stuck.source, stuck.link, stuck.target?.type, disk.category, disk.source, paused.category], ["services", "qBittorrent", "/downloads", "integration", "disk", "SABnzbd", "services"]);
});
test("the page: each client with its kind, what is wrong, its items (the stuck ones marked), what failed in the last day, its disks and its own warnings", async () => {
type Body = { clients: { id: number; kind: string; fresh: boolean; problems: { key: string }[]; state: { stuck: string[]; failedRecent: string[]; total: number; items: { name: string }[]; connection: string | null; paused: boolean; warnings: { count: number } | null; failed: unknown[] | null } }[] };
const body = (await (await fetch(base)).json()) as Body;
const q = body.clients.find((c) => c.id === qId)!;
assert.deepEqual([q.kind, q.fresh, q.state.total, q.state.items.map((i) => i.name), q.state.stuck.sort(), q.state.connection, q.problems.length], ["qbittorrent", true, 4, ["Broken", "Old.Stall", "Moving"], ["e", "s"], "disconnected", 3]);
const s = body.clients.find((c) => c.id === sId)!;
assert.deepEqual([s.kind, s.state.paused, s.state.failed?.length, s.state.failedRecent, s.state.warnings?.count, s.problems.length], ["sabnzbd", true, 2, ["f1"], 1, 2]);
await stale();
const old = (await (await fetch(base)).json()) as Body;
assert.deepEqual(old.clients.find((c) => c.id === qId)!.problems, [], "an old reading says nothing is wrong");
await fresh();
});
test("/metrics has the speeds, the items in each state, what is stuck, paused, connected, failed and the free space — only while the reading is recent", async () => {
let text = await buildMetrics(new Date());
assert.match(text, /homelab_download_speed_bytes\{client="qbittorrent",name="Torrents",direction="down"\} 1000/);
assert.match(text, /homelab_download_speed_bytes\{client="qbittorrent",name="Torrents",direction="up"\} 10/);
assert.doesNotMatch(text, /homelab_download_speed_bytes\{client="sabnzbd",name="Usenet",direction="up"\}/, "SABnzbd does not say");
assert.match(text, /homelab_download_items\{client="qbittorrent",name="Torrents",state="error"\} 1/);
assert.match(text, /homelab_download_items\{client="sabnzbd",name="Usenet",state="queued"\} 2/);
assert.match(text, /homelab_download_stuck_items\{client="qbittorrent",name="Torrents"\} 2/);
assert.match(text, /homelab_download_paused\{client="sabnzbd",name="Usenet"\} 1/);
assert.match(text, /homelab_download_connected\{client="qbittorrent",name="Torrents"\} 0/);
assert.doesNotMatch(text, /homelab_download_connected\{client="sabnzbd"/, "SABnzbd has no such thing");
assert.match(text, /homelab_download_failed_recent\{client="sabnzbd",name="Usenet"\} 1/);
assert.match(text, /homelab_download_disk_free_bytes\{client="qbittorrent",name="Torrents",folder="Download folder"\} 3221225472/);
await stale();
text = await buildMetrics(new Date());
assert.doesNotMatch(text, /homelab_download_[a-z_]+\{client="qbittorrent"/);
assert.match(text, /homelab_download_paused\{client="sabnzbd"/, "the other, still fresh, stays");
await fresh();
});
test("a wrong kind of row is no download client, and taking the integration away takes what was read with it", async () => {
await dl.forgetDownload(qId);
assert.equal((await dl.downloadSyncStatuses())[qId], undefined);
await db.delete(integrations).where(eq(integrations.id, qId));
assert.deepEqual(await db.select().from(downloadState).where(eq(downloadState.integrationId, qId)), []);
});
});