feat: emulate qBittorrent API to report download progress to Sonarr/Radarr

[roziscoding]

Summary

Adds a qBittorrent WebUI API emulation at /api/v2/... so Sonarr/Radarr can register jack as a qBittorrent download client and poll it for download progress, reading the same downloads table jack already maintains. Auto-registration switches from a TorrentBlackhole client to a qBittorrent client, and qB-added downloads switch from jack-pushed import scans to *arr-pulled imports.

Built from the approved plan in ai_docs/plans/2026-06-06-qbittorrent-api-emulation/ (research + 4 phases, Oracle-reviewed).

What it does

• Auth — POST /api/v2/auth/login validates the username against a configured servers[] connector name and the password against jack.apiKey, issuing a SID cookie. Mounted before the global apikey middleware; unauthenticated protected endpoints return 403 (qB convention).
• App — GET /api/v2/app/{version,webapiVersion,preferences} report values tuned so *arr's connection test and priority/removal checks pass (webapiVersion 2.9.2).
• Progress — GET /api/v2/torrents/{info,properties,files} map downloads rows to qB torrents: real BitTorrent infohash (so *arr keeps track), byte-based progress, pausedUP on completion, and content_path != save_path so *arr imports cleanly.
• Grab — POST /api/v2/torrents/add accepts only jack stubs / jack download URLs; magnets and foreign torrents are rejected (415). delete/setCategory are scoped to the calling server's rows.
• Pull model — qB-added downloads (those with qb_source_server set) skip jack's triggerImport; blackhole-added downloads keep the existing push.
• Auto-registration — jack registers itself as a qBittorrent download client (QBittorrentSettings, per-app movieCategory/tvCategory), upgrading any prior TorrentBlackhole "Jack" client in place, and keeps the indexer↔client binding.

Key correctness note

*arr computes the infohash itself from the grabbed .torrent and matches torrents/info by it (TorrentClientBase.cs:200). So jack reports the served stub's real infohash (sha1 of the bencoded info dict from release title+size) via a shared getStubInfoHash in torrent.ts — not sha1(peerId:itemId), which would make *arr lose track of every download.

Schema

Migration 0002 adds nullable qb_category / qb_source_server columns to downloads.

Testing

• 165 backend unit/integration tests pass (bun test apps/backend/src/); lint clean; no new type errors.
• New suites: qbittorrent-mapper, qbittorrent-api (auth/app/mapping/add/delete/setCategory/no-ops/503), integration (qB registration + blackhole→qB upgrade), database (column round-trip).
• e2e/tests/qbittorrent-flow.test.ts is written but requires the live Docker stack (run cd e2e && bun test qbittorrent-flow).

Reviewed

• Oracle plan review applied (notably the infohash fix).
• Post-implementation code review: COMPLIANT / APPROVED. Validation: COMPLETE.
• Follow-ups applied: add returns 503 (not 415) on missing downloads config; session store sweeps expired SIDs on login.

Out of scope

No real BitTorrent (no peer wire / seeding), no sync/maindata, no setPreferences. The blackhole watcher path is untouched.

Update — peer-serving backpressure + retry backoff

Two fixes added on top of the qBittorrent work, root-caused from a real incident where a single interrupted download made a peer unreachable for ~17 minutes.

fix: serve peer files with native backpressure to prevent OOM

The peer file endpoint served downloads via a hand-pumped Bun.file().stream(), which does not apply TCP backpressure. When the downloading peer stalls or aborts mid-transfer (e.g. it was restarted), the serving side reads the entire file into memory as fast as it can — starving the event loop and exhausting RAM. On a swapless host, one stalled stream of a large file is enough to hard-freeze the process until the kernel OOM-kills it.

Fix: streamFile now returns the BunFile (or its sliced view) directly and the router hands it to new Response, so Bun.serve streams it with native backpressure + sendfile.

Verified with an A/B repro (1 GB file, stalled consumer): peak RSS drops from ~1956 MB → ~39 MB, and range serving stays byte-correct (206 + correct Content-Range).

feat: widen peer download retry backoff to survive a peer outage

