feat(clients): add Debrid-Link as a torrent client

[splitsec2]

calibrain said in #1315 that he'd review and merge a Debrid-Link client if someone took a stab at it, so here it is. It's the fourth debrid service alongside AllDebrid, Real-Debrid and TorBox and it uses the same DownloadClient interface as the other three. No frontend changes, the settings UI picks it up from the backend field definitions.

I can't test this against the live API. I don't use debrid and I don't have a Debrid-Link key. Everything here is built from their v2 API docs and cross-checked against two independent reference implementations, so the request shapes should be right, but nobody has run a real magnet through it yet.

@Tatsu941 you opened the issue and mentioned they give developers free premium. Would you be able to try it? The things most worth confirming are the field names on a seedbox torrent, that premiumLeft is the right premium check, and that an API error comes back the way the client expects. Happy to fix whatever turns up.

Two things about their API shaped how this is written.

Every v2 endpoint wraps its payload in a {success, value} envelope and a failure can arrive with an HTTP 200, so _request_value decides the outcome from the body instead of the status code.

A completed seedbox torrent already carries a direct downloadUrl on every file. The other three clients each need a separate unrestrict or link-request call per file and this one doesn't, which is why it came out shorter than them despite doing the same job.

Endpoints used:

Endpoint	Used for
GET account/infos	test the key, confirm premium time remains
POST seedbox/add	magnet as JSON, .torrent as multipart
GET seedbox/list	poll progress
DELETE seedbox/{id}/remove	clean up

Ruff and basedpyright are clean and the 36 new tests pass. The two failures in tests/e2e/test_proxy_auth_middleware.py are already on main and fail the same way on a pristine checkout. They assume the first proxy-authenticated user becomes an admin, which only holds while the user table has no admin in it, so they depend on how many users earlier tests created.

One thing for review: the download loop uses download_url like the other three clients, which holds each file in memory. I kept the existing pattern rather than do something different in a new-provider PR, but say so if you'd rather it streamed here.

Closes #1315

[calibrain]

Hi, thank you !
I reviewed the PR (and also asked Claude to take a look)
Here are some of the point it found
I think its a decent idea to move to some kind of shared torrent library, from where other specific torrent implementation can stem out (ie TorBos already implements a bunch of these checks, etc.)

Blockers before merge:

• A torrent can write files outside the download folder. File names come straight from the torrent, and a name containing ../ can write anywhere the container can. TorBox already has a check for exactly this (_safe_relative_path); this client should reuse it.
• Debrid-Link's error messages are thrown away. The PR says failures can arrive with HTTP 200, but the docs say errors come back as 4xx/5xx. The client stops at the HTTP status before reading the body, so a bad key shows as "401 Client Error" instead of badToken. The tests pass only because the mock never raises on a bad status.
• The torrent fields it checks aren't in the documented API. It reads error, errorString and downloaded, but the docs only list a numeric status field. A dead or paused torrent would sit at "downloading" forever.
• Downloads can finish incomplete. The file list is captured once and never refreshed, even though the docs say it can be incomplete at first. On top of that, files with the same name overwrite each other, and torrents with many files come back as one ZIP (isZip), which the client doesn't handle. For audiobooks, any of these can import missing chapters with no error.

Worth raising:

• It polls /seedbox/list every 2 seconds. Hitting the rate limit (floodDetected) blocks the account's API use for an hour, and the handler fails the download on the first error of any kind.
• Each file is held in memory twice while saving.
• The error message includes the signed download link, which then shows up in logs and the UI.
• Cancelling doesn't stop the background download.

Most of these come from copying the older Real-Debrid client rather than the hardened TorBox one. Moving the shared pieces into a common debrid module would stop the next client from repeating this.

---

Note : I think the poll every 2 second is worth fixing, same for the "A torrent can write files outside the download folder"

[splitsec2]

Thanks for going through this so carefully. You were right that I'd copied the older Real-Debrid client instead of starting from TorBox, and it showed. I've pushed a rework that goes by the v2 docs rather than my guesses, and rebased onto current main.

The blockers

• Files outside the download folder. TorBox's _safe_relative_path is now safe_relative_path in torrent_utils, and both clients use it (TorBox's behaviour and messages are unchanged). Two files with the same name get a numbered suffix instead of overwriting each other.
• Error messages. The body is read before the status code, so a bad key reports badToken rather than "401 Client Error", and a missing torrent comes back through badId.
• Undocumented fields. error, errorString and downloaded are gone, and status is read the way the list page documents it (0 paused, 1 queued, 2 verification, 4 downloading, 8 seeding, 100 finished). A torrent counts as done at 8 or 100, and files are only fetched once every file's downloadPercent is 100. There's no documented error status, so a torrent whose progress hasn't moved for an hour fails with the peer count rather than sitting at "downloading" forever. I also found that wait means "held for file selection" rather than queued, so a torrent reported that way now gets started through the config endpoint with nothing left out.
• Incomplete downloads. Once the torrent is ready, the file list is fetched again with ?id=, which the docs give as the way to see the files inside a torrent that's listed as a single ZIP. If a ZIP still comes back it's downloaded and post-processing extracts it. That ?id= is in the list page's note rather than its parameter table, so it's the part I'd most like to see against the live API.

The others

• Polling. The handler still polls every couple of seconds, but the client only asks Debrid-Link every 15 seconds per torrent and serves the cached status in between. floodDetected pauses checks for the hour the docs give instead of failing the download, and network errors, internalError and 5xx are retried for ten minutes before they fail it. Anything else, like badToken, still fails straight away.
• Memory. The file is written from the download buffer instead of copied out of it, so it's held once. Streaming straight to disk would need a new helper that every debrid client could use, so I've left that for the shared module.
• Signed link in the message. Errors name the file now, never the URL.
• Cancel. remove() sets a cancel event the retrieval checks between files and passes to download_url, then waits for the thread before cleaning up, the same way TorBox does.

On the shared debrid module, the path check is the first piece. I'd rather do the rest as its own PR than grow this one, if that works for you.

One thing hasn't changed: I still haven't run this against the live API, because I don't have a Debrid-Link key. It's all tested against responses shaped like the docs' examples. If you or @Tatsu941 can give it a real torrent before merging, I'd feel a lot better about it, and I understand if you'd rather hold it until someone can.

[calibrain]

Thank you very much !