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

+14 -1
View File
@@ -15,7 +15,7 @@ the dashboard views themselves load fine. (UniFi, Nginx Proxy Manager, Home Assi
### Checking what an integration can read
On the Integrations page an administrator has an **Inspect** button on each integration that reads through the shared HTTP helper (Authentik, Immich, Jellyfin, NetBox, Nextcloud, Paperless-ngx, Prometheus, Hetzner Cloud, Speedtest Tracker, Fragnet, Sonarr, Radarr, Prowlarr, Lidarr, Readarr, AdGuard Home, Technitium DNS and Grafana). It runs the integration's reader once and shows:
On the Integrations page an administrator has an **Inspect** button on each integration that reads through the shared HTTP helper (Authentik, Immich, Jellyfin, NetBox, Nextcloud, Paperless-ngx, Prometheus, Hetzner Cloud, Speedtest Tracker, Fragnet, Sonarr, Radarr, Prowlarr, Lidarr, Readarr, qBittorrent, SABnzbd, AdGuard Home, Technitium DNS and Grafana). It runs the integration's reader once and shows:
- **what was asked** — each request, its path (with the *names* of the query parameters, not their values), the status, how long it took and how many bytes;
- **what came back** — the *shape* of each JSON answer to three levels: the names of the fields and the kind of each (`string`, `number`, `array(12) of { … }`), with a `?` on a field that only some items of a list have. Never a value, never a token, so the report can be copied into a message;
@@ -419,6 +419,19 @@ osTicket's API cannot close a ticket, so this is the one place in the app that *
- If an application 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 could not be read (the queue, say) is shown as *could not be read*, never as empty.
- `/metrics` has `homelab_arr_health_issues`, `homelab_arr_queue_items`, `homelab_arr_queue_stuck_items`, `homelab_arr_wanted_missing` and `homelab_arr_disk_free_bytes`.
- **Not verified against live installs** — the endpoints and fields are as the applications' published OpenAPI files and source have them (HealthResource, QueueResource, DiskSpaceResource, IndexerStatusResource), and the reader is tried against pretend ones. A finding is raised under a key made from the check and its words (numbers left out), so a finding whose wording changes is raised anew. Lidarr, Readarr and Bazarr are not read.
### qBittorrent and SABnzbd
- **Config fields:** for **qBittorrent**, the **Web UI URL** (Tools → Options → Web UI) and, if it asks for a sign-in, the **user name** and **password** (stored encrypted); leave them empty for one that lets this address in without signing in (*Bypass authentication for clients in whitelisted IP subnets*). For **SABnzbd**, its **URL** and its **API key** (Config → General → Security → API Key — the full API key, not the NZB key; stored encrypted). *Allow self-signed certificate* for either on HTTPS with its own certificate. Add each as its own integration.
- **Required access:** the address reachable from the app. qBittorrent is read through its Web API v2 (`/api/v2/…`): the app signs in with the form (`POST /auth/login`), sends the session cookie and its own address as the `Referer` (qBittorrent's protection against forged requests wants that), reads, and signs out. SABnzbd is read through `/api?mode=…&output=json&apikey=…`. A read is three to five requests, every five minutes. Nothing is sent that adds, pauses, resumes, removes or changes anything — the sign-in is the only POST.
- **What it does:** every **five minutes** each client is read — qBittorrent: its version, every torrent (`/sync/maindata`, or `/torrents/info` where that is not answered) with its state, progress, speed and last activity, the speeds and whether it can reach the network (`connection_status`: connected, firewalled or disconnected) and the free space of its download folder; SABnzbd: its version, the queue (`mode=queue`: up to 200 slots, paused or not, the speed, and the free and total space of the incomplete and complete folders), what failed (`mode=history`: the last 50 entries, the ones that failed) and its own warnings (`mode=warnings`). **Apps → Download clients** shows them, the items that need a look first; items that are finished and idle (seeding, stopped) are counted, not listed (at most 100 are kept).
- **Alerts** (sources *qBittorrent*, *SABnzbd*; held back by maintenance on the integration): **downloads stuck** (in an error state — qBittorrent's `error` and `missingFiles` — or *stalled* with nothing moving for a day; one alert for the lot, naming the first three); **no connection** (qBittorrent, `disconnected` with torrents loaded for 15 minutes — a VPN that dropped; *firewalled* is shown but not raised, since it still downloads); **paused and forgotten** (SABnzbd's queue paused for six hours with downloads waiting); **downloading nothing** (SABnzbd, not paused, work waiting, and no speed for an hour — a news server that does not answer or refuses the login); a **download disk nearly full** (SABnzbd says how big the disks are: under 10% free, critical under 5%; qBittorrent says only what is free: under 20 GB, critical under 5 GB). Failures in SABnzbd's history are shown for the last day but are not an alert, since a failed download is normal on Usenet and the *arr applications try another release. See [MONITORING.md](docs/MONITORING.md#download-clients-qbittorrent-sabnzbd).
- "Since when" (disconnected, paused, idle) is what this app saw: the time of the first read that showed it.
- If a client 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 could not be read (the history, say) is shown as *could not be read*, never as empty.
- `/metrics` has `homelab_download_speed_bytes`, `homelab_download_items`, `homelab_download_stuck_items`, `homelab_download_paused`, `homelab_download_connected`, `homelab_download_failed_recent` and `homelab_download_disk_free_bytes`.
- **A wrong password is retried every five minutes**, and qBittorrent bans an address for an hour after a few wrong ones (*Web UI → Ban client after consecutive failures*). If the integration says it was refused with HTTP 403, fix the password and wait out the ban (or restart qBittorrent).
- **Not verified against live installs** — the endpoints and fields are as the two applications' published API documentation has them, and the reader is tried against pretend ones. qBittorrent 5 renamed some states (`pausedDL` became `stoppedDL`); both are understood. SABnzbd's figures arrive as text, in megabytes and gigabytes, and are converted. Torrents are not paused, removed or added from here, and no NZB is added.
### Hetzner Cloud
- **Config fields:** the project's **API token** (Hetzner Console → the project → Security → API tokens → *Generate API token*; stored encrypted). **Read** permission is enough — and recommended: the app only ever sends GET requests. A token belongs to **one project**, so add one integration for each project you want to watch.