The download retry schedule (5 attempts, 60 s max backoff) gave up in ~3 minutes — terminally failing a resumable download long before a restarted peer recovered. Raised maxDownloadAttempts to 13 and retryMaxDelayMs to 30 min (worst-case ~64 min window, ~32 min with jitter); early retries stay ~1 s for ordinary blips. Complements this PR's per-chunk idleTimeoutMs: the idle timeout aborts a genuinely stalled transfer quickly, the backoff keeps retrying long enough to ride out a peer being down ~15–20 min, then resumes from the .part.

Deploy note: the backpressure fix is server-side — it must reach serving peers to stop the wedge.

All 176 backend tests pass; lint clean; tsc clean.

Greptile Summary

This PR replaces jack's TorrentBlackhole download client with a full qBittorrent WebUI API emulation (/api/v2/...), allowing Sonarr/Radarr to register jack as a qBittorrent client and poll it for download progress using the existing downloads table. The blackhole watcher and push-import model are removed in favour of *arr-pulled imports triggered by pausedUP state in torrentsInfo.

• Auth & session: SID-cookie login validates the username against a configured server connector name and the password against jack.apiKey; session TTL is refreshed on every authenticated poll (matching real qBittorrent behaviour).
• Infohash correctness: getStubInfoHash and createTorrentStub share the same buildStubInfo helper, guaranteeing the hash jack reports matches what *arr computed from the grabbed .torrent.
• Auto-registration upgrade: registerDownloadClient now emits QBittorrentSettings and matches existing clients by name, so a prior TorrentBlackhole "Jack" client is upgraded in place without leaving duplicates; schema migration 0002 adds nullable qb_category/qb_source_server columns.

Confidence Score: 5/5

Safe to merge; the qBittorrent emulation is well-scoped and the critical infohash correctness guarantee is solid.

The new qB API layer is cleanly isolated, auth is properly session-scoped, and the infohash derivation is shared between stub creation and reporting so *arr tracking is reliable. The previously noted issues (silent 'ok' on failed adds, session TTL not refreshed on polls) are both addressed in this revision. The remaining concerns are operational (O(n) repository scans on frequent polls, no in-flight download cancellation on delete) and do not affect correctness for current deployment sizes.

The qbittorrent controller's repository.list() call on every *arr poll warrants attention as the downloads table grows over time.

Important Files Changed

Filename	Overview
apps/backend/src/modules/qbittorrent/qbittorrent.controller.ts	New controller implementing qBittorrent API emulation; login, torrentsInfo, addTorrent, deleteTorrents, setCategory all well-structured, with session-scoping and 'failed'/'unavailable' surfacing to *arr. Full table scan on every poll and missing cancellation on delete are P2 concerns.
apps/backend/src/modules/qbittorrent/qbittorrent.router.ts	Hono router mounting the qB API surface; SID guard via middleware on /app/* and /torrents/*; auth/login and auth/logout are correctly public. Response codes (403 not 401, 415 for magnets, 503 for unavailable) match qBittorrent conventions.
apps/backend/src/modules/qbittorrent/qbittorrent.session.ts	In-memory SID store with 1h TTL; TTL is now refreshed on every get() (matching real qBittorrent), and expired entries are swept on each login. Looks correct.
apps/backend/src/modules/qbittorrent/qbittorrent.mapper.ts	Maps DownloadRecord → QbTorrent; uses the real BitTorrent v1 infohash (sha1 of bencoded info dict) derived from the same buildStubInfo used by createTorrentStub, ensuring *arr's hash lookup matches.
apps/backend/src/modules/downloads/downloads.service.ts	BlackholeWatcher path removed; new startQbDownload wires createDownload + runDownload for qB-added rows. triggerImport removed — all imports are now *arr-pull via torrentsInfo. Stale blackhole downloads (qbSourceServer=null) that complete via resumeStaleDownloads will not trigger an import scan, which is a known gap flagged in earlier review threads.
apps/backend/src/lib/servers/peer.ts	Replaced whole-request deadline with per-chunk idle timeout (armIdle/clearIdle around each network wait); added part_oversize fast path; expectedBytes fallback to releaseSize; UnknownSizeError thrown when size is completely unknown. IdleTimeoutError is transient in retry-policy; UnknownSizeError is not, which may be intentional but is undocumented.
apps/backend/src/lib/servers/arr/base.ts	registerDownloadClient switched from TorrentBlackhole to QBittorrentSettings; match-by-name logic upgrades existing 'Jack' blackhole clients in place; forceSave:true on both indexer and client registration; JACK_DOWNLOAD_CLIENT_PRIORITY hardcoded to 50 to keep Jack out of *arr's general round-robin pool.
apps/backend/src/app.ts	qB router mounted before requireApiKey middleware (correct; qB uses SID cookie auth); conditional on config.jack && config.downloads && downloadsRepository; completedPath always valid inside the guard.
apps/backend/src/modules/torznab/torrent.ts	Refactored to share buildStubInfo between createTorrentStub and new getStubInfoHash; ensures the reported infohash is exactly sha1(bencode(info dict)) as *arr computes from the .torrent it grabbed.
apps/backend/drizzle/0002_romantic_stryfe.sql	Adds nullable qb_category and qb_source_server columns to downloads via simple ALTER TABLE statements.
apps/backend/src/lib/config.ts	watchPath removed from DownloadsConfig (blackhole watcher gone); idleTimeoutMs added; maxDownloadAttempts default raised from 5→13 and retryMaxDelayMs from 1min→30min to handle peer restart windows. Existing configs silently drop the old watchPath key (Zod strips unknowns).

Sequence Diagram

sequenceDiagram
    participant Arr as Sonarr/Radarr
    participant Jack as jack (/api/v2/*)
    participant DB as downloads table
    participant Peer as Peer connector

    Arr->>Jack: "POST /api/v2/auth/login (username=serverName, password=apiKey)"
    Jack-->>Arr: Ok. + SID cookie

    Arr->>Jack: POST /api/v2/torrents/add (torrent stub or jack URL)
    Jack->>Peer: getRelease(itemId)
    Peer-->>Jack: release (filename, size)
    Jack->>DB: create row (qbCategory, qbSourceServer)
    Jack->>Peer: peerDownload() [background]
    Jack-->>Arr: Ok. 200

    loop Every 5-10 s
        Arr->>Jack: "GET /api/v2/torrents/info?category=jack-{serverId}"
        Jack->>DB: list() filter by category
        Jack-->>Arr: "[{state:downloading, progress:0.45, ...}]"
    end

    Peer-->>Jack: download complete
    Jack->>DB: "markImportQueued (status=import_queued)"

    Arr->>Jack: "GET /api/v2/torrents/info?category=jack-{serverId}"
    Jack-->>Arr: "[{state:pausedUP, progress:1.0, content_path:/completed/file.mkv}]"
    Arr->>Arr: import file from content_path

    Arr->>Jack: "POST /api/v2/torrents/delete (deleteFiles=false)"
    Jack->>DB: delete row
    Jack-->>Arr: Ok. 200

Loading

_{Reviews (10): Last reviewed commit: "feat: widen peer download retry backoff ..." | Re-trigger Greptile}

[gitguardian]

️✅ There are no secrets present in this pull request anymore.

If these secrets were true positive and are still valid, we highly recommend you to revoke them.
While these secrets were previously flagged, we no longer have a reference to the
specific commits where they were detected. Once a secret has been leaked into a git
repository, you should consider it compromised, even if it was deleted immediately.
Find here more information about risks.

---

^{_{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}}

[greptile-apps]

Stale blackhole downloads complete without triggering import

runDownload no longer calls triggerImport, which is correct for the qBittorrent pull model where *arr polls torrentsInfo and sees pausedUP. However, resumeStaleDownloads picks up all downloading rows — including those created by the old blackhole path (where qbSourceServer is null). These rows complete and are marked import_queued, but *arr never added them via /api/v2/torrents/add so it has no record of their hash. When *arr queries torrentsInfo?category=jack-<serverId>, it filters by the category it assigned; stale blackhole downloads have qbCategory = null (rendered as category: '') and are invisible to that filter. The downloaded file sits in completedPath permanently with no import triggered.

A minimal fix is to check record.qbSourceServer in downloadWithRetry after markImportQueued: if it is null, log a prominent warning directing the operator to trigger a manual import scan, or restore the triggerImport call for that case.