Bump the python-deps group across 1 directory with 2 updates (#1153)

Bumps the python-deps group with 2 updates in the / directory:
[tqdm](https://github.com/tqdm/tqdm) and
[seleniumbase](https://github.com/seleniumbase/SeleniumBase).

Updates `tqdm` from 4.69.1 to 4.70.0
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/tqdm/tqdm/releases">tqdm's
releases</a>.</em></p>
<blockquote>
<h2>tqdm v4.70.0 stable</h2>
<ul>
<li><code>contrib.concurrent</code>: major improvements
<ul>
<li>support <code>process_map(mp_context, max_tasks_per_child)</code>,
<code>thread_map(thread_name_prefix)</code> (<a
href="https://redirect.github.com/tqdm/tqdm/issues/1265">#1265</a>)</li>
<li>fix <code>total</code> based on shortest iterable length (<a
href="https://redirect.github.com/tqdm/tqdm/issues/1473">#1473</a>)</li>
<li>use default <code>max_workers</code> (<a
href="https://redirect.github.com/tqdm/tqdm/issues/1543">#1543</a> &lt;-
<a href="https://redirect.github.com/tqdm/tqdm/issues/1530">#1530</a>,
<a
href="https://redirect.github.com/tqdm/tqdm/issues/1518">#1518</a>)</li>
<li>support <code>timeout</code>, <code>buffersize</code> (<a
href="https://redirect.github.com/tqdm/tqdm/issues/1576">#1576</a>)</li>
<li>improve ETA (<a
href="https://redirect.github.com/tqdm/tqdm/issues/1708">#1708</a> &lt;-
<a
href="https://redirect.github.com/tqdm/tqdm/issues/1161">#1161</a>)</li>
<li>update <code>as_completed</code> (<a
href="https://redirect.github.com/tqdm/tqdm/issues/1709">#1709</a> &lt;-
<a
href="https://redirect.github.com/tqdm/tqdm/issues/1565">#1565</a>)</li>
<li>add <code>tqdm.concurrent.intepreter_map</code> (<a
href="https://redirect.github.com/tqdm/tqdm/issues/1777">#1777</a>)</li>
</ul>
</li>
<li><code>asyncio</code>: support iterables with only
<code>__aiter__</code> (<a
href="https://redirect.github.com/tqdm/tqdm/issues/1714">#1714</a> &lt;-
<a
href="https://redirect.github.com/tqdm/tqdm/issues/1686">#1686</a>)</li>
<li>support <code>reset(float(&quot;inf&quot;))</code> (<a
href="https://redirect.github.com/tqdm/tqdm/issues/1783">#1783</a> &lt;-
<a href="https://redirect.github.com/tqdm/tqdm/issues/1781">#1781</a>,
<a
href="https://redirect.github.com/tqdm/tqdm/issues/651">#651</a>)</li>
<li>framework: test &amp; reduce wheel size (<a
href="https://redirect.github.com/tqdm/tqdm/issues/1782">#1782</a>)</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/tqdm/tqdm/commit/96f2e60e4584cdab57a23602e27043d0465254ad"><code>96f2e60</code></a>
Merge pull request <a
href="https://redirect.github.com/tqdm/tqdm/issues/1777">#1777</a> from
shermansiu/feat/interpreter-pool</li>
<li><a
href="https://github.com/tqdm/tqdm/commit/c27393ec3a0a91d83dd53f04b80ee61f9c0cd5e4"><code>c27393e</code></a>
misc tidy</li>
<li><a
href="https://github.com/tqdm/tqdm/commit/061c6236d56f8c1ed0934606c3b4ee5c59cf122e"><code>061c623</code></a>
Disable <code>tqdm.monitor_interval</code> for subinterpreters because
they do not have ...</li>
<li><a
href="https://github.com/tqdm/tqdm/commit/9fc160ba7f959f955058985b0d1122fc9f0b2729"><code>9fc160b</code></a>
Update how we check for <code>interpreter_map</code> support in the
tests</li>
<li><a
href="https://github.com/tqdm/tqdm/commit/b42463a20fffc17ad4df2aa145076afb0dc4486d"><code>b42463a</code></a>
Ensure that subinterpreters can import tqdm while unpickling the
initializer</li>
<li><a
href="https://github.com/tqdm/tqdm/commit/16d5486c402a2808ec9c398538e0bc56d00866de"><code>16d5486</code></a>
Add support for nested progress bars</li>
<li><a
href="https://github.com/tqdm/tqdm/commit/9f5890fda6cf43e66782fbf34647f808bdc66d58"><code>9f5890f</code></a>
Add initial implementation for interpreter_map</li>
<li><a
href="https://github.com/tqdm/tqdm/commit/321f920bb7368e27eee04fed1c0de2a8a236fd9d"><code>321f920</code></a>
Merge pull request <a
href="https://redirect.github.com/tqdm/tqdm/issues/1783">#1783</a> from
LuShadowX/reset-inf-total</li>
<li><a
href="https://github.com/tqdm/tqdm/commit/4664b5701ebc5299290a1fb31a229fb1bfc64703"><code>4664b57</code></a>
minor tidy</li>
<li><a
href="https://github.com/tqdm/tqdm/commit/426a0988a1e9970041f5a649ae8a6376c5293fbe"><code>426a098</code></a>
Treat inf total as unknown in reset() too</li>
<li>Additional commits viewable in <a
href="https://github.com/tqdm/tqdm/compare/v4.69.1...v4.70.0">compare
view</a></li>
</ul>
</details>
<br />

Updates `seleniumbase` from 4.51.7 to 4.51.8
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/seleniumbase/SeleniumBase/releases">seleniumbase's
releases</a>.</em></p>
<blockquote>
<h2>4.51.8 - Add <code>drag_and_drop()</code> with CDP</h2>
<h2>Add <code>drag_and_drop()</code> with CDP</h2>
<ul>
<li><a
href="https://github.com/seleniumbase/SeleniumBase/commit/b05c11f370e69d7566d59d90883c8e8fec1c0024">Add
a CDP-based drag_and_drop() method</a>
--&gt; This resolves <a
href="https://redirect.github.com/seleniumbase/SeleniumBase/issues/4442">seleniumbase/SeleniumBase#4442</a></li>
<li><a
href="https://github.com/seleniumbase/SeleniumBase/commit/9d9ffb4f3b335da6674917b395958c9378186067">Update
CDP Mode examples</a>
--&gt; Specifically for <code>drag_and_drop()</code></li>
<li><a
href="https://github.com/seleniumbase/SeleniumBase/commit/57f2a4ec5dd286222b114acb5d2272ad459d787d">Update
the docs</a></li>
</ul>
<h2>What's Changed</h2>
<ul>
<li>Add <code>drag_and_drop()</code> with CDP by <a
href="https://github.com/mdmintz"><code>@​mdmintz</code></a> in <a
href="https://redirect.github.com/seleniumbase/SeleniumBase/pull/4443">seleniumbase/SeleniumBase#4443</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/seleniumbase/SeleniumBase/compare/v4.51.7...v4.51.8">https://github.com/seleniumbase/SeleniumBase/compare/v4.51.7...v4.51.8</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/seleniumbase/SeleniumBase/commit/8abc55e9f5ef3f2e1d8c4d92351bcbbf7163e7ce"><code>8abc55e</code></a>
Merge pull request <a
href="https://redirect.github.com/seleniumbase/SeleniumBase/issues/4443">#4443</a>
from seleniumbase/drag-and-drop-with-cdp</li>
<li><a
href="https://github.com/seleniumbase/SeleniumBase/commit/89642ff4894e3351739dc359632566902379ca64"><code>89642ff</code></a>
Version 4.51.8</li>
<li><a
href="https://github.com/seleniumbase/SeleniumBase/commit/9d9ffb4f3b335da6674917b395958c9378186067"><code>9d9ffb4</code></a>
Update CDP Mode examples</li>
<li><a
href="https://github.com/seleniumbase/SeleniumBase/commit/57f2a4ec5dd286222b114acb5d2272ad459d787d"><code>57f2a4e</code></a>
Update the docs</li>
<li><a
href="https://github.com/seleniumbase/SeleniumBase/commit/b05c11f370e69d7566d59d90883c8e8fec1c0024"><code>b05c11f</code></a>
Add a CDP-based <code>drag_and_drop()</code> method</li>
<li>See full diff in <a
href="https://github.com/seleniumbase/SeleniumBase/compare/v4.51.7...v4.51.8">compare
view</a></li>
</ul>
</details>
<br />


Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore <dependency name> major version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's major version (unless you unignore this specific
dependency's major version or upgrade to it yourself)
- `@dependabot ignore <dependency name> minor version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's minor version (unless you unignore this specific
dependency's minor version or upgrade to it yourself)
- `@dependabot ignore <dependency name>` will close this group update PR
and stop Dependabot creating any more for the specific dependency
(unless you unignore this specific dependency or upgrade to it yourself)
- `@dependabot unignore <dependency name>` will remove all of the ignore
conditions of the specified dependency
- `@dependabot unignore <dependency name> <ignore condition>` will
remove the ignore condition of the specified dependency and ignore
conditions


</details>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: CaliBrain <calibrain@l4n.xyz>

.github/workflows/build-and-publish-docker-image.yml

@@ -67,10 +67,10 @@ jobs:
         run: echo "date=$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
 
       - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Log in to the Container registry
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -78,7 +78,13 @@ jobs:
 
       - name: Extract metadata for ${{ matrix.target }} image
         id: meta
-        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
+        env:
+          # Annotate both the per-platform manifests and the multi-arch image
+          # index. The index level is what manifest-list consumers (Renovate's
+          # minimumReleaseAge soak check, provenance/SBOM tooling) read for the
+          # standard org.opencontainers.image.* annotations, including `created`.
+          DOCKER_METADATA_ANNOTATIONS_LEVELS: index,manifest
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}${{ matrix.image_name_suffix }}
           tags: |
@@ -90,11 +96,11 @@ jobs:
             type=ref,event=tag
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
 
       - name: Build and push ${{ matrix.target }} Docker image
         id: push
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           platforms: linux/amd64,linux/arm64
           context: .
@@ -105,10 +111,11 @@ jobs:
             RELEASE_VERSION=${{ github.ref_name }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          annotations: ${{ steps.meta.outputs.annotations }}
 
       - name: Generate artifact attestation for ${{ matrix.target }} image
         if: github.event_name != 'pull_request'
-        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
+        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
         with:
           subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}${{ matrix.image_name_suffix }}
           subject-digest: ${{ steps.push.outputs.digest }}
@@ -127,14 +134,14 @@ jobs:
       LEGACY_NAME: calibre-web-automated-book-downloader
     steps:
       - name: Log in to registry
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
 
       - name: Create legacy aliases
         run: |

.github/workflows/ci.yml

@@ -13,10 +13,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Install uv and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           version: "0.11.3"
           python-version: "3.14"
@@ -39,10 +39,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Install uv and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           version: "0.11.3"
           python-version: "3.14"
@@ -59,10 +59,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Install uv and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           version: "0.11.3"
           python-version: "3.14"
@@ -78,13 +78,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
 
       - name: Build shelfmark-lite image
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           context: .
           target: shelfmark-lite
@@ -99,10 +99,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 24
           cache: "npm"
@@ -122,10 +122,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 24
           cache: "npm"
@@ -142,10 +142,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 24
           cache: "npm"

.github/workflows/codeql.yml

@@ -22,17 +22,17 @@ jobs:
         language: [python, javascript-typescript]
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v3
+        uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v3
         with:
           languages: ${{ matrix.language }}
 
       - name: Autobuild
-        uses: github/codeql-action/autobuild@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v3
+        uses: github/codeql-action/autobuild@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v3
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v3
+        uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v3
         with:
           category: "/language:${{ matrix.language }}"

.github/workflows/e2e-platform.yml

@@ -0,0 +1,130 @@
+name: E2E Platform
+
+# Hermetic end-to-end matrix: boots the app under test against mock
+# Anna's Archive / Cloudflare / bypasser / DNS / proxy / Tor / real torrent
+# clients and runs the cluster suite under each config profile.
+#
+# On a PR that touches relevant code, this runs a fast core subset *and* the heavy
+# `full` profile (real Chrome solving Cloudflare + DoH + real qBittorrent). The
+# `e2e-required` job aggregates them into ONE status check — make that check a
+# required status check in branch protection to block merges on any e2e failure
+# (see tests/e2e/platform/README.md "Gating PRs").
+
+on:
+  pull_request:
+  schedule:
+    - cron: "0 4 * * *"   # nightly full matrix
+  workflow_dispatch:
+
+concurrency:
+  group: e2e-platform-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Detect whether anything that affects the e2e platform changed. This lets the
+  # required check always report (never stuck "pending") while only spending CI on
+  # PRs that can actually break the e2e stack.
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      relevant: ${{ steps.filter.outputs.relevant }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dorny/paths-filter@v4.0.2
+        id: filter
+        with:
+          filters: |
+            relevant:
+              - 'shelfmark/**'
+              - 'entrypoint.sh'
+              - 'tor.sh'
+              - 'Dockerfile'
+              - 'tests/e2e/platform/**'
+              - '.github/workflows/e2e-platform.yml'
+
+  select-profiles:
+    needs: changes
+    if: needs.changes.outputs.relevant == 'true' || github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    outputs:
+      profiles: ${{ steps.pick.outputs.profiles }}
+    steps:
+      - id: pick
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            echo 'profiles=["baseline","bypasser-external","dns-blocked"]' >> "$GITHUB_OUTPUT"
+          else
+            echo 'profiles=["baseline","bypasser-external","bypasser-disabled","dns-manual","dns-blocked","dns-doh","proxy-http","proxy-socks","tor","client-transmission","client-deluge","client-qbittorrent-delayed"]' >> "$GITHUB_OUTPUT"
+          fi
+
+  e2e:
+    needs: select-profiles
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        profile: ${{ fromJSON(needs.select-profiles.outputs.profiles) }}
+    name: e2e (${{ matrix.profile }})
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - name: Sync dependencies
+        run: make install-python-dev
+      - name: Run e2e platform (${{ matrix.profile }})
+        run: tests/e2e/platform/run-e2e.sh env/${{ matrix.profile }}.env
+      - name: Dump shelfmark logs on failure
+        if: failure()
+        run: cat tests/e2e/platform/.state/shelfmark.${{ matrix.profile }}.log || true
+
+  # Heavy "everything real" job: real Chrome internal bypasser solving Cloudflare +
+  # DoH + real qBittorrent webseed download. Runs on relevant PRs and nightly.
+  e2e-full:
+    needs: changes
+    if: needs.changes.outputs.relevant == 'true' || github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    name: e2e (full — real Chrome + qBittorrent)
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - name: Sync dependencies
+        run: make install-python-dev
+      - name: Run full pipeline
+        run: tests/e2e/platform/run-e2e.sh env/full.env
+      - name: Dump logs on failure
+        if: failure()
+        run: |
+          cat tests/e2e/platform/.state/shelfmark.full.log || true
+          docker logs e2e-qbittorrent || true
+
+  # Single aggregated gate. ALWAYS runs (so a required check never hangs "pending"
+  # on unrelated PRs) and FAILS if any e2e job failed/was cancelled. Make THIS the
+  # required status check in branch protection.
+  e2e-required:
+    name: e2e required
+    needs: [e2e, e2e-full]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Aggregate e2e results
+        run: |
+          matrix='${{ needs.e2e.result }}'
+          full='${{ needs.e2e-full.result }}'
+          echo "e2e matrix=$matrix, e2e-full=$full"
+          # success or skipped (unrelated PR) is OK; failure/cancelled blocks.
+          for r in "$matrix" "$full"; do
+            if [ "$r" = "failure" ] || [ "$r" = "cancelled" ]; then
+              echo "::error::An e2e platform job did not pass — blocking."
+              exit 1
+            fi
+          done
+          echo "All e2e platform jobs passed (or were skipped as not relevant)."

.gitignore

@@ -166,6 +166,10 @@ ENV/
 env.bak/
 venv.bak/
 
+# ...but the e2e platform test profiles live in an env/ dir and must be tracked
+!tests/e2e/platform/env/
+!tests/e2e/platform/env/*.env
+
 # Spyder project settings
 .spyderproject
 .spyproject

Dockerfile

@@ -4,7 +4,7 @@ ARG BUILDPLATFORM
 ARG BUILDARCH
 
 # Frontend build stage.
-FROM --platform=$BUILDPLATFORM node:24-alpine@sha256:fb71d01345f11b708a3553c66e7c74074f2d506400ea81973343d915cb64eef0 AS frontend-builder
+FROM --platform=$BUILDPLATFORM node:24-alpine@sha256:a0b9bf06e4e6193cf7a0f58816cc935ff8c2a908f81e6f1a95432d679c54fbfd AS frontend-builder
 
 # Helpful debug output to see what platforms BuildKit thinks it's using
 RUN echo "BUILDPLATFORM=$BUILDPLATFORM BUILDARCH=$BUILDARCH TARGETPLATFORM=$TARGETPLATFORM TARGETARCH=$TARGETARCH"
@@ -25,7 +25,7 @@ COPY src/frontend/ ./
 RUN npm run build
 
 # Use python-slim as the base image
-FROM python:3.14.5-slim@sha256:c845af9399020c7e562969a13689e929074a10fd057acd1b1fad06a2fb068e97 AS base
+FROM python:3.14.6-slim@sha256:cea0e6040540fb2b965b6e7fb5ffa00871e632eef63719f0ea54bca189ce14a6 AS base
 
 COPY --from=ghcr.io/astral-sh/uv:0.11.3@sha256:90bbb3c16635e9627f49eec6539f956d70746c409209041800a0280b93152823 /uv /uvx /bin/
 
@@ -72,7 +72,12 @@ RUN apt-get update && \
     # --- Tor support (activated via USING_TOR=true) ---
     tor \
     supervisor \
-    iptables && \
+    iptables \
+    # --- WireGuard support (activated via USING_WIREGUARD=true) ---
+    wireguard-tools \
+    iproute2 \
+    procps \
+    ca-certificates && \
     # Configure iptables alternatives for tor.sh compatibility
     update-alternatives --set iptables /usr/sbin/iptables-legacy && \
     update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy && \
@@ -131,7 +136,7 @@ RUN mkdir -p \
     ln -s /tmp/shelfmark/seleniumbase/archived_files /app/archived_files && \
     chown -R 1000:1000 /config /books /home/shelfmark /tmp/shelfmark /var/log/shelfmark && \
     chmod -R a+rX /app && \
-    chmod +x /app/entrypoint.sh /app/tor.sh /app/genDebug.sh
+    chmod +x /app/entrypoint.sh /app/tor.sh /app/wireguard.sh /app/genDebug.sh
 
 # Expose the application port
 EXPOSE ${FLASK_PORT}
@@ -147,21 +152,39 @@ ENTRYPOINT ["/usr/bin/dumb-init", "--"]
 
 FROM base AS shelfmark
 
-RUN apt-get update && \
-    apt-get install -y --no-install-recommends \
+# --- Chromium (PINNED to 149.0.7827.196) ---
+# Debian's chromium 150.0.7871.46-1~deb13u1 security update (trixie-security,
+# 2026-07-05) no longer opens the DevTools remote-debugging TCP port at all
+# (no listener, no DevToolsActivePort file, even with a custom --user-data-dir;
+# the RemoteDebuggingAllowed policy does not restore it). The SeleniumBase
+# Pure-CDP driver connects through that port (/json/version), so with 150 every
+# internal bypass dies with "Pure CDP browser startup failed" and all
+# CF-gated downloads fail. Install the last working version from
+# snapshot.debian.org until the bypasser can talk to Chromium >= 150 (e.g.
+# pipe-based DevTools / UC mode) or seleniumbase ships a fix.
+# Chrome 144+ requires --enable-unsafe-swiftshader for WebGL in Docker.
+# This flag is set in internal_bypasser.py _get_browser_args()
+ARG CHROMIUM_VERSION=149.0.7827.196-1~deb13u1
+ARG CHROMIUM_SNAPSHOT=20260704T000000Z
+
+RUN echo "deb [check-valid-until=no] https://snapshot.debian.org/archive/debian-security/${CHROMIUM_SNAPSHOT}/ trixie-security main" \
+        > /etc/apt/sources.list.d/chromium-pin-snapshot.list && \
+    apt-get update -o Acquire::Retries=5 && \
+    apt-get install -y --no-install-recommends -o Acquire::Retries=5 \
     # For dumb display
     xvfb \
     # For screen recording
     ffmpeg \
-    # --- Chromium (unpinned - uses latest from Debian repos) ---
-    # Chrome 144+ requires --enable-unsafe-swiftshader for WebGL in Docker.
-    # This flag is set in internal_bypasser.py _get_browser_args()
-    chromium \
-    chromium-common \
+    chromium=${CHROMIUM_VERSION} \
+    chromium-common=${CHROMIUM_VERSION} \
     # For tkinter (pyautogui)
     python3-tk \
     # For RAR extraction
     unrar-free && \
+    # Keep apt from "upgrading" chromium past the pin inside derived images
+    printf 'Package: chromium chromium-common\nPin: version %s\nPin-Priority: 1001\n' "${CHROMIUM_VERSION}" \
+        > /etc/apt/preferences.d/chromium-pin && \
+    rm /etc/apt/sources.list.d/chromium-pin-snapshot.list && \
     # Create symlink so rarfile library can find unrar
     ln -sf /usr/bin/unrar-free /usr/bin/unrar && \
     # Cleanup APT cache
@@ -173,6 +196,21 @@ RUN apt-get update && \
 RUN --mount=type=cache,target=/root/.cache/uv \
     uv sync --locked --no-default-groups --extra browser
 
+# Deterministically resolve the Xlib namespace collision.
+# pyautogui/mouseinfo pull the stale `python3-xlib` (0.15, 2014), while the
+# `--extra browser` set pulls `python-xlib` (0.33). Both packages install into
+# the same top-level `Xlib/` namespace, so whichever lands last wins. When the
+# 2014 build wins, `Xlib.X` is missing `FamilyServerInterpreted`, which the
+# SeleniumBase Pure-CDP driver requires at browser startup -> every bypass fails
+# with "module 'Xlib.X' has no attribute 'FamilyServerInterpreted'" and no
+# Cloudflare/DDoS-Guard protected download can complete. Drop the stale package
+# and force python-xlib 0.33 to own the namespace. pyautogui runs fine against
+# 0.33 (superset API).
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv pip uninstall --python /app/.venv/bin/python python3-xlib && \
+    uv pip install --python /app/.venv/bin/python --reinstall python-xlib==0.33 && \
+    /app/.venv/bin/python -c "import Xlib.X; assert hasattr(Xlib.X, 'FamilyServerInterpreted'), 'Xlib.X.FamilyServerInterpreted missing after fix'; print('Xlib namespace OK:', Xlib.__version__)"
+
 # uv is only needed while building the image.
 RUN rm -f /usr/bin/uv /usr/bin/uvx
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install install-ci install-python-dev dev build preview frontend-typecheck frontend-lint frontend-format frontend-format-fix frontend-checks frontend-test clean up down docker-build refresh restart build-serve python-lint python-lint-fix python-format python-format-fix python-typecheck python-dead-code python-checks python-test python-test-cov checks fix
+.PHONY: help install install-ci install-python-dev dev build preview frontend-typecheck frontend-lint frontend-format frontend-format-fix frontend-checks frontend-test clean up down docker-build refresh restart build-serve python-lint python-lint-fix python-format python-format-fix python-typecheck python-dead-code python-checks python-test python-test-cov e2e-platform e2e-platform-profile e2e-platform-matrix e2e-platform-full e2e-platform-build checks fix
 
 # Frontend directory
 FRONTEND_DIR := src/frontend
@@ -38,6 +38,10 @@ help:
 	@echo "  python-checks - Run all Python static analysis checks"
 	@echo "  python-test - Run unit tests"
 	@echo "  python-test-cov - Run unit tests with coverage report"
+	@echo "  e2e-platform - Run e2e docker platform (baseline profile)"
+	@echo "  e2e-platform-profile PROFILE=<name> - Run e2e platform for one profile"
+	@echo "  e2e-platform-matrix - Run e2e platform across all config profiles"
+	@echo "  e2e-platform-full - Run heavy 'full' profile (real Chrome bypasser + DoH + real qBittorrent)"
 	@echo "  clean      - Remove node_modules and build artifacts"
 	@echo ""
 	@echo "Backend (Docker):"
@@ -127,6 +131,30 @@ python-test-cov:
 	@echo "Running tests with coverage..."
 	uv run pytest tests/ -x --tb=short -m "not integration and not e2e" --cov --cov-report=term-missing
 
+# E2E docker platform: hermetic stack (mock AA/Cloudflare/bypasser/DNS/proxy/Tor)
+# exercised across config profiles. See tests/e2e/platform/README.md.
+E2E_PLATFORM_DIR := tests/e2e/platform
+
+e2e-platform:
+	@echo "Running e2e platform (baseline profile)..."
+	cd $(E2E_PLATFORM_DIR) && ./run-e2e.sh env/baseline.env
+
+e2e-platform-profile:
+	@echo "Running e2e platform (profile=$(PROFILE))..."
+	cd $(E2E_PLATFORM_DIR) && ./run-e2e.sh env/$(PROFILE).env
+
+e2e-platform-matrix:
+	@echo "Running e2e platform matrix (all profiles)..."
+	cd $(E2E_PLATFORM_DIR) && ./run-matrix.sh
+
+e2e-platform-build:
+	@echo "Pre-building e2e platform images once (reused across profiles)..."
+	cd $(E2E_PLATFORM_DIR) && ./build-images.sh
+
+e2e-platform-full:
+	@echo "Running e2e platform FULL profile (real Chrome bypasser + DoH + real qBittorrent)..."
+	cd $(E2E_PLATFORM_DIR) && ./run-e2e.sh env/full.env
+
 # Frontend linting
 frontend-lint:
 	@echo "Running Oxlint..."

compose/docker-compose.wireguard.yml

@@ -0,0 +1,43 @@
+# Routes all traffic through a WireGuard tunnel - requires root startup.
+#
+# Mount your wg-quick config at /config/wg0.conf (read-only is fine). All
+# non-LAN egress is forced through the tunnel by an iptables kill-switch, so if
+# the tunnel drops, external traffic fails closed. LAN ranges (WebUI + internal
+# download clients like Prowlarr / qBittorrent) stay reachable off-tunnel.
+services:
+  shelfmark-wireguard:
+    image: ghcr.io/calibrain/shelfmark:latest
+    environment:
+      FLASK_PORT: 8084
+      # Quoted so it is passed as the literal string "true": entrypoint.sh compares
+      # $USING_WIREGUARD against "true", and some Compose implementations stringify
+      # a bare YAML boolean as "True", which would silently NOT enable WireGuard.
+      USING_WIREGUARD: "true"
+      # Path to the mounted wg-quick config (default shown).
+      WIREGUARD_CONFIG: /config/wg0.conf
+      # CIDRs kept OFF the tunnel so the WebUI and internal clients stay reachable.
+      LAN_NETWORK: 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
+      PUID: 1000
+      PGID: 1000
+    cap_add:
+      - NET_ADMIN
+      - NET_RAW
+    # WireGuard needs the module/kernel routing; NET_ADMIN covers wg-quick.
+    sysctls:
+      - net.ipv4.conf.all.src_valid_mark=1
+      # Disable IPv6 in the container so the kill-switch can guarantee no IPv6
+      # leak path on kernels/containers without a usable ip6tables. wireguard.sh
+      # fails closed if IPv6 is neither kill-switched nor disabled. If your host
+      # DOES have a working ip6tables you may omit these (an ip6tables kill-switch
+      # is installed instead); or set WIREGUARD_ALLOW_IPV6_LEAK=true only if the
+      # container genuinely has no IPv6 connectivity.
+      - net.ipv6.conf.all.disable_ipv6=1
+      - net.ipv6.conf.default.disable_ipv6=1
+    ports:
+      - 8084:8084
+    restart: unless-stopped
+    volumes:
+      - /path/to/books:/books # Default destination for book downloads
+      - /path/to/config:/config # App configuration (put wg0.conf here)
+      # Required for torrent / usenet - path must match your download client's volume exactly
+      # - /path/to/downloads:/path/to/downloads

data/book-languages.json

@@ -1,72 +1,79 @@
 [
-    { "language": "English", "code": "en" },
-    { "language": "Chinese", "code": "zh" },
-    { "language": "Russian", "code": "ru" },
-    { "language": "Spanish", "code": "es" },
-    { "language": "French", "code": "fr" },
-    { "language": "German", "code": "de" },
-    { "language": "Italian", "code": "it" },
-    { "language": "Portuguese", "code": "pt" },
-    { "language": "Polish", "code": "pl" },
-    { "language": "Bulgarian", "code": "bg" },
-    { "language": "Dutch", "code": "nl" },
-    { "language": "Japanese", "code": "ja" },
-    { "language": "Arabic", "code": "ar" },
-    { "language": "Hebrew", "code": "he" },
-    { "language": "Turkish", "code": "tr" },
-    { "language": "Hungarian", "code": "hu" },
-    { "language": "Latin", "code": "la" },
-    { "language": "Czech", "code": "cs" },
-    { "language": "Korean", "code": "ko" },
-    { "language": "Ukrainian", "code": "uk" },
-    { "language": "Indonesian", "code": "id" },
-    { "language": "Romanian", "code": "ro" },
-    { "language": "Swedish", "code": "sv" },
-    { "language": "Greek", "code": "el" },
-    { "language": "Lithuanian", "code": "lt" },
-    { "language": "Bangla", "code": "bn" },
-    { "language": "Traditional Chinese", "code": "zh‑Hant" },
-    { "language": "Afrikaans", "code": "af" },
-    { "language": "Catalan", "code": "ca" },
-    { "language": "Danish", "code": "da" },
-    { "language": "Thai", "code": "th" },
-    { "language": "Hindi", "code": "hi" },
-    { "language": "Irish", "code": "ga" },
-    { "language": "Latvian", "code": "lv" },
+    { "language": "English", "code": "en", "aliases": ["eng"] },
+    { "language": "Chinese", "code": "zh", "aliases": ["chi", "zho"] },
+    { "language": "Russian", "code": "ru", "aliases": ["rus"] },
+    { "language": "Spanish", "code": "es", "aliases": ["spa"] },
+    { "language": "French", "code": "fr", "aliases": ["fra", "fre"] },
+    { "language": "German", "code": "de", "aliases": ["deu", "ger"] },
+    { "language": "Italian", "code": "it", "aliases": ["ita"] },
+    { "language": "Portuguese", "code": "pt", "aliases": ["por"] },
+    { "language": "Polish", "code": "pl", "aliases": ["pol"] },
+    { "language": "Bulgarian", "code": "bg", "aliases": ["bul"] },
+    { "language": "Dutch", "code": "nl", "aliases": ["dut", "nld"] },
+    { "language": "Japanese", "code": "ja", "aliases": ["jap", "jpn"] },
+    { "language": "Arabic", "code": "ar", "aliases": ["ara"] },
+    { "language": "Hebrew", "code": "he", "aliases": ["heb"] },
+    { "language": "Turkish", "code": "tr", "aliases": ["tur"] },
+    { "language": "Hungarian", "code": "hu", "aliases": ["hun"] },
+    { "language": "Latin", "code": "la", "aliases": ["lat"] },
+    { "language": "Czech", "code": "cs", "aliases": ["ces", "cze"] },
+    { "language": "Korean", "code": "ko", "aliases": ["kor"] },
+    { "language": "Ukrainian", "code": "uk", "aliases": ["ukr"] },
+    { "language": "Indonesian", "code": "id", "aliases": ["ind"] },
+    { "language": "Romanian", "code": "ro", "aliases": ["rom", "ron"] },
+    { "language": "Swedish", "code": "sv", "aliases": ["swe"] },
+    { "language": "Greek", "code": "el", "aliases": ["ell", "gre"] },
+    { "language": "Lithuanian", "code": "lt", "aliases": ["lit"] },
+    { "language": "Bangla", "code": "bn", "aliases": ["ben", "bengali"] },
+    { "language": "Traditional Chinese", "code": "zh-Hant", "aliases": ["zh‑Hant"] },
+    { "language": "Afrikaans", "code": "af", "aliases": ["afr"] },
+    { "language": "Catalan", "code": "ca", "aliases": ["cat"] },
+    { "language": "Danish", "code": "da", "aliases": ["dan"] },
+    { "language": "Thai", "code": "th", "aliases": ["tha"] },
+    { "language": "Hindi", "code": "hi", "aliases": ["hin"] },
+    { "language": "Irish", "code": "ga", "aliases": ["gle"] },
+    { "language": "Latvian", "code": "lv", "aliases": ["lav"] },
     { "language": "Tibetan", "code": "bo" },
-    { "language": "Kannada", "code": "kn" },
-    { "language": "Serbian", "code": "sr" },
-    { "language": "Persian", "code": "fa" },
-    { "language": "Croatian", "code": "hr" },
+    { "language": "Kannada", "code": "kn", "aliases": ["kan"] },
+    { "language": "Serbian", "code": "sr", "aliases": ["srp"] },
+    { "language": "Persian", "code": "fa", "aliases": ["farsi", "fas", "per"] },
+    { "language": "Croatian", "code": "hr", "aliases": ["hrv"] },
     { "language": "Slovak", "code": "sk" },
-    { "language": "Javanese", "code": "jv" },
-    { "language": "Vietnamese", "code": "vi" },
-    { "language": "Urdu", "code": "ur" },
-    { "language": "Finnish", "code": "fi" },
-    { "language": "Norwegian", "code": "no" },
+    { "language": "Javanese", "code": "jv", "aliases": ["jav"] },
+    { "language": "Vietnamese", "code": "vi", "aliases": ["vie"] },
+    { "language": "Urdu", "code": "ur", "aliases": ["urd"] },
+    { "language": "Finnish", "code": "fi", "aliases": ["fin"] },
+    { "language": "Norwegian", "code": "no", "aliases": ["nor"] },
     { "language": "Kinyarwanda", "code": "rw" },
-    { "language": "Tamil", "code": "ta" },
+    { "language": "Tamil", "code": "ta", "aliases": ["tam"] },
     { "language": "Belarusian", "code": "be" },
     { "language": "Kazakh", "code": "kk" },
     { "language": "Mongolian", "code": "mn" },
     { "language": "Georgian", "code": "ka" },
-    { "language": "Slovenian", "code": "sl" },
+    { "language": "Slovenian", "code": "sl", "aliases": ["slv"] },
     { "language": "Esperanto", "code": "eo" },
     { "language": "Galician", "code": "gl" },
-    { "language": "Marathi", "code": "mr" },
-    { "language": "Filipino", "code": "fil" },
-    { "language": "Gujarati", "code": "gu" },
-    { "language": "Malayalam", "code": "ml" },
+    { "language": "Marathi", "code": "mr", "aliases": ["mar"] },
+    { "language": "Filipino", "code": "fil", "aliases": ["tagalog", "tgl"] },
+    { "language": "Gujarati", "code": "gu", "aliases": ["guj"] },
+    { "language": "Malayalam", "code": "ml", "aliases": ["mal"] },
     { "language": "Kyrgyz", "code": "ky" },
     { "language": "Azerbaijani", "code": "az" },
     { "language": "Quechua", "code": "qu" },
     { "language": "Swahili", "code": "sw" },
     { "language": "Bashkir", "code": "ba" },
-    { "language": "Punjabi", "code": "pa" },
-    { "language": "Malay", "code": "ms" },
-    { "language": "Telugu", "code": "te" },
+    { "language": "Punjabi", "code": "pa", "aliases": ["pan"] },
+    { "language": "Malay", "code": "ms", "aliases": ["may", "msa"] },
+    { "language": "Telugu", "code": "te", "aliases": ["tel"] },
     { "language": "Albanian", "code": "sq" },
     { "language": "Uyghur", "code": "ug" },
     { "language": "Armenian", "code": "hy" },
-    { "language": "Shan", "code": "shn" }
+    { "language": "Shan", "code": "shn" },
+    { "language": "Bosnian", "code": "bs", "aliases": ["bos"] },
+    { "language": "Burmese", "code": "my", "aliases": ["bur", "mya"] },
+    { "language": "Estonian", "code": "et", "aliases": ["est"] },
+    { "language": "Icelandic", "code": "is", "aliases": ["ice", "isl"] },
+    { "language": "Manx", "code": "gv", "aliases": ["glv"] },
+    { "language": "Scottish Gaelic", "code": "gd", "aliases": ["gla"] },
+    { "language": "Sanskrit", "code": "sa", "aliases": ["san"] }
 ]

docker-compose.dev.wireguard.yml

@@ -0,0 +1,25 @@
+# Local development - WireGuard variant
+services:
+  shelfmark-wireguard-dev:
+    extends:
+      file: ./compose/docker-compose.wireguard.yml
+      service: shelfmark-wireguard
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: shelfmark
+    environment:
+      # Quoted so they are passed as the literal string "true" (entrypoint.sh and
+      # the app compare against "true"); a bare YAML boolean can be stringified as
+      # "True" by some Compose variants, silently disabling the feature.
+      DEBUG: "true"
+      USING_WIREGUARD: "true"
+      WIREGUARD_CONFIG: /config/wg0.conf
+    volumes:
+      - ./.local/config:/config
+      - ./.local/books:/books
+      - ./.local/log:/var/log/shelfmark
+      - ./.local/tmp:/tmp/shelfmark
+      # Place your wg-quick config at ./.local/config/wg0.conf
+      # Required for torrent / usenet - path must match your download client's volume exactly
+      # - /path/to/downloads:/path/to/downloads

docs/configuration.md

@@ -91,6 +91,10 @@ Example:
 - Shelfmark can see the same files at `/downloads/books/...`
 - Add a mapping from Remote Path `/data/torrents` to Local Path `/downloads`
 
+If the files are copied or synced into Shelfmark on a delay, increase **Completed Path Wait (seconds)**
+in Settings -> Advanced. The default is 60 seconds; seedbox or remote-sync setups may need a value
+longer than the sync interval.
+
 ## File Processing Options
 
 ### Transfer Method (Torrent / Usenet Only)

docs/environment-variables.md

@@ -7,6 +7,7 @@ This document lists all configuration options that can be set via environment va
 ## Table of Contents
 
 - [Bootstrap Configuration](#bootstrap-configuration)
+- [Egress / VPN Routing](#egress--vpn-routing)
 - [General](#general)
 - [Search Mode](#search-mode)
 - [Downloads](#downloads)
@@ -145,6 +146,98 @@ Show the onboarding wizard on first run. Set to false to skip (useful for epheme
 
 </details>
 
+## Egress / VPN Routing
+
+These startup-only variables are consumed by `entrypoint.sh` / `wireguard.sh` to select and configure the WireGuard transparent-egress kill-switch. `USING_WIREGUARD` and [`USING_TOR`](#using_tor) (documented under Network) are mutually exclusive; both require root startup.
+
+| Variable | Description | Type | Default |
+|----------|-------------|------|---------|
+| `USING_WIREGUARD` | Route all traffic through a WireGuard VPN tunnel with a fail-closed iptables kill-switch (non-tunnel egress is dropped). Requires root startup and NET_ADMIN (plus NET_RAW). Mutually exclusive with USING_TOR. | boolean | `false` |
+| `WIREGUARD_CONFIG` | Path to the mounted wg-quick configuration file. | string (path) | `/config/wg0.conf` |
+| `WIREGUARD_INTERFACE` | WireGuard interface name brought up by wg-quick. | string | `wg0` |
+| `LAN_NETWORK` | Comma-separated CIDRs kept off the tunnel so the WebUI and internal download clients (Prowlarr, qBittorrent) stay reachable. | string (comma-separated) | `127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16` |
+| `WIREGUARD_ENFORCE_DNS` | Pin the container's resolver so DNS cannot silently fall back to an off-tunnel path. The resolver used is WIREGUARD_DNS if set, else the tunnel config's DNS = line. This does NOT force queries through the tunnel: it is designed for a trusted LAN resolver kept reachable off-tunnel via LAN_NETWORK (the query leaves over the LAN; the resolver encrypts upstream while the download still egresses via the tunnel). Special case: when Docker's embedded resolver (nameserver 127.0.0.11) is present, it is PRESERVED so container-name resolution (e.g. prowlarr, qbittorrent) keeps working, and the embedded resolver's upstream must be pinned via the container's compose dns: list. Fails closed (refuses to start) only when no embedded resolver is present AND no resolver is defined, or /etc/resolv.conf is not writable. | boolean | `true` |
+| `WIREGUARD_DNS` | Explicit resolver(s) (comma/space separated) to pin when WIREGUARD_ENFORCE_DNS is true and Docker's embedded resolver is NOT in use. Use when the VPN's pushed DNS filters domains you need; point it at a resolver reachable via the tunnel or an allowed LAN resolver. NOTE: when the embedded resolver (127.0.0.11) is present it is preserved and this value cannot repoint its upstream from inside the container — set the container's compose dns: list to the trusted resolver instead. | string (comma-separated) | `unset (uses config DNS = line)` |
+| `WIREGUARD_DISABLE_IPV6` | Strip IPv6 Address/AllowedIPs/DNS from the tunnel config before wg-quick (many container kernels lack the ip6tables raw table wg-quick needs) and remove IPv6 as a leak surface. | boolean | `true` |
+| `WIREGUARD_ALLOW_IPV6_LEAK` | Escape hatch: continue startup even when an IPv6 kill-switch cannot be installed AND IPv6 cannot be disabled. Only set when the container has no IPv6 connectivity, as IPv6 egress may otherwise bypass the tunnel. | boolean | `false` |
+| `WIREGUARD_ALLOW_WEBUI_OFFTUNNEL` | When false (default) the kill-switch is strictly fail-closed: the only off-tunnel egress permitted is loopback, the tunnel device and the LAN allowlist. Set true only if a NON-LAN client (e.g. a public reverse proxy on a different segment) must reach the WebUI; it permits app-server REPLY packets (--sport FLASK_PORT, conntrack REPLY) to leave off-tunnel. Server replies only, never client-initiated egress, so it cannot leak outbound browsing/downloads or the real IP for outbound requests, but it is still an off-tunnel path while the tunnel is down, hence opt-in. LAN WebUI clients never need it (covered by LAN_NETWORK). | boolean | `false` |
+| `WIREGUARD_STALE_AFTER` | Seconds since the last WireGuard handshake before the healthcheck bounces the tunnel. | number | `180` |
+
+<details>
+<summary>Detailed descriptions</summary>
+
+#### `USING_WIREGUARD`
+
+Route all traffic through a WireGuard VPN tunnel with a fail-closed iptables kill-switch (non-tunnel egress is dropped). Requires root startup and NET_ADMIN (plus NET_RAW). Mutually exclusive with USING_TOR.
+
+- **Type:** boolean
+- **Default:** `false`
+
+#### `WIREGUARD_CONFIG`
+
+Path to the mounted wg-quick configuration file.
+
+- **Type:** string (path)
+- **Default:** `/config/wg0.conf`
+
+#### `WIREGUARD_INTERFACE`
+
+WireGuard interface name brought up by wg-quick.
+
+- **Type:** string
+- **Default:** `wg0`
+
+#### `LAN_NETWORK`
+
+Comma-separated CIDRs kept off the tunnel so the WebUI and internal download clients (Prowlarr, qBittorrent) stay reachable.
+
+- **Type:** string (comma-separated)
+- **Default:** `127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16`
+
+#### `WIREGUARD_ENFORCE_DNS`
+
+Pin the container's resolver so DNS cannot silently fall back to an off-tunnel path. The resolver used is WIREGUARD_DNS if set, else the tunnel config's DNS = line. This does NOT force queries through the tunnel: it is designed for a trusted LAN resolver kept reachable off-tunnel via LAN_NETWORK (the query leaves over the LAN; the resolver encrypts upstream while the download still egresses via the tunnel). Special case: when Docker's embedded resolver (nameserver 127.0.0.11) is present, it is PRESERVED so container-name resolution (e.g. prowlarr, qbittorrent) keeps working, and the embedded resolver's upstream must be pinned via the container's compose dns: list. Fails closed (refuses to start) only when no embedded resolver is present AND no resolver is defined, or /etc/resolv.conf is not writable.
+
+- **Type:** boolean
+- **Default:** `true`
+
+#### `WIREGUARD_DNS`
+
+Explicit resolver(s) (comma/space separated) to pin when WIREGUARD_ENFORCE_DNS is true and Docker's embedded resolver is NOT in use. Use when the VPN's pushed DNS filters domains you need; point it at a resolver reachable via the tunnel or an allowed LAN resolver. NOTE: when the embedded resolver (127.0.0.11) is present it is preserved and this value cannot repoint its upstream from inside the container — set the container's compose dns: list to the trusted resolver instead.
+
+- **Type:** string (comma-separated)
+- **Default:** `unset (uses config DNS = line)`
+
+#### `WIREGUARD_DISABLE_IPV6`
+
+Strip IPv6 Address/AllowedIPs/DNS from the tunnel config before wg-quick (many container kernels lack the ip6tables raw table wg-quick needs) and remove IPv6 as a leak surface.
+
+- **Type:** boolean
+- **Default:** `true`
+
+#### `WIREGUARD_ALLOW_IPV6_LEAK`
+
+Escape hatch: continue startup even when an IPv6 kill-switch cannot be installed AND IPv6 cannot be disabled. Only set when the container has no IPv6 connectivity, as IPv6 egress may otherwise bypass the tunnel.
+
+- **Type:** boolean
+- **Default:** `false`
+
+#### `WIREGUARD_ALLOW_WEBUI_OFFTUNNEL`
+
+When false (default) the kill-switch is strictly fail-closed: the only off-tunnel egress permitted is loopback, the tunnel device and the LAN allowlist. Set true only if a NON-LAN client (e.g. a public reverse proxy on a different segment) must reach the WebUI; it permits app-server REPLY packets (--sport FLASK_PORT, conntrack REPLY) to leave off-tunnel. Server replies only, never client-initiated egress, so it cannot leak outbound browsing/downloads or the real IP for outbound requests, but it is still an off-tunnel path while the tunnel is down, hence opt-in. LAN WebUI clients never need it (covered by LAN_NETWORK).
+
+- **Type:** boolean
+- **Default:** `false`
+
+#### `WIREGUARD_STALE_AFTER`
+
+Seconds since the last WireGuard handshake before the healthcheck bounces the tunnel.
+
+- **Type:** number
+- **Default:** `180`
+
+</details>
+
 ## General
 
 | Variable | Description | Type | Default |
@@ -339,8 +432,8 @@ The release source tab to open by default in the release modal for audiobooks. U
 | `BOOKS_OUTPUT_MODE` | Choose where completed book files are sent. | string (choice) | `folder` |
 | `INGEST_DIR` | Directory where downloaded files are saved. Use {User} for per-user folders (e.g. /books/{User}). | string | `/books` |
 | `FILE_ORGANIZATION` | Choose how downloaded book files are named and organized. | string (choice) | `rename` |
-| `TEMPLATE_RENAME` | Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads. | string | `{Author} - {Title} ({Year})` |
-| `TEMPLATE_ORGANIZE` | Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. | string | `{Author}/{Title} ({Year})` |
+| `TEMPLATE_RENAME` | Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads. | string | `{Author} - {Title} ({Year})` |
+| `TEMPLATE_ORGANIZE` | Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. | string | `{Author}/{Title} ({Year})` |
 | `HARDLINK_TORRENTS` | Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder. | boolean | `false` |
 | `BOOKLORE_HOST` | Base URL of your Grimmory instance | string | _none_ |
 | `BOOKLORE_USERNAME` | Grimmory account username | string | _none_ |
@@ -361,8 +454,8 @@ The release source tab to open by default in the release modal for audiobooks. U
 | `EMAIL_ALLOW_UNVERIFIED_TLS` | Disable TLS certificate verification (not recommended). | boolean | `false` |
 | `DESTINATION_AUDIOBOOK` | Directory where downloaded audiobook files are saved. Leave empty to use the Books destination. | string | _none_ |
 | `FILE_ORGANIZATION_AUDIOBOOK` | Choose how downloaded audiobook files are named and organized. | string (choice) | `rename` |
-| `TEMPLATE_AUDIOBOOK_RENAME` | Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads. | string | `{Author} - {Title}` |
-| `TEMPLATE_AUDIOBOOK_ORGANIZE` | Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. | string | `{Author}/{Title}/{Title}` |
+| `TEMPLATE_AUDIOBOOK_RENAME` | Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads. | string | `{Author} - {Title}` |
+| `TEMPLATE_AUDIOBOOK_ORGANIZE` | Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. | string | `{Author}/{Title}/{Title}` |
 | `HARDLINK_TORRENTS_AUDIOBOOK` | Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder. | boolean | `true` |
 | `AUTO_OPEN_DOWNLOADS_SIDEBAR` | Automatically open the downloads sidebar when a new download is queued. | boolean | `false` |
 | `DOWNLOAD_TO_BROWSER_CONTENT_TYPES` | Automatically download completed files to your browser for the selected content types. | string (comma-separated) | _empty list_ |
@@ -406,7 +499,7 @@ Choose how downloaded book files are named and organized.
 
 **Naming Template**
 
-Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads.
+Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads.
 
 - **Type:** string
 - **Default:** `{Author} - {Title} ({Year})`
@@ -415,7 +508,7 @@ Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename wi
 
 **Path Template**
 
-Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.
+Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.
 
 - **Type:** string
 - **Default:** `{Author}/{Title} ({Year})`
@@ -616,7 +709,7 @@ Choose how downloaded audiobook files are named and organized.
 
 **Naming Template**
 
-Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads.
+Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads.
 
 - **Type:** string
 - **Default:** `{Author} - {Title}`
@@ -625,7 +718,7 @@ Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename wi
 
 **Path Template**
 
-Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.
+Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.
 
 - **Type:** string
 - **Default:** `{Author}/{Title}/{Title}`
@@ -958,6 +1051,7 @@ Comma-separated hosts to bypass proxy (e.g., localhost,127.0.0.1,10.*,*.local)
 | `CUSTOM_SCRIPT` | Path to a script to run after each successful download. Must be executable. | string | _none_ |
 | `CUSTOM_SCRIPT_PATH_MODE` | Pass the path to the custom script as an absolute path or relative to the destination folder. | string (choice) | `absolute` |
 | `CUSTOM_SCRIPT_JSON_PAYLOAD` | Send a JSON payload to the script via stdin. Useful for multi-file imports (audiobooks) or richer metadata without relying on path parsing. | boolean | `false` |
+| `DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT` | How long to wait after a torrent or usenet client reports completion for the completed file path to become visible to Shelfmark. Increase this for seedbox or remote-sync workflows. | number | `60` |
 | `COVERS_CACHE_ENABLED` | Cache book covers on the server for faster loading. | boolean | `true` |
 | `COVERS_CACHE_TTL` | How long to keep cached covers. Set to 0 to keep forever (recommended for static artwork). | number | `0` |
 | `COVERS_CACHE_MAX_SIZE_MB` | Maximum disk space for cached covers. Oldest images are removed when limit is reached. | number | `500` |
@@ -1038,6 +1132,16 @@ Send a JSON payload to the script via stdin. Useful for multi-file imports (audi
 - **Type:** boolean
 - **Default:** `false`
 
+#### `DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT`
+
+**Completed Path Wait (seconds)**
+
+How long to wait after a torrent or usenet client reports completion for the completed file path to become visible to Shelfmark. Increase this for seedbox or remote-sync workflows.
+
+- **Type:** number
+- **Default:** `60`
+- **Constraints:** min: 0, max: 3600
+
 #### `COVERS_CACHE_ENABLED`
 
 **Enable Cover Cache**
@@ -1107,6 +1211,7 @@ How long to cache individual book details. Default: 600 (10 minutes). Max: 60480
 | `PROWLARR_API_KEY` | Found in Prowlarr: Settings > General > API Key | string (secret) | _none_ |
 | `PROWLARR_INDEXERS` | Select which indexers to search. 📚 = has book categories. Leave empty to search all. | string (comma-separated) | _empty list_ |
 | `PROWLARR_AUTO_EXPAND` | Automatically retry search without category filtering if no results are found | boolean | `false` |
+| `PROWLARR_COLLAPSE_DUPLICATES` | Collapse a release that several indexer entries returned down to a single row, keeping the entry with the best Prowlarr priority. Turn this off to see every entry that carried it, which is what makes results from filter-specific entries (freeleech and the like) visible. | boolean | `true` |
 | `PROWLARR_USE_SEED_PREFERENCES` | Apply per-indexer seed time and ratio preferences from Prowlarr when sending torrents to the download client | boolean | `false` |
 
 <details>
@@ -1159,6 +1264,15 @@ Automatically retry search without category filtering if no results are found
 - **Type:** boolean
 - **Default:** `false`
 
+#### `PROWLARR_COLLAPSE_DUPLICATES`
+
+**Show one row per release**
+
+Collapse a release that several indexer entries returned down to a single row, keeping the entry with the best Prowlarr priority. Turn this off to see every entry that carried it, which is what makes results from filter-specific entries (freeleech and the like) visible.
+
+- **Type:** boolean
+- **Default:** `true`
+
 #### `PROWLARR_USE_SEED_PREFERENCES`
 
 **Use Prowlarr seed preferences**
@@ -1291,9 +1405,11 @@ Delay between requests in seconds to avoid rate limiting (0-10).
 | `IRC_SERVER` | IRC server hostname | string | _none_ |
 | `IRC_PORT` | IRC server port (usually 6697 for TLS, 6667 for plain) | number | `6697` |
 | `IRC_USE_TLS` | Enable TLS/SSL encryption for the IRC connection. Disable for servers that don't support TLS. | boolean | `true` |
-| `IRC_CHANNEL` | Channel name without the # prefix | string | _none_ |
+| `IRC_CHANNEL` | Channel name without the # prefix. Used for all searches unless a separate audiobook channel is configured below. | string | _none_ |
 | `IRC_NICK` | Your IRC nickname (required). Must be unique on the IRC network. | string | _none_ |
-| `IRC_SEARCH_BOT` | The search bot to address queries to (required). | string | _none_ |
+| `IRC_SEARCH_BOT` | The search bot to address queries to (required). Searches are sent as "@<bot> <query>". | string | _none_ |
+| `IRC_AUDIOBOOK_CHANNEL` | Optional. Channel name (without the # prefix) to use for audiobook searches. Leave blank to use the main channel above for audiobooks too. | string | _none_ |
+| `IRC_AUDIOBOOK_SEARCH_BOT` | Optional. Search bot for the audiobook channel. Leave blank to reuse the main search bot above. Only used when an audiobook channel is set. | string | _none_ |
 | `IRC_CACHE_TTL` | How long to keep cached search results before they expire. | string (choice) | `2592000` |
 
 <details>
@@ -1331,7 +1447,7 @@ Enable TLS/SSL encryption for the IRC connection. Disable for servers that don't
 
 **Channel**
 
-Channel name without the # prefix
+Channel name without the # prefix. Used for all searches unless a separate audiobook channel is configured below.
 
 - **Type:** string
 - **Default:** _none_
@@ -1351,12 +1467,30 @@ Your IRC nickname (required). Must be unique on the IRC network.
 
 **Search bot**
 
-The search bot to address queries to (required). Searches are sent as "@<bot> <query>". Without it, queries would be posted unaddressed to the channel.
+The search bot to address queries to (required). Searches are sent as "@<bot> <query>".
 
 - **Type:** string
 - **Default:** _none_
 - **Required:** Yes
 
+#### `IRC_AUDIOBOOK_CHANNEL`
+
+**Audiobook channel**
+
+Optional. Channel name (without the # prefix) to use for audiobook searches. Leave blank to use the main channel above for audiobooks too.
+
+- **Type:** string
+- **Default:** _none_
+
+#### `IRC_AUDIOBOOK_SEARCH_BOT`
+
+**Audiobook search bot**
+
+Optional. Search bot for the audiobook channel. Leave blank to reuse the main search bot above. Only used when an audiobook channel is set.
+
+- **Type:** string
+- **Default:** _none_
+
 #### `IRC_CACHE_TTL`
 
 **Cache Duration**
@@ -1377,6 +1511,7 @@ How long to keep cached search results before they expire.
 | `QBITTORRENT_URL` | Web UI URL of your qBittorrent instance | string | _none_ |
 | `QBITTORRENT_USERNAME` | qBittorrent Web UI username | string | _none_ |
 | `QBITTORRENT_PASSWORD` | qBittorrent Web UI password | string (secret) | _none_ |
+| `QBITTORRENT_API_KEY` | Found in qBittorrent: Options > Web UI > API Key (qBittorrent 5.2.0+). Used instead of the username and password when set. | string (secret) | _none_ |
 | `QBITTORRENT_CATEGORY` | Category to assign to book downloads in qBittorrent | string | `books` |
 | `QBITTORRENT_CATEGORY_AUDIOBOOK` | Category for audiobook downloads. Leave empty to use the book category. | string | _empty string_ |
 | `QBITTORRENT_DOWNLOAD_DIR` | Server-side directory where torrents are downloaded (optional, uses qBittorrent default if not specified) | string | _none_ |
@@ -1396,9 +1531,11 @@ How long to keep cached search results before they expire.
 | `RTORRENT_URL` | XML-RPC URL of your rTorrent instance | string | _none_ |
 | `RTORRENT_USERNAME` | HTTP Basic auth username (if authentication enabled) | string | _none_ |
 | `RTORRENT_PASSWORD` | HTTP Basic auth password | string (secret) | _none_ |
-| `RTORRENT_LABEL` | Label to assign to book downloads in rTorrent | string | `cwabd` |
+| `RTORRENT_LABEL` | Label to assign to ebook downloads in rTorrent | string | `cwabd` |
+| `RTORRENT_AUDIOBOOK_LABEL` | Label to assign to audiobook downloads in rTorrent (falls back to Book Label if not set) | string | _none_ |
 | `RTORRENT_DOWNLOAD_DIR` | Server-side directory where torrents are downloaded (optional, uses rTorrent default if not specified) | string | _none_ |
-| `PROWLARR_TORRENT_ACTION` | Remove deletes the torrent from your client immediately after import (stops seeding, files are kept); Keep leaves it in the client to continue seeding | string (choice) | `keep` |
+| `PROWLARR_TORRENT_ACTION` | Choose whether to keep, remove, or move the torrent to another category or label after import | string (choice) | `keep` |
+| `PROWLARR_TORRENT_POST_IMPORT_CATEGORY` | Category or label to assign after a successful import | string | _empty string_ |
 | `PROWLARR_USENET_CLIENT` | Choose which usenet client to use | string (choice) | _empty string_ |
 | `NZBGET_URL` | URL of your NZBGet instance | string | _none_ |
 | `NZBGET_USERNAME` | NZBGet control username | string | `nzbget` |
@@ -1451,6 +1588,15 @@ qBittorrent Web UI password
 - **Type:** string (secret)
 - **Default:** _none_
 
+#### `QBITTORRENT_API_KEY`
+
+**API Key**
+
+Found in qBittorrent: Options > Web UI > API Key (qBittorrent 5.2.0+). Used instead of the username and password when set.
+
+- **Type:** string (secret)
+- **Default:** _none_
+
 #### `QBITTORRENT_CATEGORY`
 
 **Book Category**
@@ -1626,11 +1772,20 @@ HTTP Basic auth password
 
 **Book Label**
 
-Label to assign to book downloads in rTorrent
+Label to assign to ebook downloads in rTorrent
 
 - **Type:** string
 - **Default:** `cwabd`
 
+#### `RTORRENT_AUDIOBOOK_LABEL`
+
+**Audiobook Label**
+
+Label to assign to audiobook downloads in rTorrent (falls back to Book Label if not set)
+
+- **Type:** string
+- **Default:** _none_
+
 #### `RTORRENT_DOWNLOAD_DIR`
 
 **Download Directory**
@@ -1644,11 +1799,20 @@ Server-side directory where torrents are downloaded (optional, uses rTorrent def
 
 **Torrent Completion Action**
 
-Remove deletes the torrent from your client immediately after import (stops seeding, files are kept); Keep leaves it in the client to continue seeding
+Choose whether to keep, remove, or move the torrent to another category or label after import
 
 - **Type:** string (choice)
 - **Default:** `keep`
-- **Options:** `keep` (Keep), `remove` (Remove)
+- **Options:** `keep` (Keep), `remove` (Remove), `change_category` (Change Category)
+
+#### `PROWLARR_TORRENT_POST_IMPORT_CATEGORY`
+
+**Post-Import Category**
+
+Category or label to assign after a successful import
+
+- **Type:** string
+- **Default:** _empty string_
 
 #### `PROWLARR_USENET_CLIENT`
 
@@ -1907,6 +2071,7 @@ Default sort order for Google Books search results.
 | Variable | Description | Type | Default |
 |----------|-------------|------|---------|
 | `DIRECT_DOWNLOAD_ENABLED` | Show Direct Download in release-source lists and allow Direct mode searches. Add your own mirror URLs in the Mirrors tab before using it. | boolean | `false` |
+| `DIRECT_DOWNLOAD_LANGUAGE_FROM_PATH` | When language metadata is missing or unknown, parse the distant path (file path shown in search results) for language tags like [BD FR] or [En]. Also enables local language filtering so lgli files without AA language metadata are not excluded before the distant path can be checked. | boolean | `false` |
 | `AA_DONATOR_KEY` | Enables fast download access on AA. Get this from your donator account page. | string (secret) | _none_ |
 | `FAST_SOURCES_DISPLAY` | Always tried first, no waiting or bypass required. | JSON array | _see UI for defaults_ |
 | `SOURCE_PRIORITY` | Fallback sources, may have waiting. Requires bypasser. Drag to reorder. | JSON array | _see UI for defaults_ |
@@ -1934,6 +2099,15 @@ Show Direct Download in release-source lists and allow Direct mode searches. Add
 - **Type:** boolean
 - **Default:** `false`
 
+#### `DIRECT_DOWNLOAD_LANGUAGE_FROM_PATH`
+
+**Detect Language From Distant Path**
+
+When language metadata is missing or unknown, parse the distant path (file path shown in search results) for language tags like [BD FR] or [En]. Also enables local language filtering so lgli files without AA language metadata are not excluded before the distant path can be checked.
+
+- **Type:** boolean
+- **Default:** `false`
+
 #### `AA_DONATOR_KEY`
 
 **Account Donator Key**

docs/oidc.md

@@ -30,7 +30,19 @@ Configure in **Settings → Security → Authentication Method → OIDC**.
 | Auto-Provision Users | Create accounts on first login | `true` |
 | Login Button Label | Custom text for the sign-in button | — |
 
-Use **Test Connection** to verify discovery and client configuration before attempting login.
+Use **Test Connection** to verify discovery, client configuration, and the provider's token signing keys (JWKS) before attempting login.
+
+> **Authentik users:** make sure your provider has a **Signing Key** selected (e.g. the default self-signed certificate). Without one, Authentik serves an empty JWKS document and every login fails with an OIDC callback error, even though the discovery document looks healthy.
+
+## Account Linking
+
+On login, Shelfmark matches the OIDC identity to a user account in this order:
+
+1. **OIDC subject** — a user who has logged in through this provider before.
+2. **Email** — a local account with the same (unique) email address. This only happens when the provider also asserts `email_verified: true` for the address; an unverified email would let anyone claim a local account by registering its address at the IdP.
+3. Otherwise, a new account is created when **Auto-Provision Users** is enabled (username conflicts get a numeric suffix), or the login is rejected with "Account not found" when it is disabled.
+
+If the `email_verified` claim is missing or `false`, email linking is silently skipped — a common surprise when the address was never verified at the identity provider (e.g. Keycloak's **Email verified** toggle on the user, or Authentik accounts created without email verification). Make sure the `email` scope is requested and the address is marked verified in your IdP.
 
 ## Environment Variables
 
@@ -46,6 +58,8 @@ If `DISABLE_LOCAL_AUTH` and `OIDC_AUTO_REDIRECT` are both enabled, users are red
 
 ## Troubleshooting
 
+- **No token signing keys (empty JWKS)** — The provider's JWKS endpoint returned no keys, so ID tokens can't be verified. In Authentik this happens when the provider has no **Signing Key** selected; pick one (e.g. the default self-signed certificate) and try again.
 - **Issuer validation failed** — The issuer in the token doesn't match the discovery document. Check your provider's external URL / issuer configuration.
 - **Callback URL mismatch** — Reverse proxy isn't forwarding `X-Forwarded-Proto` or `X-Forwarded-Host`, so the constructed callback URL doesn't match what's registered in the provider.
-- **Account not found** — Auto-provision is disabled and the user hasn't been pre-created by an admin.
+- **Account not found** — Auto-provision is disabled and the user hasn't been pre-created by an admin. If you pre-created the account with a matching email, see [Account Linking](#account-linking): the provider must send `email_verified: true` for linking to happen.
+- **Login created a duplicate account instead of linking to my local one** — Email linking requires a verified email; see [Account Linking](#account-linking). With `DEBUG=true`, the log notes when linking is skipped because the address isn't verified.

entrypoint.sh

@@ -81,6 +81,13 @@ if is_truthy "$ENABLE_LOGGING_VALUE"; then
     fi
 fi
 
+# Egress modes are mutually exclusive. Check this BEFORE starting either one so
+# we never run tor.sh and then abort, leaving a half-configured network stack.
+if [ "$USING_TOR" = "true" ] && [ "$USING_WIREGUARD" = "true" ]; then
+    echo "USING_TOR and USING_WIREGUARD are mutually exclusive; enable only one egress mode." >&2
+    exit 1
+fi
+
 if [ "$USING_TOR" = "true" ]; then
     if [ "$RUN_AS_NON_ROOT" = "true" ]; then
         echo "USING_TOR=true requires the container to start as root." >&2
@@ -90,6 +97,15 @@ if [ "$USING_TOR" = "true" ]; then
     ./tor.sh
 fi
 
+if [ "$USING_WIREGUARD" = "true" ]; then
+    if [ "$RUN_AS_NON_ROOT" = "true" ]; then
+        echo "USING_WIREGUARD=true requires the container to start as root." >&2
+        echo "Non-root mode skips the privileged network setup WireGuard depends on." >&2
+        exit 1
+    fi
+    ./wireguard.sh
+fi
+
 if [ "$FILE_LOGGING_ENABLED" = "true" ]; then
     start_file_logging "$LOG_FILE"
 fi
@@ -235,7 +251,11 @@ test_write() {
         return 1
     fi
 
-    if ! run_as_target_user sh -c 'echo 0123456789_TEST > "$1"' _ "$test_file"; then
+    # This is a probe: a failure here is expected (e.g. a fresh root-owned bind
+    # mount) and is recovered by the caller via change_ownership + re-probe. Hide
+    # the shell's "Permission denied"/"Read-only file system" stderr so a handled
+    # probe miss doesn't masquerade as a real boot failure in the logs.
+    if ! run_as_target_user sh -c 'echo 0123456789_TEST 2>/dev/null > "$1"' _ "$test_file"; then
         echo "Failed to write test file in $folder as $USERNAME"
         return 1
     fi
@@ -448,6 +468,12 @@ else
     if [ $config_ok -ne 0 ]; then
         fail_unwritable_config_dir "$CONFIG_PATH"
     fi
+
+    # The ingest/destination library (default /books) is user data and may be a
+    # bind mount owned by another uid; downloads fail with "Destination not
+    # writable" if the runtime user can't write there. Fix the top-level dir only
+    # (root mode) so we don't recursively chown a potentially huge library.
+    make_writable "${INGEST_DIR:-/books}" root
 fi
 
 # Always run Gunicorn (even when DEBUG=true) to ensure Socket.IO WebSocket

pyproject.toml

@@ -19,28 +19,28 @@ dependencies = [
     "psutil",
     "emoji",
     "rarfile",
-    "qbittorrent-api",
+    "qbittorrent-api>=2026.5.3",
     "transmission-rpc",
     "authlib>=1.7.2,<1.8",
-    "apprise>=1.11.0",
+    "apprise>=1.12.0",
 ]
 
 [project.optional-dependencies]
 browser = [
     "pyvirtualdisplay",
     "pyautogui",
-    "seleniumbase==4.49.10",
+    "seleniumbase==4.51.8",
     "python-xlib",
 ]
 
 [dependency-groups]
 dev = [
-    "basedpyright>=1.39.7",
+    "basedpyright>=1.39.9",
     "prek",
     "pytest",
     "pytest-cov",
     "pytest-xdist>=3.8.0",
-    "ruff==0.15.17",
+    "ruff==0.16.0",
     "vulture>=2.14",
 ]
 

readme.md

@@ -106,6 +106,16 @@ Environment variables work for initial setup and Docker deployments. They serve
 | `PUID` / `PGID` | Runtime user/group for the default root-startup flow (also supports legacy `UID`/`GID`) | `1000` / `1000` |
 | `SEARCH_MODE` | `direct` or `universal` | `universal` |
 | `USING_TOR` | Enable Tor routing (requires root startup) | `false` |
+| `USING_WIREGUARD` | Enable WireGuard VPN egress with kill-switch (requires root startup) | `false` |
+| `WIREGUARD_CONFIG` | Path to the mounted wg-quick config | `/config/wg0.conf` |
+| `WIREGUARD_INTERFACE` | WireGuard interface name | `wg0` |
+| `LAN_NETWORK` | Comma-separated CIDRs kept off the tunnel so the WebUI / internal clients stay reachable | `127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16` |
+| `WIREGUARD_ENFORCE_DNS` | Pin the resolver (via `WIREGUARD_DNS`, else the config's `DNS =`) so DNS can't silently fall back to an off-tunnel path. Designed for a trusted LAN resolver kept reachable via `LAN_NETWORK` (query leaves over the LAN; download still egresses via the tunnel) — it does **not** force queries through the tunnel. Docker's embedded resolver (`127.0.0.11`) is preserved when present so container-name resolution keeps working; pin its upstream via the container's `dns:` list. Fails closed if no resolver is available or `/etc/resolv.conf` is not writable. | `true` |
+| `WIREGUARD_DNS` | Explicit resolver(s) to pin (comma/space separated). Use when the VPN's pushed DNS filters domains you need; point at a resolver reachable via the tunnel or an allowed LAN resolver. | _(unset; uses config `DNS =`)_ |
+| `WIREGUARD_DISABLE_IPV6` | Strip IPv6 from the tunnel config (many container kernels lack the ip6tables `raw` table wg-quick needs) and remove IPv6 as a leak surface. | `true` |
+| `WIREGUARD_ALLOW_IPV6_LEAK` | Escape hatch: continue even when an IPv6 kill-switch can't be installed AND IPv6 can't be disabled. Only set if the container has no IPv6 connectivity. | `false` |
+| `WIREGUARD_ALLOW_WEBUI_OFFTUNNEL` | Opt-in off-tunnel WebUI reachability. Default (`false`) keeps the kill-switch strictly fail-closed: the only off-tunnel egress is loopback, the tunnel device and the LAN allowlist. Set `true` only if a **non-LAN** client (e.g. a public reverse proxy on another segment) must reach the WebUI; it permits app-server **replies** (`--sport FLASK_PORT`, conntrack REPLY) off-tunnel — server replies only, never client-initiated egress. LAN clients never need it (covered by `LAN_NETWORK`). | `false` |
+| `WIREGUARD_STALE_AFTER` | Seconds since the last handshake before the healthcheck bounces the tunnel. | `180` |
 
 See the full [Environment Variables Reference](docs/environment-variables.md) for all available options.
 
@@ -141,6 +151,24 @@ docker compose -f docker-compose.tor.yml up -d
 - Timezone is auto-detected from Tor exit node
 - Custom DNS/proxy settings are ignored when Tor is active
 
+#### WireGuard VPN Routing
+Optional WireGuard support to route all external egress through a VPN tunnel with a fail-closed kill-switch:
+```bash
+curl -O https://raw.githubusercontent.com/calibrain/shelfmark/main/compose/docker-compose.wireguard.yml
+# place your wg-quick config where the compose mounts /config, as wg0.conf
+docker compose -f docker-compose.wireguard.yml up -d
+```
+
+**Notes:**
+- Requires root startup
+- Requires `NET_ADMIN` and `NET_RAW` capabilities
+- Mount a standard wg-quick config at `WIREGUARD_CONFIG` (default `/config/wg0.conf`)
+- All non-LAN egress is forced through the tunnel; if the tunnel drops, external traffic **fails closed** while LAN ranges (WebUI, Prowlarr, qBittorrent) stay reachable
+- IPv4 and IPv6 both fail closed. On kernels without a usable `ip6tables`, disable IPv6 for the container (`sysctls: net.ipv6.conf.all.disable_ipv6=1`, as in the compose example) or the container refuses to start rather than risk an IPv6 leak
+- A supervised healthcheck bounces the tunnel if the handshake goes stale, and refreshes the endpoint allow rules so a roaming/rotated peer endpoint can reconnect
+- Mutually exclusive with `USING_TOR`
+- **DNS trust:** `WIREGUARD_DNS` must be a resolver you trust on a trusted network segment. When it is a LAN resolver (kept reachable off-tunnel by `LAN_NETWORK`), the query to that resolver leaves as plaintext UDP/53 on the LAN — the resolver is responsible for encrypting upstream. Two resolver paths exist: (1) when Docker's embedded resolver (`127.0.0.11`) is present it is **preserved** so container names (Prowlarr, qBittorrent) resolve — you MUST pin its upstream to a trusted resolver via the container's compose `dns:` list, since `WIREGUARD_DNS` cannot repoint the embedded resolver from inside the container; (2) otherwise `WIREGUARD_DNS`/the config `DNS =` line is written to `/etc/resolv.conf`. Setting `WIREGUARD_ENFORCE_DNS=false` is a **foot-gun**: with no embedded resolver present the container then uses its inherited resolver, which forwards to the Docker daemon's upstream **off-tunnel**, leaking your DNS. Leave enforcement on unless you have pinned the resolver another way.
+
 ### Lite
 A lighter image without the built-in browser automation. Ideal for:
 

scripts/generate_env_docs.py

@@ -238,6 +238,113 @@ def _generate_bootstrap_env_docs() -> list[str]:
     return lines
 
 
+def _generate_egress_env_docs() -> list[str]:
+    """Generate documentation for VPN/Tor egress environment variables.
+
+    These are startup-only variables consumed by entrypoint.sh / wireguard.sh
+    (before and outside the settings registry) to select and configure the
+    transparent-egress kill-switch. `USING_TOR` has a registry-backed entry
+    under Network and is cross-referenced rather than repeated here so the two
+    mutually exclusive egress modes are discoverable side by side without
+    emitting a duplicate `#### USING_TOR` anchor.
+    """
+    egress_vars = [
+        {
+            "name": "USING_WIREGUARD",
+            "description": "Route all traffic through a WireGuard VPN tunnel with a fail-closed iptables kill-switch (non-tunnel egress is dropped). Requires root startup and NET_ADMIN (plus NET_RAW). Mutually exclusive with USING_TOR.",
+            "type": "boolean",
+            "default": "false",
+        },
+        {
+            "name": "WIREGUARD_CONFIG",
+            "description": "Path to the mounted wg-quick configuration file.",
+            "type": "string (path)",
+            "default": "/config/wg0.conf",
+        },
+        {
+            "name": "WIREGUARD_INTERFACE",
+            "description": "WireGuard interface name brought up by wg-quick.",
+            "type": "string",
+            "default": "wg0",
+        },
+        {
+            "name": "LAN_NETWORK",
+            "description": "Comma-separated CIDRs kept off the tunnel so the WebUI and internal download clients (Prowlarr, qBittorrent) stay reachable.",
+            "type": "string (comma-separated)",
+            "default": "127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16",
+        },
+        {
+            "name": "WIREGUARD_ENFORCE_DNS",
+            "description": "Pin the container's resolver so DNS cannot silently fall back to an off-tunnel path. The resolver used is WIREGUARD_DNS if set, else the tunnel config's DNS = line. This does NOT force queries through the tunnel: it is designed for a trusted LAN resolver kept reachable off-tunnel via LAN_NETWORK (the query leaves over the LAN; the resolver encrypts upstream while the download still egresses via the tunnel). Special case: when Docker's embedded resolver (nameserver 127.0.0.11) is present, it is PRESERVED so container-name resolution (e.g. prowlarr, qbittorrent) keeps working, and the embedded resolver's upstream must be pinned via the container's compose dns: list. Fails closed (refuses to start) only when no embedded resolver is present AND no resolver is defined, or /etc/resolv.conf is not writable.",
+            "type": "boolean",
+            "default": "true",
+        },
+        {
+            "name": "WIREGUARD_DNS",
+            "description": "Explicit resolver(s) (comma/space separated) to pin when WIREGUARD_ENFORCE_DNS is true and Docker's embedded resolver is NOT in use. Use when the VPN's pushed DNS filters domains you need; point it at a resolver reachable via the tunnel or an allowed LAN resolver. NOTE: when the embedded resolver (127.0.0.11) is present it is preserved and this value cannot repoint its upstream from inside the container — set the container's compose dns: list to the trusted resolver instead.",
+            "type": "string (comma-separated)",
+            "default": "unset (uses config DNS = line)",
+        },
+        {
+            "name": "WIREGUARD_DISABLE_IPV6",
+            "description": "Strip IPv6 Address/AllowedIPs/DNS from the tunnel config before wg-quick (many container kernels lack the ip6tables raw table wg-quick needs) and remove IPv6 as a leak surface.",
+            "type": "boolean",
+            "default": "true",
+        },
+        {
+            "name": "WIREGUARD_ALLOW_IPV6_LEAK",
+            "description": "Escape hatch: continue startup even when an IPv6 kill-switch cannot be installed AND IPv6 cannot be disabled. Only set when the container has no IPv6 connectivity, as IPv6 egress may otherwise bypass the tunnel.",
+            "type": "boolean",
+            "default": "false",
+        },
+        {
+            "name": "WIREGUARD_ALLOW_WEBUI_OFFTUNNEL",
+            "description": "When false (default) the kill-switch is strictly fail-closed: the only off-tunnel egress permitted is loopback, the tunnel device and the LAN allowlist. Set true only if a NON-LAN client (e.g. a public reverse proxy on a different segment) must reach the WebUI; it permits app-server REPLY packets (--sport FLASK_PORT, conntrack REPLY) to leave off-tunnel. Server replies only, never client-initiated egress, so it cannot leak outbound browsing/downloads or the real IP for outbound requests, but it is still an off-tunnel path while the tunnel is down, hence opt-in. LAN WebUI clients never need it (covered by LAN_NETWORK).",
+            "type": "boolean",
+            "default": "false",
+        },
+        {
+            "name": "WIREGUARD_STALE_AFTER",
+            "description": "Seconds since the last WireGuard handshake before the healthcheck bounces the tunnel.",
+            "type": "number",
+            "default": "180",
+        },
+    ]
+
+    lines = [
+        "## Egress / VPN Routing",
+        "",
+        "These startup-only variables are consumed by `entrypoint.sh` / `wireguard.sh` to select and configure the WireGuard transparent-egress kill-switch. `USING_WIREGUARD` and [`USING_TOR`](#using_tor) (documented under Network) are mutually exclusive; both require root startup.",
+        "",
+        "| Variable | Description | Type | Default |",
+        "|----------|-------------|------|---------|",
+    ]
+
+    lines.extend(
+        f"| `{var['name']}` | {var['description']} | {var['type']} | `{var['default']}` |"
+        for var in egress_vars
+    )
+
+    lines.append("")
+    lines.append("<details>")
+    lines.append("<summary>Detailed descriptions</summary>")
+    lines.append("")
+
+    for var in egress_vars:
+        lines.append(f"#### `{var['name']}`")
+        lines.append("")
+        lines.append(var["description"])
+        lines.append("")
+        lines.append(f"- **Type:** {var['type']}")
+        lines.append(f"- **Default:** `{var['default']}`")
+        lines.append("")
+
+    lines.append("</details>")
+    lines.append("")
+
+    return lines
+
+
 def generate_env_docs() -> str:
     """Generate markdown documentation for all environment variables."""
     # Import settings modules to ensure all settings are registered
@@ -282,6 +389,7 @@ def generate_env_docs() -> str:
     # Generate TOC
     toc_entries = [
         "- [Bootstrap Configuration](#bootstrap-configuration)",
+        "- [Egress / VPN Routing](#egress--vpn-routing)",
     ]
 
     # Ungrouped tabs first
@@ -307,6 +415,9 @@ def generate_env_docs() -> str:
     # Add bootstrap environment variables documentation
     lines.extend(_generate_bootstrap_env_docs())
 
+    # Add egress / VPN routing (startup-only, shell-driven) documentation
+    lines.extend(_generate_egress_env_docs())
+
     # Generate documentation for ungrouped tabs
     for tab in grouped_tabs.get(None, []):
         lines.extend(_generate_tab_docs(tab))

shelfmark/bypass/internal_bypasser.py

@@ -939,7 +939,17 @@ def _get_via_subprocess(url: str, retry: int, cancel_flag: Event | None = None)
     result_path = (
         Path(tempfile.gettempdir()) / f"shelfmark-bypass-{os.getpid()}-{time.time_ns()}.json"
     )
-    payload = {"url": url, "retry": retry, "result_path": str(result_path)}
+    # DNS provider state lives only in the parent's memory (no disk persistence), so the
+    # freshly spawned helper would otherwise pre-resolve AA hostnames against the system
+    # resolver - which may be blocked or hijacked by the user's ISP. Pass the parent's
+    # active DNS config so the helper mirrors it (e.g. DoH) when building Chrome's host
+    # resolver rules.
+    payload = {
+        "url": url,
+        "retry": retry,
+        "result_path": str(result_path),
+        "dns_config": network.get_dns_config(),
+    }
     env_vars = os.environ.copy()
     env_vars[_BYPASS_CHILD_ENV] = "1"
     env_vars = _prepare_child_browser_env(env_vars)
@@ -1278,6 +1288,30 @@ def get_bypassed_page(
     return response_html
 
 
+def _apply_parent_dns_config(dns_config: dict[str, Any]) -> None:
+    """Mirror the parent process's active DNS provider in this helper subprocess.
+
+    DNS state is in-memory only, so a fresh helper defaults to system DNS and would
+    pre-resolve AA hostnames (for Chrome's --host-resolver-rules) against a resolver
+    that may be blocked/hijacked. Re-applying the parent's provider keeps the helper on
+    the same DoH/custom resolver the parent already validated.
+    """
+    provider = str(dns_config.get("provider") or "").strip().lower()
+    # "auto" means the parent has not rotated off system DNS yet, so the helper's own
+    # default initialization already matches it - nothing to override.
+    if not provider or provider == "auto":
+        return
+    manual_servers = dns_config.get("servers") if provider == "manual" else None
+    try:
+        network.set_dns_provider(
+            provider,
+            manual_servers,
+            use_doh=bool(dns_config.get("doh_enabled")),
+        )
+    except (OSError, RuntimeError, ValueError) as exc:
+        logger.warning("Could not apply parent DNS config (%s): %s", provider, exc)
+
+
 def _run_child_process() -> int:
     """CLI entrypoint used by the Docker helper subprocess."""
     request = json.loads(sys.stdin.read() or "{}")
@@ -1287,6 +1321,10 @@ def _run_child_process() -> int:
         request.get("retry"), _coerce_positive_int(app_config.MAX_RETRY, 10)
     )
 
+    dns_config = request.get("dns_config")
+    if isinstance(dns_config, dict):
+        _apply_parent_dns_config(dns_config)
+
     try:
         html = get(url, retry=retry)
         payload = {

shelfmark/config/booklore_settings.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import hashlib
 from typing import Any
 
 from shelfmark.core.config import config
@@ -23,7 +24,7 @@ _BOOKLORE_OPTIONS_CACHE: dict[str, Any] = {
 
 
 def _get_booklore_cache_key(base_url: str, username: str, password: str) -> str:
-    return f"{base_url}|{username}|{hash(password)}"
+    return f"{base_url}|{username}|{hashlib.sha256(password.encode()).hexdigest()}"
 
 
 def _get_booklore_select_options(

shelfmark/config/security_handlers.py

@@ -115,7 +115,7 @@ def check_oidc_connection(
         response.raise_for_status()
         document = response.json()
 
-        required_fields = ["issuer", "authorization_endpoint", "token_endpoint"]
+        required_fields = ["issuer", "authorization_endpoint", "token_endpoint", "jwks_uri"]
         missing_fields = [field for field in required_fields if field not in document]
         if missing_fields:
             return {
@@ -123,6 +123,24 @@ def check_oidc_connection(
                 "message": f"Discovery document missing fields: {', '.join(missing_fields)}",
             }
 
+        # Logins verify the ID token against the provider's JWKS, so an empty key
+        # set (e.g. an Authentik provider with no Signing Key selected) means every
+        # login will fail even though discovery looks healthy.
+        jwks_uri = str(document["jwks_uri"])
+        jwks_response = requests.get(jwks_uri, timeout=10, verify=get_ssl_verify(jwks_uri))
+        jwks_response.raise_for_status()
+        jwks_document = jwks_response.json()
+        jwks_keys = jwks_document.get("keys") if isinstance(jwks_document, dict) else None
+        if not jwks_keys:
+            return {
+                "success": False,
+                "message": (
+                    "Discovery document is valid, but the provider returned no token "
+                    "signing keys (empty JWKS), so logins will fail. If you use "
+                    "Authentik, select a Signing Key in the provider settings."
+                ),
+            }
+
         return {"success": True, "message": f"Connected to {document['issuer']}"}
     except Exception as exc:
         logger.exception("OIDC connection test failed")

shelfmark/config/settings.py

@@ -1,6 +1,5 @@
 """Core settings registration and derived configuration values."""
 
-import json
 from pathlib import Path
 from typing import Any
 
@@ -15,6 +14,7 @@ from shelfmark.config.download_settings_handlers import (
     check_books_destination,
 )
 from shelfmark.config.email_settings import check_email_connection
+from shelfmark.core.languages import supported_book_languages
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.settings_registry import (
     ActionButton,
@@ -36,6 +36,9 @@ from shelfmark.core.settings_registry import (
     register_settings,
 )
 
+_DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT_DEFAULT = 60
+_DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT_MAX = 3600
+
 
 def _on_save_advanced(values: dict[str, Any]) -> dict[str, Any]:
     """Validate advanced settings before persisting."""
@@ -43,6 +46,40 @@ def _on_save_advanced(values: dict[str, Any]) -> dict[str, Any]:
 
     logger = setup_logger(__name__)
 
+    timeout_key = "DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT"
+    if timeout_key in values:
+        raw_timeout = values.get(timeout_key)
+        if isinstance(raw_timeout, bool):
+            return {
+                "error": True,
+                "message": "Completed Path Wait must be a number of seconds",
+                "values": values,
+            }
+        if raw_timeout is None:
+            return {
+                "error": True,
+                "message": "Completed Path Wait must be a number of seconds",
+                "values": values,
+            }
+        try:
+            timeout_seconds = int(raw_timeout)
+        except TypeError, ValueError:
+            return {
+                "error": True,
+                "message": "Completed Path Wait must be a number of seconds",
+                "values": values,
+            }
+        if timeout_seconds < 0 or timeout_seconds > _DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT_MAX:
+            return {
+                "error": True,
+                "message": (
+                    "Completed Path Wait must be between 0 and "
+                    f"{_DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT_MAX} seconds"
+                ),
+                "values": values,
+            }
+        values[timeout_key] = timeout_seconds
+
     mappings = values.get("PROWLARR_REMOTE_PATH_MAPPINGS")
     if mappings is None:
         return {"error": False, "values": values}
@@ -106,11 +143,8 @@ for key in ["CONFIG_DIR", "LOG_DIR", "TMP_DIR", "INGEST_DIR", "DEBUG", "DOCKERMO
     if hasattr(env, key):
         logger.debug("  %s: %s", key, getattr(env, key))
 
-# Load supported book languages from data file
-# Path is relative to the package root, not this file
-_DATA_DIR = Path(__file__).resolve().parent.parent.parent / "data"
-with (_DATA_DIR / "book-languages.json").open() as file:
-    _SUPPORTED_BOOK_LANGUAGE = json.load(file)
+# Selectable book languages, without the resolution aliases clients do not need.
+_SUPPORTED_BOOK_LANGUAGE = supported_book_languages()
 
 # Directory settings
 BASE_DIR = Path(__file__).resolve().parent.parent.parent
@@ -975,7 +1009,7 @@ def download_settings() -> list[SettingsField]:
             key="TEMPLATE_RENAME",
             label="Naming Template",
             description=(
-                "Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} "
+                "Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} "
                 "(source filename without extension). Universal adds: {Series}, "
                 "{SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: "
                 "{Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. "
@@ -994,7 +1028,7 @@ def download_settings() -> list[SettingsField]:
             key="TEMPLATE_ORGANIZE",
             label="Path Template",
             description=(
-                "Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, "
+                "Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, "
                 "{OriginalName} (source filename without extension). Universal adds: {Series}, "
                 "{SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: "
                 "{Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty."
@@ -1257,7 +1291,7 @@ def download_settings() -> list[SettingsField]:
             key="TEMPLATE_AUDIOBOOK_RENAME",
             label="Naming Template",
             description=(
-                "Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} "
+                "Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} "
                 "(source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, "
                 "{PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: "
                 "{Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. "
@@ -1274,7 +1308,7 @@ def download_settings() -> list[SettingsField]:
             key="TEMPLATE_AUDIOBOOK_ORGANIZE",
             label="Path Template",
             description=(
-                "Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, "
+                "Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, "
                 "{OriginalName} (source filename without extension), {Series}, {SeriesPosition}, "
                 "{Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: "
                 "{Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty."
@@ -1780,6 +1814,18 @@ def advanced_settings() -> list[SettingsField]:
             title="Remote Path Mappings",
             description="Map download client paths to paths inside Shelfmark. Needed when volume mounts differ between containers.",
         ),
+        NumberField(
+            key="DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT",
+            label="Completed Path Wait (seconds)",
+            description=(
+                "How long to wait after a torrent or usenet client reports completion "
+                "for the completed file path to become visible to Shelfmark. Increase "
+                "this for seedbox or remote-sync workflows."
+            ),
+            default=_DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT_DEFAULT,
+            min_value=0,
+            max_value=_DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT_MAX,
+        ),
         TableField(
             key="PROWLARR_REMOTE_PATH_MAPPINGS",
             label="Path Mappings",

shelfmark/core/external_user_linking.py

@@ -149,7 +149,7 @@ def _find_existing_alias_user(
     ]
     if not candidates:
         return None
-    return sorted(candidates, key=lambda user: int(user.get("id") or 0))[0]
+    return min(candidates, key=lambda user: int(user.get("id") or 0), default=None)
 
 
 def _resolve_create_username(

shelfmark/core/languages.py

@@ -0,0 +1,138 @@
+"""Canonical language resolution shared by every release source.
+
+Release sources report a language in whatever shape their upstream uses: a
+two-letter code, an ISO 639-2 three-letter code in either the bibliographic or
+terminological form, or an English name. They all need the same ISO 639-1 code
+out the other side, so the aliases live in one place (``data/book-languages.json``)
+and adding a language means editing one file.
+"""
+
+import json
+import threading
+import unicodedata
+from pathlib import Path
+
+from shelfmark.core.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+LANGUAGE_DATA_PATH = Path(__file__).resolve().parents[1].parent / "data" / "book-languages.json"
+
+# Values a source uses to mean "we could not tell".
+LANGUAGE_PLACEHOLDERS = frozenset({"", "-", "--", "unknown", "unk", "n/a", "na", "none", "null"})
+
+_ALIAS_TO_CODE: dict[str, str] | None = None
+_CODE_TO_NAME: dict[str, str] | None = None
+_LOCK = threading.Lock()
+
+
+# Separators that stand in for the hyphen in a subtag. The dashes turn up in
+# codes copied from web pages -- "zh‑Hant" used U+2011, which renders close
+# enough to both a hyphen and an underscore to go unnoticed -- and the
+# underscore is the spelling Direct Download accepted before this module existed.
+_SUBTAG_SEPARATORS = dict.fromkeys(map(ord, "‐‑‒–—―−﹘﹣－_"), "-")
+
+
+def _fold(value: str) -> str:
+    """Casefold, strip accents, and normalize subtag separators, so 'Español'
+    and 'espanol', or 'zh-Hant', 'zh‑Hant' and 'zh_Hant', all match."""
+    decomposed = unicodedata.normalize("NFKD", value).translate(_SUBTAG_SEPARATORS)
+    stripped = "".join(ch for ch in decomposed if not unicodedata.combining(ch))
+    return " ".join(stripped.split()).casefold()
+
+
+def _load() -> tuple[dict[str, str], dict[str, str]]:
+    global _ALIAS_TO_CODE, _CODE_TO_NAME
+
+    if _ALIAS_TO_CODE is not None and _CODE_TO_NAME is not None:
+        return _ALIAS_TO_CODE, _CODE_TO_NAME
+
+    with _LOCK:
+        if _ALIAS_TO_CODE is not None and _CODE_TO_NAME is not None:
+            return _ALIAS_TO_CODE, _CODE_TO_NAME
+
+        alias_to_code: dict[str, str] = {}
+        code_to_name: dict[str, str] = {}
+
+        try:
+            raw = json.loads(LANGUAGE_DATA_PATH.read_text(encoding="utf-8"))
+        except OSError, ValueError:
+            logger.exception("Failed to load language data from %s", LANGUAGE_DATA_PATH)
+            raw = []
+
+        if not isinstance(raw, list):
+            logger.warning("Language data at %s is not a list", LANGUAGE_DATA_PATH)
+            raw = []
+
+        for item in raw:
+            if not isinstance(item, dict):
+                continue
+            code = str(item.get("code") or "").strip()
+            name = str(item.get("language") or "").strip()
+            if not code:
+                continue
+
+            code_to_name.setdefault(code, name or code)
+
+            for candidate in (code, name, *(item.get("aliases") or [])):
+                folded = _fold(str(candidate))
+                if folded and folded not in LANGUAGE_PLACEHOLDERS:
+                    alias_to_code.setdefault(folded, code)
+
+        _ALIAS_TO_CODE = alias_to_code
+        _CODE_TO_NAME = code_to_name
+        return alias_to_code, code_to_name
+
+
+def normalize_language(value: object) -> str | None:
+    """Resolve any known spelling of a language to its ISO 639-1 code.
+
+    Accepts a two-letter code, an ISO 639-2 three-letter code in either the
+    bibliographic or terminological form, or an English name. Returns None for
+    anything unrecognised or for the placeholders a source uses to say it does
+    not know, so callers can treat "no language" uniformly.
+    """
+    if value is None:
+        return None
+
+    folded = _fold(str(value))
+    if not folded or folded in LANGUAGE_PLACEHOLDERS:
+        return None
+
+    alias_to_code, _ = _load()
+    return alias_to_code.get(folded)
+
+
+def language_name(code: str | None) -> str | None:
+    """Return the English name for a language code, or None if unknown."""
+    if not code:
+        return None
+
+    _, code_to_name = _load()
+    return code_to_name.get(str(code).strip())
+
+
+def language_alias_map() -> dict[str, str]:
+    """Every known alias mapped to its code, for callers doing their own matching.
+
+    Direct Download scans free-text paths and needs the whole alias set up front
+    to look for, rather than resolving one candidate at a time.
+    """
+    alias_to_code, _ = _load()
+    return dict(alias_to_code)
+
+
+def supported_book_languages() -> list[dict[str, str]]:
+    """The selectable languages, as ``{"language": ..., "code": ...}``.
+
+    Aliases are an implementation detail of resolution, so they are left out of
+    what the settings dropdown and the API hand to clients.
+    """
+    _, code_to_name = _load()
+    return [{"language": name, "code": code} for code, name in code_to_name.items()]
+
+
+def known_language_codes() -> frozenset[str]:
+    """Every ISO 639-1 code the bundled language data defines."""
+    _, code_to_name = _load()
+    return frozenset(code_to_name)

shelfmark/core/models.py

@@ -108,6 +108,9 @@ class DownloadTask:
     retry_expected_hash: str | None = None  # Optional torrent hash used to match client downloads
     retry_ratio_limit: float | None = None  # Optional post-download seeding ratio
     retry_seeding_time_limit_minutes: int | None = None  # Optional post-download seeding time limit
+    retry_source_context: dict[str, Any] = field(
+        default_factory=dict
+    )  # Source-private context for retry/re-resolution
     can_retry_without_staged_source: bool = (
         True  # Whether the source can restart without a preserved staged file
     )
@@ -116,6 +119,7 @@ class DownloadTask:
     series_name: str | None = None
     series_position: float | None = None  # Float for novellas (e.g., 1.5)
     subtitle: str | None = None  # Book subtitle for naming templates
+    language: str | None = None  # Release language code for the {Language} template variable
 
     # Hardlinking support
     original_download_path: str | None = None  # Path in download client (for hardlinking)

shelfmark/core/naming.py

@@ -4,6 +4,7 @@ import re
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from shelfmark.core.languages import LANGUAGE_PLACEHOLDERS, normalize_language
 from shelfmark.core.logger import setup_logger
 
 if TYPE_CHECKING:
@@ -19,6 +20,7 @@ KNOWN_TOKENS = [
     "primarytitle",
     "originalname",
     "partnumber",
+    "language",
     "subtitle",
     "author",
     "series",
@@ -66,6 +68,33 @@ def format_series_position(position: str | float | None) -> str:
     return str(position)
 
 
+def normalize_language_code(language: str | None) -> str:
+    """Resolve a release language to the single spelling used in a path.
+
+    Sources report the same language in different shapes: "en", "eng", "English".
+    All of them have to collapse to one code, or the editions they identify end
+    up in separate folders, which is the collision this token exists to prevent.
+    Placeholder values render empty so `{ (Language)}` disappears entirely
+    rather than labelling a folder "(unknown)".
+
+    A language the bundled data does not know is kept, casefolded, rather than
+    dropped: it still separates editions, and it cannot collide with a resolved
+    code precisely because nothing resolves it.
+    """
+    if not language:
+        return ""
+
+    resolved = normalize_language(language)
+    if resolved is not None:
+        return resolved
+
+    normalized = " ".join(str(language).split()).strip().casefold()
+    if normalized in LANGUAGE_PLACEHOLDERS:
+        return ""
+
+    return normalized
+
+
 def derive_primary_title(title: str | None, subtitle: str | None) -> str:
     """Return the title without an explicit subtitle suffix when possible."""
     title_value = " ".join(str(title or "").split()).strip()
@@ -91,8 +120,7 @@ PAD_NUMBERS_PATTERN = re.compile(r"\d+")
 
 def natural_sort_key(path: str | Path) -> str:
     """Generate a sort key with padded numbers for natural sorting."""
-    filename = Path(path).name.lower()
-    return PAD_NUMBERS_PATTERN.sub(lambda m: m.group().zfill(9), filename)
+    return PAD_NUMBERS_PATTERN.sub(lambda m: m.group().zfill(9), str(path).lower())
 
 
 def assign_part_numbers(

shelfmark/core/oidc_routes.py

@@ -33,6 +33,11 @@ logger = setup_logger(__name__)
 oauth = OAuth()
 _RETURN_TO_SESSION_KEY = "oidc_return_to"
 _OIDC_CLIENT_ERRORS = (OAuthError, OSError, RuntimeError, TypeError, ValueError)
+_EMPTY_JWKS_MESSAGE = (
+    "Authentication failed: the identity provider returned no token signing keys "
+    "(empty JWKS). If you use Authentik, select a Signing Key in the provider "
+    "settings and try again."
+)
 
 
 class _ClaimsMappingLike(Protocol):
@@ -121,6 +126,17 @@ def _normalize_return_to(raw_return_to: object) -> str | None:
     return urlunsplit(("", "", path, parsed.query, parsed.fragment))
 
 
+def _idp_jwks_has_no_keys(client: Any) -> bool:
+    """Return True when the IdP's JWKS document verifiably contains no signing keys."""
+    try:
+        jwk_set = client.fetch_jwk_set(force=True)
+    except (*_OIDC_CLIENT_ERRORS, KeyError):
+        return False
+    if not isinstance(jwk_set, Mapping):
+        return False
+    return not jwk_set.get("keys")
+
+
 def _get_pending_return_to(*, clear: bool = False) -> str | None:
     """Read the pending post-login target from the session."""
     raw_return_to = (
@@ -274,6 +290,17 @@ def register_oidc_routes(app: Flask, user_db: UserDB) -> None:
                 return redirect(
                     _login_error_url(f"OIDC token claim validation failed: {claim_name}")
                 )
+            except KeyError, ValueError:
+                # An IdP serving an empty JWKS document (e.g. an Authentik provider
+                # with no Signing Key selected) surfaces as KeyError('keys') while
+                # importing the key set. Test Connection only validates discovery,
+                # so this is the first place the misconfiguration becomes visible.
+                if _idp_jwks_has_no_keys(client):
+                    logger.exception(
+                        "OIDC callback failed: the IdP JWKS document contains no signing keys"
+                    )
+                    return redirect(_login_error_url(_EMPTY_JWKS_MESSAGE))
+                raise
             claims = _normalize_claims(token.get("userinfo"))
 
             # If userinfo is missing or claims are too sparse, request it explicitly.
@@ -306,6 +333,12 @@ def register_oidc_routes(app: Flask, user_db: UserDB) -> None:
                 is_admin = admin_group in groups
 
             allow_email_link = bool(user_info.get("email")) and _is_email_verified(claims)
+            if user_info.get("email") and not allow_email_link:
+                logger.debug(
+                    "OIDC email %s is not marked verified by the IdP; skipping "
+                    "email-based account linking",
+                    user_info["email"],
+                )
             user = provision_oidc_user(
                 user_db,
                 user_info,

shelfmark/download/clients/__init__.py

@@ -325,6 +325,19 @@ class DownloadClient(ABC):
 
         """
 
+    def set_category(self, download_id: str, category: str) -> bool:
+        """Update a download's category or label when supported by the client.
+
+        Args:
+            download_id: The client-specific download ID.
+            category: Category or label to assign.
+
+        Returns:
+            True if the category was updated, otherwise False.
+
+        """
+        return False
+
     @abstractmethod
     def get_download_path(self, download_id: str) -> str | None:
         """Get the path where files were downloaded.
@@ -359,10 +372,13 @@ class DownloadClient(ABC):
 
 # Client registry: protocol -> list of client classes
 _CLIENTS: dict[str, list[type[DownloadClient]]] = {}
+ClientType = TypeVar("ClientType", bound=DownloadClient)
 _BUILTIN_CLIENT_MODULES = (
+    "shelfmark.download.clients.alldebrid",
     "shelfmark.download.clients.deluge",
     "shelfmark.download.clients.nzbget",
     "shelfmark.download.clients.qbittorrent",
+    "shelfmark.download.clients.realdebrid",
     "shelfmark.download.clients.rtorrent",
     "shelfmark.download.clients.sabnzbd",
     "shelfmark.download.clients.transmission",
@@ -383,7 +399,7 @@ def _ensure_builtin_clients_registered() -> None:
 
 def register_client(
     protocol: str,
-) -> Callable[[type[DownloadClient]], type[DownloadClient]]:
+) -> Callable[[type[ClientType]], type[ClientType]]:
     """Register a download client for a protocol.
 
     Multiple clients can be registered for the same protocol.
@@ -399,7 +415,7 @@ def register_client(
 
     """
 
-    def decorator(cls: type[DownloadClient]) -> type[DownloadClient]:
+    def decorator(cls: type[ClientType]) -> type[ClientType]:
         if protocol not in _CLIENTS:
             _CLIENTS[protocol] = []
         _CLIENTS[protocol].append(cls)

shelfmark/download/clients/alldebrid.py

@@ -0,0 +1,681 @@
+"""AllDebrid debrid service client for Shelfmark.
+
+Routes magnet links through the AllDebrid API (v4/v4.1) to download
+torrent content via AllDebrid's CDN infrastructure.
+"""
+
+from __future__ import annotations
+
+import shutil
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, ClassVar, NoReturn
+from urllib.parse import quote
+
+import requests
+
+from shelfmark.config.env import TMP_DIR
+from shelfmark.core.config import config
+from shelfmark.core.logger import setup_logger
+from shelfmark.download.clients import (
+    DownloadClient,
+    DownloadState,
+    DownloadStatus,
+    register_client,
+)
+from shelfmark.download.clients._coercion import config_text
+from shelfmark.download.http import download_url
+from shelfmark.download.network import get_ssl_verify
+
+logger = setup_logger(__name__)
+
+_API_BASE = "https://api.alldebrid.com/v4"
+_AGENT = "shelfmark"
+
+_ALLDEBRID_CLIENT_ERRORS = (
+    AttributeError,
+    OSError,
+    requests.exceptions.RequestException,
+    RuntimeError,
+    TypeError,
+    ValueError,
+)
+
+# AllDebrid magnet status codes (from API v4.1 documentation).
+_STATUS_DOWNLOADING = frozenset({0, 1, 2, 3})
+_STATUS_READY = 4
+
+# Timeouts and retry limits for API calls.
+_API_TIMEOUT = 30
+_STATUS_TIMEOUT = 15
+_DELAYED_POLL_INTERVAL = 5
+_DELAYED_POLL_MAX_ATTEMPTS = 12
+
+# File extensions recognised as book or audiobook content.
+_BOOK_EXTENSIONS = (
+    ".aac",
+    ".azw",
+    ".azw3",
+    ".cbr",
+    ".cbz",
+    ".djvu",
+    ".doc",
+    ".docx",
+    ".epub",
+    ".fb2",
+    ".flac",
+    ".lit",
+    ".m4a",
+    ".m4b",
+    ".mobi",
+    ".mp3",
+    ".ogg",
+    ".opus",
+    ".pdf",
+    ".rtf",
+    ".txt",
+    ".wma",
+)
+
+
+def _flatten_magnet_files(
+    entries: list[dict[str, Any]],
+    prefix: str = "",
+) -> list[dict[str, Any]]:
+    """Flatten AllDebrid's nested file tree into a list of file dicts.
+
+    AllDebrid returns files with ``"n"`` (name), ``"s"`` (size),
+    ``"l"`` (link), and ``"e"`` (children) keys.  Directories use
+    ``"e"`` to nest their contents.
+
+    Returns:
+        List of ``{"filename": ..., "size": ..., "link": ...}`` dicts.
+
+    """
+    flat: list[dict[str, Any]] = []
+    for entry in entries:
+        name = entry.get("n", "")
+        if "e" in entry:
+            flat.extend(
+                _flatten_magnet_files(entry["e"], prefix=f"{prefix}{name}/"),
+            )
+        elif entry.get("l"):
+            flat.append(
+                {
+                    "filename": f"{prefix}{name}",
+                    "size": entry.get("s", 0),
+                    "link": entry["l"],
+                }
+            )
+    return flat
+
+
+def _raise_runtime_error(message: str) -> NoReturn:
+    raise RuntimeError(message)
+
+
+@dataclass
+class _DownloadState:
+    """Internal mutable state for an in-progress AllDebrid download."""
+
+    magnet_id: str
+    name: str
+    target_dir: Path
+    phase: str = "uploading"
+    error_message: str | None = None
+    progress: float = 0.0
+    download_thread: threading.Thread | None = None
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+
+@register_client("torrent")
+class AllDebridClient(DownloadClient):
+    """AllDebrid debrid service client.
+
+    Downloads torrent content by uploading magnet links to AllDebrid,
+    waiting for the torrent to complete on their servers, then fetching
+    the resulting files via direct HTTP download from AllDebrid's CDN.
+
+    API documentation: https://docs.alldebrid.com/
+    """
+
+    protocol = "torrent"
+    name = "alldebrid"
+
+    _downloads: ClassVar[dict[str, _DownloadState]] = {}
+    _downloads_lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._api_key = config_text(config.get("ALLDEBRID_API_KEY", ""))
+
+    def _auth_headers(self) -> dict[str, str]:
+        """Return Authorization header dict for API requests."""
+        return {"Authorization": f"Bearer {self._api_key}"}
+
+    # ------------------------------------------------------------------
+    # DownloadClient interface
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def is_configured() -> bool:
+        """Return True when AllDebrid is selected and an API key exists."""
+        client = config_text(config.get("PROWLARR_TORRENT_CLIENT", ""))
+        api_key = config_text(config.get("ALLDEBRID_API_KEY", ""))
+        return client == "alldebrid" and bool(api_key)
+
+    def test_connection(self) -> tuple[bool, str]:
+        """Validate the API key and check Premium subscription status."""
+        if not self._api_key:
+            return False, "AllDebrid API Key is required"
+        try:
+            url = f"{_API_BASE}/user"
+            resp = requests.get(
+                url,
+                headers=self._auth_headers(),
+                timeout=_STATUS_TIMEOUT,
+                verify=get_ssl_verify(url),
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            if data.get("status") != "success":
+                err = data.get("error", {}).get("message", "API error")
+                return False, f"AllDebrid error: {err}"
+            user = data.get("data", {}).get("user", {})
+            username = user.get("username", "Unknown")
+            if not user.get("isPremium", False):
+                return (
+                    False,
+                    f"AllDebrid user '{username}' does not have a Premium subscription",
+                )
+        except _ALLDEBRID_CLIENT_ERRORS as e:
+            return False, f"Connection failed: {e}"
+        else:
+            return True, f"Connected to AllDebrid as '{username}' (Premium)"
+
+    def add_download(
+        self,
+        url: str,
+        name: str,
+        category: str | None = None,
+        expected_hash: str | None = None,
+        **kwargs: object,
+    ) -> str:
+        """Upload a magnet link to AllDebrid and return the magnet ID."""
+        if not self._api_key:
+            msg = "AllDebrid API key is not configured"
+            raise RuntimeError(msg)
+
+        magnet_link = url
+        if not magnet_link.startswith("magnet:") and expected_hash:
+            magnet_link = f"magnet:?xt=urn:btih:{expected_hash}"
+
+        api_url = f"{_API_BASE}/magnet/upload"
+        try:
+            resp = requests.post(
+                api_url,
+                headers=self._auth_headers(),
+                data={"magnets[]": magnet_link},
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(api_url),
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            if data.get("status") != "success":
+                code = data.get("error", {}).get("code", "UNKNOWN")
+                msg = f"AllDebrid upload failed: {code}"
+                _raise_runtime_error(msg)
+
+            magnets = data.get("data", {}).get("magnets", [])
+            if not magnets:
+                msg = "No magnet returned from AllDebrid"
+                _raise_runtime_error(msg)
+
+            info = magnets[0]
+            if info.get("error"):
+                code = info["error"].get("code", "UNKNOWN")
+                msg = f"AllDebrid magnet error: {code}"
+                _raise_runtime_error(msg)
+
+            magnet_id = str(info.get("id", ""))
+            if not magnet_id:
+                msg = "No magnet ID returned from AllDebrid"
+                _raise_runtime_error(msg)
+
+            target_dir = TMP_DIR / f"alldebrid_{magnet_id}"
+            target_dir.mkdir(parents=True, exist_ok=True)
+
+            state = _DownloadState(
+                magnet_id=magnet_id,
+                name=name,
+                target_dir=target_dir,
+                phase="waiting_ad",
+            )
+            with self._downloads_lock:
+                self._downloads[magnet_id] = state
+
+            logger.info(
+                "Added torrent to AllDebrid: ID %s (%s)",
+                magnet_id,
+                name,
+            )
+
+        except Exception:
+            logger.exception("Failed to upload magnet to AllDebrid")
+            raise
+
+        else:
+            return magnet_id
+
+    def get_status(self, download_id: str) -> DownloadStatus:
+        """Poll AllDebrid for magnet status and drive the download."""
+        state = self._ensure_state(download_id)
+
+        # Return cached terminal / in-flight states immediately.
+        with state.lock:
+            if state.phase == "error":
+                return DownloadStatus.error(
+                    state.error_message or "AllDebrid error",
+                )
+            if state.phase == "complete":
+                return DownloadStatus(
+                    progress=100.0,
+                    state=DownloadState.COMPLETE,
+                    message="Complete",
+                    complete=True,
+                    file_path=str(state.target_dir),
+                )
+            if state.phase == "downloading_http":
+                return DownloadStatus(
+                    progress=state.progress,
+                    state=DownloadState.DOWNLOADING,
+                    message="Downloading files via HTTP...",
+                    complete=False,
+                    file_path=None,
+                )
+
+        # Ask AllDebrid for the current magnet status.
+        try:
+            status_url = f"{_API_BASE.replace('/v4', '/v4.1')}/magnet/status"
+            resp = requests.post(
+                status_url,
+                headers=self._auth_headers(),
+                data={"id": download_id},
+                timeout=_STATUS_TIMEOUT,
+                verify=get_ssl_verify(status_url),
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            if data.get("status") != "success":
+                err = data.get("error", {}).get("message", "Status failed")
+                return DownloadStatus.error(
+                    f"AllDebrid status error: {err}",
+                )
+
+            mag = self._extract_magnet_info(data)
+            return self._handle_magnet_status(mag, state)
+
+        except Exception as e:
+            logger.exception(
+                "Error checking AllDebrid status for %s",
+                download_id,
+            )
+            return DownloadStatus.error(str(e))
+
+    def remove(
+        self,
+        download_id: str,
+        *,
+        delete_files: bool = False,
+    ) -> bool:
+        """Delete the magnet from AllDebrid and clean up local files."""
+        try:
+            url = f"{_API_BASE}/magnet/delete"
+            requests.post(
+                url,
+                headers=self._auth_headers(),
+                data={"id": download_id},
+                timeout=_STATUS_TIMEOUT,
+                verify=get_ssl_verify(url),
+            )
+        except _ALLDEBRID_CLIENT_ERRORS as e:
+            logger.warning("Failed to delete magnet from AllDebrid: %s", e)
+
+        with self._downloads_lock:
+            state = self._downloads.pop(download_id, None)
+
+        if state and state.target_dir.exists():
+            shutil.rmtree(state.target_dir, ignore_errors=True)
+        return True
+
+    def get_download_path(self, download_id: str) -> str | None:
+        """Return the local directory containing downloaded files."""
+        with self._downloads_lock:
+            state = self._downloads.get(download_id)
+        if state and state.phase == "complete":
+            return str(state.target_dir)
+        target_dir = TMP_DIR / f"alldebrid_{download_id}"
+        if target_dir.exists():
+            return str(target_dir)
+        return None
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _ensure_state(self, download_id: str) -> _DownloadState:
+        """Get or create download state for the given magnet ID."""
+        with self._downloads_lock:
+            state = self._downloads.get(download_id)
+        if state:
+            return state
+
+        target_dir = TMP_DIR / f"alldebrid_{download_id}"
+        state = _DownloadState(
+            magnet_id=download_id,
+            name=f"Download {download_id}",
+            target_dir=target_dir,
+            phase="waiting_ad",
+        )
+        with self._downloads_lock:
+            self._downloads[download_id] = state
+        return state
+
+    @staticmethod
+    def _extract_magnet_info(data: dict[str, Any]) -> dict[str, Any]:
+        """Extract magnet info dict from a status API response."""
+        mag_data = data.get("data", {}).get("magnets", {})
+        if isinstance(mag_data, list) and mag_data:
+            return mag_data[0]
+        if isinstance(mag_data, dict):
+            return mag_data
+        return {}
+
+    def _handle_magnet_status(
+        self,
+        mag: dict[str, Any],
+        state: _DownloadState,
+    ) -> DownloadStatus:
+        """Map AllDebrid magnet status to a DownloadStatus."""
+        status_code = mag.get("statusCode")
+
+        if status_code in _STATUS_DOWNLOADING:
+            size = mag.get("size", 0)
+            downloaded = mag.get("downloaded", 0)
+            pct = (downloaded / size * 100.0) if size > 0 else 0.0
+            return DownloadStatus(
+                progress=pct * 0.5,
+                state=DownloadState.DOWNLOADING,
+                message=(f"AllDebrid downloading torrent ({mag.get('filename', state.name)})"),
+                complete=False,
+                file_path=None,
+                download_speed=mag.get("downloadSpeed", 0),
+            )
+
+        if status_code == _STATUS_READY or mag.get("ready", False):
+            self._maybe_start_download_thread(state)
+            return DownloadStatus(
+                progress=50.0,
+                state=DownloadState.DOWNLOADING,
+                message="AllDebrid ready, retrieving files...",
+                complete=False,
+                file_path=None,
+            )
+
+        # Terminal error from AllDebrid.
+        error_txt = mag.get("error", {}).get("message") or f"AllDebrid status code {status_code}"
+        with state.lock:
+            state.phase = "error"
+            state.error_message = error_txt
+        return DownloadStatus.error(error_txt)
+
+    def _maybe_start_download_thread(self, state: _DownloadState) -> None:
+        """Spawn a background thread to unlock and download files."""
+        with state.lock:
+            already_running = state.phase in (
+                "unlocking",
+                "downloading_http",
+                "complete",
+            )
+            thread_alive = state.download_thread is not None and state.download_thread.is_alive()
+            if already_running or thread_alive:
+                return
+            state.phase = "unlocking"
+            t = threading.Thread(
+                target=self._process_and_download,
+                args=(state,),
+                daemon=True,
+            )
+            state.download_thread = t
+            t.start()
+
+    # ------------------------------------------------------------------
+    # Link unlocking
+    # ------------------------------------------------------------------
+
+    def _unlock_file_link(self, link: str) -> str:
+        """Resolve an AllDebrid file link to a direct CDN download URL.
+
+        AllDebrid's ``/v4/magnet/files`` endpoint returns virtual links
+        (``alldebrid.com/f/...``) that must be converted to direct CDN
+        URLs via ``/v4/link/unlock``.
+
+        Strategy:
+            1. If the link is already a CDN URL (``/dl/``), return it.
+            2. ``POST /v4/link/unlock`` with Bearer auth (primary).
+            3. ``GET /v4/link/unlock`` with query parameters (fallback).
+            4. Append ``apikey=`` to ``alldebrid.com/f/`` links
+               (last-resort fallback for ghost-cached torrents).
+
+        """
+        # 1. Already a direct CDN link.
+        if "/dl/" in link:
+            return link
+
+        headers = self._auth_headers()
+        unlock_url = f"{_API_BASE}/link/unlock"
+        err_msg = "Unknown unlock error"
+
+        # 2. POST unlock (primary method).
+        try:
+            resp = requests.post(
+                unlock_url,
+                headers=headers,
+                data={"link": link},
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(unlock_url),
+            )
+            if resp.status_code == 200:
+                body = resp.json()
+                if body.get("status") == "success":
+                    direct = self._resolve_unlock_data(
+                        body.get("data", {}),
+                        headers,
+                    )
+                    if direct:
+                        return direct
+                err_msg = body.get("error", {}).get(
+                    "message",
+                    "Unlock failed",
+                )
+        except _ALLDEBRID_CLIENT_ERRORS as e:
+            logger.debug("POST unlock exception: %s", e)
+
+        # 3. GET unlock fallback with URL-encoded link.
+        try:
+            encoded = quote(link, safe="")
+            get_url = (
+                f"{_API_BASE}/link/unlock?agent={_AGENT}&apikey={self._api_key}&link={encoded}"
+            )
+            resp = requests.get(
+                get_url,
+                headers=headers,
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(get_url),
+            )
+            if resp.status_code == 200:
+                body = resp.json()
+                if body.get("status") == "success":
+                    direct = body.get("data", {}).get("link")
+                    if direct:
+                        return direct
+                err_msg = body.get("error", {}).get("message", err_msg)
+        except _ALLDEBRID_CLIENT_ERRORS as e:
+            logger.debug("GET unlock exception: %s", e)
+
+        # 4. Last-resort: append apikey to alldebrid.com/f/ links.
+        if "alldebrid.com/f/" in link:
+            logger.info(
+                "Using apikey fallback for AllDebrid file link: %s",
+                link,
+            )
+            if "apikey=" not in link:
+                sep = "&" if "?" in link else "?"
+                return f"{link}{sep}apikey={self._api_key}"
+            return link
+
+        logger.error(
+            "AllDebrid unlock failed for '%s': %s",
+            link,
+            err_msg,
+        )
+        msg = f"AllDebrid unlock failed: {err_msg}"
+        raise RuntimeError(msg)
+
+    def _resolve_unlock_data(
+        self,
+        data: dict[str, Any],
+        headers: dict[str, str],
+    ) -> str | None:
+        """Extract the direct link from unlock response data.
+
+        Handles the *delayed link* flow where AllDebrid returns a
+        ``delayed`` ID instead of an immediate download link.
+        """
+        # Delayed link: poll until the CDN file is ready.
+        if "delayed" in data:
+            delayed_id = data["delayed"]
+            logger.info(
+                "AllDebrid link delayed (ID %s), polling...",
+                delayed_id,
+            )
+            delayed_url = f"{_API_BASE}/link/delayed"
+            for _ in range(_DELAYED_POLL_MAX_ATTEMPTS):
+                time.sleep(_DELAYED_POLL_INTERVAL)
+                try:
+                    resp = requests.post(
+                        delayed_url,
+                        headers=headers,
+                        data={"id": delayed_id},
+                        timeout=_STATUS_TIMEOUT,
+                        verify=get_ssl_verify(delayed_url),
+                    )
+                    if resp.status_code != 200:
+                        continue
+                    body = resp.json()
+                    d = body.get("data", {})
+                    if body.get("status") == "success" and d.get("status") == 2 and d.get("link"):
+                        return d["link"]
+                except _ALLDEBRID_CLIENT_ERRORS as e:
+                    logger.debug("Delayed poll exception: %s", e)
+
+        return data.get("link")
+
+    # ------------------------------------------------------------------
+    # File download pipeline
+    # ------------------------------------------------------------------
+
+    def _process_and_download(self, state: _DownloadState) -> None:
+        """Fetch the file list, unlock links, and download via HTTP.
+
+        Runs in a background thread spawned by ``_maybe_start_download_thread``.
+        """
+        try:
+            files = self._fetch_file_list(state.magnet_id)
+            relevant = [f for f in files if f["filename"].lower().endswith(_BOOK_EXTENSIONS)]
+            if not relevant:
+                relevant = files
+
+            with state.lock:
+                state.phase = "downloading_http"
+
+            total = len(relevant)
+            for idx, file_info in enumerate(relevant):
+                direct_link = self._unlock_file_link(file_info["link"])
+
+                rel_path = Path(file_info["filename"])
+                dest = state.target_dir / rel_path
+                dest.parent.mkdir(parents=True, exist_ok=True)
+
+                logger.info(
+                    "Downloading AllDebrid file %d/%d: %s",
+                    idx + 1,
+                    total,
+                    rel_path,
+                )
+
+                buf = download_url(
+                    direct_link,
+                    referer="https://alldebrid.com/",
+                )
+                if not buf:
+                    msg = f"Failed to download from {direct_link}"
+                    _raise_runtime_error(msg)
+
+                with dest.open("wb") as fh:
+                    fh.write(buf.getvalue())
+
+                with state.lock:
+                    state.progress = 50.0 + (idx + 1) / total * 50.0
+
+            with state.lock:
+                state.phase = "complete"
+                state.progress = 100.0
+
+            logger.info(
+                "AllDebrid download complete for ID %s at %s",
+                state.magnet_id,
+                state.target_dir,
+            )
+
+        except Exception:
+            logger.exception(
+                "Error in AllDebrid download for ID %s",
+                state.magnet_id,
+            )
+            with state.lock:
+                state.phase = "error"
+                state.error_message = str(
+                    state.error_message or "Download failed",
+                )
+
+    def _fetch_file_list(
+        self,
+        magnet_id: str,
+    ) -> list[dict[str, Any]]:
+        """Retrieve and flatten the file tree for a magnet."""
+        url = f"{_API_BASE}/magnet/files"
+        resp = requests.post(
+            url,
+            headers=self._auth_headers(),
+            data={"id[]": magnet_id},
+            timeout=_API_TIMEOUT,
+            verify=get_ssl_verify(url),
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        if data.get("status") != "success":
+            msg = f"Failed to list magnet files: {data.get('error')}"
+            raise RuntimeError(msg)
+
+        magnets = data.get("data", {}).get("magnets", [])
+        if not magnets:
+            msg = "No magnet files returned"
+            raise RuntimeError(msg)
+
+        files = _flatten_magnet_files(magnets[0].get("files", []))
+        if not files:
+            msg = "No files found in torrent"
+            raise RuntimeError(msg)
+        return files

shelfmark/download/clients/base_handler.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import errno
+import math
 import shutil
 import time
 from abc import ABC, abstractmethod
@@ -55,6 +56,19 @@ SECONDS_PER_HOUR = 3600
 # How long to wait for completed files to appear (seconds)
 COMPLETED_PATH_RETRY_INTERVAL = 5
 COMPLETED_PATH_MAX_ATTEMPTS = 12  # 12 attempts * 5s = 60s grace period
+COMPLETED_PATH_TIMEOUT_SETTING = "DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT"
+COMPLETED_PATH_TIMEOUT_MAX_SECONDS = 3600
+_RETRYABLE_COMPLETED_PATH_ERRNOS = frozenset(
+    code
+    for code in (
+        errno.ENOENT,
+        getattr(errno, "ESTALE", None),
+        getattr(errno, "EAGAIN", None),
+        getattr(errno, "EBUSY", None),
+        getattr(errno, "ETIMEDOUT", None),
+    )
+    if code is not None
+)
 
 
 @dataclass(frozen=True)
@@ -69,6 +83,39 @@ class DownloadRequest:
     ratio_limit: float | None = None
 
 
+@dataclass(frozen=True)
+class _CompletedPathResolution:
+    path: Path | None
+    error: str | None
+    retryable: bool
+
+
+def _coerce_completed_path_timeout_seconds(value: object, default: float) -> float:
+    if isinstance(value, bool) or value is None:
+        return default
+    if isinstance(value, (int, float)):
+        parsed = float(value)
+    elif isinstance(value, str):
+        try:
+            parsed = float(value.strip())
+        except ValueError:
+            return default
+    else:
+        return default
+
+    if not math.isfinite(parsed) or parsed < 0:
+        return default
+    return min(parsed, float(COMPLETED_PATH_TIMEOUT_MAX_SECONDS))
+
+
+def _is_retryable_completed_path_probe(error: OSError | None) -> bool:
+    return error is not None and error.errno in _RETRYABLE_COMPLETED_PATH_ERRNOS
+
+
+def _path_needs_mapping(path: str) -> bool:
+    return (len(path) >= WINDOWS_DRIVE_PREFIX_LENGTH and path[1] == ":") or "\\" in path
+
+
 def _diagnose_path_issue(path: str) -> str:
     """Analyze a path and return diagnostic hints for common issues.
 
@@ -167,6 +214,23 @@ class ExternalClientHandler(DownloadHandler, ABC):
         """Maximum attempts when waiting for completed files."""
         return COMPLETED_PATH_MAX_ATTEMPTS
 
+    def _completed_path_timeout_seconds(self) -> float:
+        """Total time to wait for completed files to appear on disk."""
+        fallback = self._completed_path_retry_interval() * self._completed_path_max_attempts()
+        configured = config.get(COMPLETED_PATH_TIMEOUT_SETTING, fallback)
+        return _coerce_completed_path_timeout_seconds(configured, fallback)
+
+    def _refresh_download_request_after_add_failure(
+        self,
+        *,
+        task: DownloadTask,
+        request: DownloadRequest,
+        error: Exception,
+        status_callback: Callable[[str, str | None], None],
+    ) -> DownloadRequest | None:
+        """Give source handlers one chance to refresh stale resolved download data."""
+        return None
+
     def _get_category_for_task(self, client: DownloadClient, task: DownloadTask) -> str | None:
         """Get audiobook category if configured and applicable, else None for default."""
         if not is_audiobook(task.content_type):
@@ -220,17 +284,47 @@ class ExternalClientHandler(DownloadHandler, ABC):
                 )
 
         elif protocol == "torrent":
-            if config.get("PROWLARR_TORRENT_ACTION", "keep") != "remove":
+            torrent_action = config.get("PROWLARR_TORRENT_ACTION", "keep")
+            if torrent_action == "remove":
+                try:
+                    client.remove(download_id, delete_files=False)
+                except _CLIENT_CLEANUP_ERRORS as e:
+                    logger.warning(
+                        "Failed to remove torrent %s from %s: %s",
+                        download_id,
+                        getattr(client, "name", "client"),
+                        e,
+                    )
                 return
+
+            if torrent_action != "change_category":
+                return
+
+            post_import_category = normalize_optional_text(
+                config.get("PROWLARR_TORRENT_POST_IMPORT_CATEGORY", "")
+            )
+            if post_import_category is None:
+                return
+
             try:
-                client.remove(download_id, delete_files=False)
+                category_updated = client.set_category(download_id, post_import_category)
             except _CLIENT_CLEANUP_ERRORS as e:
                 logger.warning(
-                    "Failed to remove torrent %s from %s: %s",
+                    "Failed to set post-import category for torrent %s in %s: %s",
                     download_id,
                     getattr(client, "name", "client"),
                     e,
                 )
+                return
+
+            if not category_updated:
+                # Clients that cannot label torrents (debrid services) return False here,
+                # and the ones that can already log the specific failure themselves.
+                logger.debug(
+                    "Post-import category not applied to torrent %s in %s",
+                    download_id,
+                    getattr(client, "name", "client"),
+                )
 
     def _remove_usenet_download(
         self,
@@ -387,6 +481,21 @@ class ExternalClientHandler(DownloadHandler, ABC):
         log_details: bool,
     ) -> tuple[Path | None, str | None]:
         """Resolve and validate the completed download path once."""
+        result = self._resolve_download_path_once_detailed(
+            client,
+            download_id,
+            log_details=log_details,
+        )
+        return result.path, result.error
+
+    def _resolve_download_path_once_detailed(
+        self,
+        client: DownloadClient,
+        download_id: str,
+        *,
+        log_details: bool,
+    ) -> _CompletedPathResolution:
+        """Resolve and validate a completed path, including retryability."""
         try:
             raw_path = client.get_download_path(download_id)
         except Exception as e:
@@ -402,7 +511,7 @@ class ExternalClientHandler(DownloadHandler, ABC):
                 logger.debug(
                     "Failed to resolve download path for %s %s: %s", client.name, download_id, e
                 )
-            return None, message
+            return _CompletedPathResolution(None, message, retryable=False)
 
         if not raw_path:
             message = (
@@ -417,7 +526,7 @@ class ExternalClientHandler(DownloadHandler, ABC):
                 logger.debug(
                     "Download client returned empty path for %s %s", client.name, download_id
                 )
-            return None, message
+            return _CompletedPathResolution(None, message, retryable=False)
 
         from shelfmark.core.path_mappings import (
             get_client_host_identifier,
@@ -457,7 +566,7 @@ class ExternalClientHandler(DownloadHandler, ABC):
                     logger.error(failure_log, *failure_args)
                 else:
                     logger.debug(failure_log, *failure_args)
-                return None, message
+                return _CompletedPathResolution(None, message, retryable=False)
 
             remapped_exists, remapped_error = _probe_completed_path(remapped)
 
@@ -480,7 +589,7 @@ class ExternalClientHandler(DownloadHandler, ABC):
                     source_path_obj,
                     remapped,
                 )
-                return remapped, None
+                return _CompletedPathResolution(remapped, None, retryable=False)
 
             message = (
                 f"Remapped path '{remapped}' does not exist. "
@@ -499,7 +608,11 @@ class ExternalClientHandler(DownloadHandler, ABC):
                 logger.error(failure_log, *failure_args)
             else:
                 logger.debug(failure_log, *failure_args)
-            return None, message
+            return _CompletedPathResolution(
+                None,
+                message,
+                retryable=_is_retryable_completed_path_probe(remapped_error),
+            )
 
         source_exists, source_error = _probe_completed_path(source_path_obj)
 
@@ -522,7 +635,7 @@ class ExternalClientHandler(DownloadHandler, ABC):
                     download_id,
                     source_path_obj,
                 )
-            return source_path_obj, None
+            return _CompletedPathResolution(source_path_obj, None, retryable=False)
 
         hint = _diagnose_path_issue(raw_path)
         if mappings:
@@ -555,7 +668,12 @@ class ExternalClientHandler(DownloadHandler, ABC):
             logger.error(failure_log, *failure_args)
         else:
             logger.debug(failure_log, *failure_args)
-        return None, message
+        return _CompletedPathResolution(
+            None,
+            message,
+            retryable=not _path_needs_mapping(raw_path)
+            and _is_retryable_completed_path_probe(source_error),
+        )
 
     def _wait_for_completed_path(
         self,
@@ -567,23 +685,37 @@ class ExternalClientHandler(DownloadHandler, ABC):
     ) -> tuple[Path | None, str | None]:
         """Wait briefly for completed files to appear on disk."""
         last_error: str | None = None
-        max_attempts = self._completed_path_max_attempts()
         retry_interval = self._completed_path_retry_interval()
+        timeout_seconds = self._completed_path_timeout_seconds()
+        if retry_interval <= 0 or timeout_seconds <= 0:
+            max_attempts = 1
+        else:
+            max_attempts = int(math.ceil(timeout_seconds / retry_interval)) + 1
 
         for attempt in range(1, max_attempts + 1):
             if cancel_flag and cancel_flag.is_set():
                 return None, last_error
 
             log_details = attempt == max_attempts
-            resolved_path, error = self._resolve_download_path_once(
+            result = self._resolve_download_path_once_detailed(
                 client,
                 download_id,
                 log_details=log_details,
             )
-            if resolved_path:
-                return resolved_path, None
+            if result.path:
+                return result.path, None
 
-            last_error = error
+            last_error = result.error
+
+            if not result.retryable:
+                if not log_details:
+                    logger.error(
+                        "Completed path resolution is not retryable for %s (%s): %s",
+                        client.name,
+                        download_id,
+                        last_error,
+                    )
+                return None, last_error
 
             if attempt < max_attempts:
                 status_callback("locating", "Waiting for completed files...")
@@ -700,20 +832,38 @@ class ExternalClientHandler(DownloadHandler, ABC):
                 status_callback("downloading", "Resuming existing download")
             else:
                 # No existing download - add new
-                status_callback("resolving", f"Sending to {client.name}")
-                try:
-                    download_id = client.add_download(
-                        url=request.url,
-                        name=request.release_name,
-                        category=category,
-                        expected_hash=request.expected_hash,
-                        seeding_time_limit=request.seeding_time_limit,
-                        ratio_limit=request.ratio_limit,
-                    )
-                except Exception as e:
-                    logger.exception("Failed to add to %s", client.name)
-                    status_callback("error", f"Failed to add to {client.name}: {e}")
-                    return None
+                refresh_attempted = False
+                while True:
+                    status_callback("resolving", f"Sending to {client.name}")
+                    try:
+                        download_id = client.add_download(
+                            url=request.url,
+                            name=request.release_name,
+                            category=category,
+                            expected_hash=request.expected_hash,
+                            seeding_time_limit=request.seeding_time_limit,
+                            ratio_limit=request.ratio_limit,
+                        )
+                    except Exception as e:
+                        if not refresh_attempted:
+                            refresh_attempted = True
+                            refreshed_request = self._refresh_download_request_after_add_failure(
+                                task=task,
+                                request=request,
+                                error=e,
+                                status_callback=status_callback,
+                            )
+                            if (
+                                refreshed_request is not None
+                                and refreshed_request.protocol == request.protocol
+                            ):
+                                request = refreshed_request
+                                continue
+
+                        logger.exception("Failed to add to %s", client.name)
+                        status_callback("error", f"Failed to add to {client.name}: {e}")
+                        return None
+                    break
 
                 logger.info(
                     "Added to %s: %s for '%s'", client.name, download_id, request.release_name

shelfmark/download/clients/deluge.py

@@ -227,10 +227,10 @@ class DelugeClient(DownloadClient):
 
         return self._rpc_call("daemon.info")
 
-    def _try_set_label(self, torrent_id: str, label: str) -> None:
+    def _try_set_label(self, torrent_id: str, label: str) -> bool:
         """Best-effort label assignment (requires Deluge Label plugin)."""
         if not label:
-            return
+            return False
 
         try:
             # label.add will error if the plugin is unavailable or the label exists.
@@ -240,6 +240,9 @@ class DelugeClient(DownloadClient):
             self._rpc_call("label.set_torrent", torrent_id, label)
         except _DELUGE_CLIENT_ERRORS as e:
             logger.debug("Could not set Deluge label '%s' for %s: %s", label, torrent_id, e)
+            return False
+        else:
+            return True
 
     @staticmethod
     def is_configured() -> bool:
@@ -277,7 +280,10 @@ class DelugeClient(DownloadClient):
 
             torrent_info = extract_torrent_info(url, expected_hash=expected_hash)
             if not torrent_info.is_magnet and not torrent_info.torrent_data:
-                _raise_runtime_error("Failed to fetch torrent file")
+                message = "Failed to fetch torrent file"
+                if torrent_info.fetch_error:
+                    message = f"{message}: {torrent_info.fetch_error}"
+                _raise_runtime_error(message)
 
             options: dict[str, Any] = {}
             if self._download_dir:
@@ -419,6 +425,15 @@ class DelugeClient(DownloadClient):
         else:
             return False
 
+    def set_category(self, download_id: str, category: str) -> bool:
+        """Assign a label to a torrent using Deluge's Label plugin."""
+        try:
+            self._ensure_connected()
+            return self._try_set_label(download_id, category)
+        except _DELUGE_CLIENT_ERRORS as e:
+            self._log_error("set_category", e)
+            return False
+
     def get_download_path(self, download_id: str) -> str | None:
         """Return the resolved download path for a Deluge torrent."""
         try:

shelfmark/download/clients/qbittorrent.py

@@ -182,15 +182,15 @@ class QBittorrentClient(DownloadClient):
         params = {"hash": torrent_hash}
 
         try:
-            self._client.auth_log_in()
+            self._ensure_authenticated()
             response = self._client._session.get(url, params=params, timeout=10)
 
             # Re-authenticate and retry once on 403
-            if response.status_code == _HTTP_STATUS_FORBIDDEN:
+            if response.status_code == _HTTP_STATUS_FORBIDDEN and self._can_reauthenticate:
                 logger.debug(
                     "qBittorrent returned 403 for properties; re-authenticating and retrying"
                 )
-                self._client.auth_log_in()
+                self._ensure_authenticated()
                 response = self._client._session.get(url, params=params, timeout=10)
 
             if response.status_code == _HTTP_STATUS_FORBIDDEN:
@@ -244,6 +244,7 @@ class QBittorrentClient(DownloadClient):
 
         username = config_text(config.get("QBITTORRENT_USERNAME", ""))
         password = config_text(config.get("QBITTORRENT_PASSWORD", ""))
+        self._api_key = config_text(config.get("QBITTORRENT_API_KEY", ""))
 
         # qbittorrent-api accepts either a full URL or host:port; prefer the normalized URL
         # for consistency.
@@ -251,14 +252,30 @@ class QBittorrentClient(DownloadClient):
             host=self._base_url,
             username=username,
             password=password,
+            api_key=self._api_key or None,
             VERIFY_WEBUI_CERTIFICATE=get_ssl_verify(self._base_url),
         )
         self._category = config_text(config.get("QBITTORRENT_CATEGORY", "books"))
         self._download_dir = config_text(config.get("QBITTORRENT_DOWNLOAD_DIR", ""))
         self._tags = _normalize_tags(config.get("QBITTORRENT_TAG", []))
 
+    @property
+    def _can_reauthenticate(self) -> bool:
+        """Whether a 403 is worth retrying; a bearer token cannot be refreshed like a session."""
+        return not self._api_key
+
+    def _ensure_authenticated(self) -> None:
+        """Authenticate the underlying HTTP session before it is used directly.
+
+        API keys (qBittorrent 5.2.0+) are sent as a bearer header on every request and
+        have no login endpoint, so there is no session to establish up front.
+        """
+        if self._api_key:
+            return
+        self._client.auth_log_in()
+
     def _get_torrents_info(
-        self, torrent_hash: str | None = None
+        self, torrent_hash: str | None = None, category: str | None = None
     ) -> tuple[list[SimpleNamespace], str | None]:
         """Get torrent info using GET.
 
@@ -267,6 +284,7 @@ class QBittorrentClient(DownloadClient):
         - Keep "API/auth/connect" errors distinct from "torrent missing".
         - If a hash-specific query returns empty, fall back to listing by category
           and matching locally.
+        - Without a hash, `category` narrows the listing to that category.
 
         Returns:
             (torrents, error_message)
@@ -275,8 +293,7 @@ class QBittorrentClient(DownloadClient):
         url = f"{self._base_url}/api/v2/torrents/info"
 
         def do_request(params: dict[str, str]) -> requests.Response:
-            # Ensure session is authenticated before using it directly
-            self._client.auth_log_in()
+            self._ensure_authenticated()
             return self._client._session.get(url, params=params, timeout=10)
 
         def parse_response(
@@ -284,9 +301,9 @@ class QBittorrentClient(DownloadClient):
             *,
             request_params: dict[str, str],
         ) -> tuple[list[SimpleNamespace], str | None]:
-            if response.status_code == _HTTP_STATUS_FORBIDDEN:
+            if response.status_code == _HTTP_STATUS_FORBIDDEN and self._can_reauthenticate:
                 logger.debug("qBittorrent returned 403; re-authenticating and retrying")
-                self._client.auth_log_in()
+                self._ensure_authenticated()
                 response = self._client._session.get(url, params=request_params, timeout=10)
 
             if response.status_code == _HTTP_STATUS_FORBIDDEN:
@@ -301,6 +318,8 @@ class QBittorrentClient(DownloadClient):
             primary_params: dict[str, str] = {}
             if torrent_hash:
                 primary_params["hashes"] = torrent_hash
+            elif category:
+                primary_params["category"] = category
 
             response = do_request(primary_params)
             torrents, error = parse_response(response, request_params=primary_params)
@@ -358,6 +377,44 @@ class QBittorrentClient(DownloadClient):
         else:
             return torrents, None
 
+    def _list_category_hashes(self, category: str | None) -> set[str] | None:
+        """Snapshot the hashes qBittorrent currently reports for a category."""
+        torrents, error = self._get_torrents_info(category=category)
+        if error:
+            logger.debug("Could not snapshot qBittorrent torrents: %s", error)
+            return None
+        return {str(torrent.hash).lower() for torrent in torrents if getattr(torrent, "hash", None)}
+
+    def _discover_added_torrent_hash(
+        self,
+        name: str,
+        category: str | None,
+        known_hashes: set[str] | None,
+    ) -> str | None:
+        """Recover the hash of a torrent that was added without a known info_hash.
+
+        A `known_hashes` of None means the pre-add snapshot failed, so only a
+        torrent matching the requested rename can identify the new arrival.
+        """
+        for _ in range(20):
+            torrents, error = self._get_torrents_info(category=category)
+            if error:
+                logger.debug("qBittorrent hash discovery: %s", error)
+            else:
+                new_torrents = [
+                    torrent
+                    for torrent in torrents
+                    if getattr(torrent, "hash", None)
+                    and (known_hashes is None or str(torrent.hash).lower() not in known_hashes)
+                ]
+                for torrent in new_torrents:
+                    if getattr(torrent, "name", None) == name:
+                        return str(torrent.hash).lower()
+                if known_hashes is not None and len(new_torrents) == 1:
+                    return str(new_torrents[0].hash).lower()
+            time.sleep(0.5)
+        return None
+
     @staticmethod
     def is_configured() -> bool:
         """Check if qBittorrent is configured and selected as the torrent client."""
@@ -368,7 +425,7 @@ class QBittorrentClient(DownloadClient):
     def test_connection(self) -> tuple[bool, str]:
         """Test connection to qBittorrent."""
         try:
-            self._client.auth_log_in()
+            self._ensure_authenticated()
             api_version = self._client.app.web_api_version
         except _QBITTORRENT_CLIENT_ERRORS as e:
             return False, f"Connection failed: {e!s}"
@@ -425,6 +482,10 @@ class QBittorrentClient(DownloadClient):
             expected_hash = torrent_info.info_hash
             torrent_data = torrent_info.torrent_data
 
+            known_hashes: set[str] | None = None
+            if not expected_hash:
+                known_hashes = self._list_category_hashes(category)
+
             # Per-torrent seeding limits from indexer
             seeding_time_limit_value = kwargs.get("seeding_time_limit")
             seeding_time_limit = coerce_optional_int(seeding_time_limit_value)
@@ -459,12 +520,20 @@ class QBittorrentClient(DownloadClient):
             result_text = _normalize_add_result(result)
             logger.debug("qBittorrent add result: %s", result_text)
 
-            if not expected_hash:
-                _raise_runtime_error("Could not determine torrent hash from URL")
-
             if _is_explicit_add_failure(result):
                 _raise_runtime_error(f"Failed to add torrent: {result_text}")
 
+            if not expected_hash:
+                # qBittorrent fetches .torrent URLs itself, so the add can succeed
+                # even when no hash could be extracted up front. Recover it by
+                # watching for the new torrent to appear.
+                expected_hash = self._discover_added_torrent_hash(name, category, known_hashes)
+            if not expected_hash:
+                message = "Could not determine torrent hash from URL"
+                if torrent_info.fetch_error:
+                    message = f"{message} (torrent file fetch failed: {torrent_info.fetch_error})"
+                _raise_runtime_error(message)
+
             # Some qBittorrent-compatible clients return HTTP 200 with an empty body
             # instead of qBittorrent's literal "Ok." response. Prefer verifying that
             # the torrent becomes visible over trusting the response body alone.
@@ -604,6 +673,26 @@ class QBittorrentClient(DownloadClient):
         else:
             return True
 
+    def set_category(self, download_id: str, category: str) -> bool:
+        """Assign a category to a torrent in qBittorrent."""
+        try:
+            try:
+                self._client.torrents_create_category(name=category)
+            except _QBITTORRENT_CLIENT_ERRORS as e:
+                if "Conflict" not in type(e).__name__ and "409" not in str(e):
+                    logger.debug("Could not create category '%s': %s", category, e)
+
+            self._client.torrents_set_category(
+                torrent_hashes=download_id,
+                category=category,
+            )
+            logger.info("Set qBittorrent category for %s to '%s'", download_id, category)
+        except _QBITTORRENT_CLIENT_ERRORS as e:
+            self._log_error("set_category", e)
+            return False
+        else:
+            return True
+
     def get_download_path(self, download_id: str) -> str | None:
         """Get the path where torrent files are located.
 
@@ -675,11 +764,11 @@ class QBittorrentClient(DownloadClient):
         import os
 
         def get_with_auth(url: str, params: dict[str, str]) -> requests.Response:
-            self._client.auth_log_in()
+            self._ensure_authenticated()
             resp = self._client._session.get(url, params=params, timeout=10)
-            if resp.status_code == _HTTP_STATUS_FORBIDDEN:
+            if resp.status_code == _HTTP_STATUS_FORBIDDEN and self._can_reauthenticate:
                 logger.debug("qBittorrent returned 403; re-authenticating and retrying")
-                self._client.auth_log_in()
+                self._ensure_authenticated()
                 resp = self._client._session.get(url, params=params, timeout=10)
             return resp
 

shelfmark/download/clients/realdebrid.py

@@ -0,0 +1,517 @@
+"""Real-Debrid debrid service client for Shelfmark.
+
+Routes magnet links through the Real-Debrid REST API (v1.0) to download
+torrent content via Real-Debrid's CDN infrastructure.
+"""
+
+from __future__ import annotations
+
+import shutil
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, ClassVar, NoReturn
+
+import requests
+
+from shelfmark.config.env import TMP_DIR
+from shelfmark.core.config import config
+from shelfmark.core.logger import setup_logger
+from shelfmark.download.clients import (
+    DownloadClient,
+    DownloadState,
+    DownloadStatus,
+    register_client,
+)
+from shelfmark.download.clients._coercion import config_text
+from shelfmark.download.http import download_url
+from shelfmark.download.network import get_ssl_verify
+
+logger = setup_logger(__name__)
+
+_API_BASE = "https://api.real-debrid.com/rest/1.0"
+
+_REALDEBRID_CLIENT_ERRORS = (
+    AttributeError,
+    OSError,
+    requests.exceptions.RequestException,
+    RuntimeError,
+    TypeError,
+    ValueError,
+)
+
+# Real-Debrid torrent status values.
+_STATUS_DOWNLOADING = frozenset(
+    {
+        "magnet_conversion",
+        "waiting_files_selection",
+        "downloading",
+        "compressing",
+        "uploading",
+    }
+)
+_STATUS_READY = "downloaded"
+_STATUS_ERROR = frozenset({"error", "virus", "dead"})
+
+# Timeouts for API calls.
+_API_TIMEOUT = 30
+_STATUS_TIMEOUT = 15
+
+# File extensions recognised as book or audiobook content.
+_BOOK_EXTENSIONS = (
+    ".aac",
+    ".azw",
+    ".azw3",
+    ".cbr",
+    ".cbz",
+    ".djvu",
+    ".doc",
+    ".docx",
+    ".epub",
+    ".fb2",
+    ".flac",
+    ".lit",
+    ".m4a",
+    ".m4b",
+    ".mobi",
+    ".mp3",
+    ".ogg",
+    ".opus",
+    ".pdf",
+    ".rtf",
+    ".txt",
+    ".wma",
+)
+
+
+def _raise_runtime_error(message: str) -> NoReturn:
+    raise RuntimeError(message)
+
+
+@dataclass
+class _DownloadState:
+    """Internal mutable state for an in-progress Real-Debrid download."""
+
+    torrent_id: str
+    name: str
+    target_dir: Path
+    phase: str = "uploading"
+    error_message: str | None = None
+    progress: float = 0.0
+    download_thread: threading.Thread | None = None
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+
+@register_client("torrent")
+class RealDebridClient(DownloadClient):
+    """Real-Debrid debrid service client.
+
+    Downloads torrent content by uploading magnet links to Real-Debrid,
+    selecting all files for download on their servers, then unrestricting
+    and fetching the resulting files via direct HTTP download from
+    Real-Debrid's CDN.
+
+    API documentation: https://api.real-debrid.com/
+    """
+
+    protocol = "torrent"
+    name = "realdebrid"
+
+    _downloads: ClassVar[dict[str, _DownloadState]] = {}
+    _downloads_lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._api_key = config_text(config.get("REALDEBRID_API_KEY", ""))
+
+    def _auth_headers(self) -> dict[str, str]:
+        """Return Authorization header dict for API requests."""
+        return {"Authorization": f"Bearer {self._api_key}"}
+
+    # ------------------------------------------------------------------
+    # DownloadClient interface
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def is_configured() -> bool:
+        """Return True when Real-Debrid is selected and an API key exists."""
+        client = config_text(config.get("PROWLARR_TORRENT_CLIENT", ""))
+        api_key = config_text(config.get("REALDEBRID_API_KEY", ""))
+        return client == "realdebrid" and bool(api_key)
+
+    def test_connection(self) -> tuple[bool, str]:
+        """Validate the API key and check Premium subscription status."""
+        if not self._api_key:
+            return False, "Real-Debrid API Key is required"
+        try:
+            url = f"{_API_BASE}/user"
+            resp = requests.get(
+                url,
+                headers=self._auth_headers(),
+                timeout=_STATUS_TIMEOUT,
+                verify=get_ssl_verify(url),
+            )
+            resp.raise_for_status()
+            user = resp.json()
+            username = user.get("username", "Unknown")
+            account_type = user.get("type", "free")
+            if account_type != "premium":
+                return (
+                    False,
+                    f"Real-Debrid user '{username}' does not have "
+                    f"a Premium subscription (type: {account_type})",
+                )
+        except _REALDEBRID_CLIENT_ERRORS as e:
+            return False, f"Connection failed: {e}"
+        else:
+            return True, f"Connected to Real-Debrid as '{username}' (Premium)"
+
+    def add_download(
+        self,
+        url: str,
+        name: str,
+        category: str | None = None,
+        expected_hash: str | None = None,
+        **kwargs: object,
+    ) -> str:
+        """Upload a magnet link to Real-Debrid and select all files."""
+        if not self._api_key:
+            msg = "Real-Debrid API key is not configured"
+            raise RuntimeError(msg)
+
+        magnet_link = url
+        if not magnet_link.startswith("magnet:") and expected_hash:
+            magnet_link = f"magnet:?xt=urn:btih:{expected_hash}"
+
+        add_url = f"{_API_BASE}/torrents/addMagnet"
+        try:
+            resp = requests.post(
+                add_url,
+                headers=self._auth_headers(),
+                data={"magnet": magnet_link},
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(add_url),
+            )
+            resp.raise_for_status()
+            data = resp.json()
+
+            torrent_id = str(data.get("id", ""))
+            if not torrent_id:
+                msg = "No torrent ID returned from Real-Debrid"
+                _raise_runtime_error(msg)
+
+            # Select all files so Real-Debrid starts downloading the torrent
+            select_url = f"{_API_BASE}/torrents/selectFiles/{torrent_id}"
+            sel_resp = requests.post(
+                select_url,
+                headers=self._auth_headers(),
+                data={"files": "all"},
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(select_url),
+            )
+            sel_resp.raise_for_status()
+
+            target_dir = TMP_DIR / f"realdebrid_{torrent_id}"
+            target_dir.mkdir(parents=True, exist_ok=True)
+
+            state = _DownloadState(
+                torrent_id=torrent_id,
+                name=name,
+                target_dir=target_dir,
+                phase="waiting_rd",
+            )
+            with self._downloads_lock:
+                self._downloads[torrent_id] = state
+
+            logger.info(
+                "Added torrent to Real-Debrid: ID %s (%s)",
+                torrent_id,
+                name,
+            )
+
+        except Exception:
+            logger.exception("Failed to upload magnet to Real-Debrid")
+            raise
+
+        else:
+            return torrent_id
+
+    def get_status(self, download_id: str) -> DownloadStatus:
+        """Poll Real-Debrid for torrent status and drive the download."""
+        state = self._ensure_state(download_id)
+
+        # Return cached terminal / in-flight states immediately.
+        with state.lock:
+            if state.phase == "error":
+                return DownloadStatus.error(
+                    state.error_message or "Real-Debrid error",
+                )
+            if state.phase == "complete":
+                return DownloadStatus(
+                    progress=100.0,
+                    state=DownloadState.COMPLETE,
+                    message="Complete",
+                    complete=True,
+                    file_path=str(state.target_dir),
+                )
+            if state.phase == "downloading_http":
+                return DownloadStatus(
+                    progress=state.progress,
+                    state=DownloadState.DOWNLOADING,
+                    message="Downloading files via HTTP...",
+                    complete=False,
+                    file_path=None,
+                )
+
+        # Query Real-Debrid for torrent info.
+        try:
+            info_url = f"{_API_BASE}/torrents/info/{download_id}"
+            resp = requests.get(
+                info_url,
+                headers=self._auth_headers(),
+                timeout=_STATUS_TIMEOUT,
+                verify=get_ssl_verify(info_url),
+            )
+            resp.raise_for_status()
+            info = resp.json()
+            return self._handle_torrent_info(info, state)
+
+        except Exception as e:
+            logger.exception(
+                "Error checking Real-Debrid status for %s",
+                download_id,
+            )
+            return DownloadStatus.error(str(e))
+
+    def remove(
+        self,
+        download_id: str,
+        *,
+        delete_files: bool = False,
+    ) -> bool:
+        """Delete the torrent from Real-Debrid and clean up local files."""
+        try:
+            url = f"{_API_BASE}/torrents/delete/{download_id}"
+            requests.delete(
+                url,
+                headers=self._auth_headers(),
+                timeout=_STATUS_TIMEOUT,
+                verify=get_ssl_verify(url),
+            )
+        except _REALDEBRID_CLIENT_ERRORS as e:
+            logger.warning("Failed to delete torrent from Real-Debrid: %s", e)
+
+        with self._downloads_lock:
+            state = self._downloads.pop(download_id, None)
+
+        if state and state.target_dir.exists():
+            shutil.rmtree(state.target_dir, ignore_errors=True)
+        return True
+
+    def get_download_path(self, download_id: str) -> str | None:
+        """Return the local directory containing downloaded files."""
+        with self._downloads_lock:
+            state = self._downloads.get(download_id)
+        if state and state.phase == "complete":
+            return str(state.target_dir)
+        target_dir = TMP_DIR / f"realdebrid_{download_id}"
+        if target_dir.exists():
+            return str(target_dir)
+        return None
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _ensure_state(self, download_id: str) -> _DownloadState:
+        """Get or create download state for the given torrent ID."""
+        with self._downloads_lock:
+            state = self._downloads.get(download_id)
+        if state:
+            return state
+
+        target_dir = TMP_DIR / f"realdebrid_{download_id}"
+        state = _DownloadState(
+            torrent_id=download_id,
+            name=f"Download {download_id}",
+            target_dir=target_dir,
+            phase="waiting_rd",
+        )
+        with self._downloads_lock:
+            self._downloads[download_id] = state
+        return state
+
+    def _handle_torrent_info(
+        self,
+        info: dict[str, Any],
+        state: _DownloadState,
+    ) -> DownloadStatus:
+        """Map Real-Debrid torrent info to a DownloadStatus."""
+        status = info.get("status", "")
+
+        if status in _STATUS_DOWNLOADING:
+            progress = float(info.get("progress", 0.0))
+            speed = int(info.get("speed", 0))
+            filename = info.get("filename", state.name)
+            return DownloadStatus(
+                progress=progress * 0.5,
+                state=DownloadState.DOWNLOADING,
+                message=f"Real-Debrid downloading torrent ({filename})",
+                complete=False,
+                file_path=None,
+                download_speed=speed,
+            )
+
+        if status == _STATUS_READY:
+            links = info.get("links", [])
+            files = info.get("files", [])
+            self._maybe_start_download_thread(state, links, files)
+            return DownloadStatus(
+                progress=50.0,
+                state=DownloadState.DOWNLOADING,
+                message="Real-Debrid ready, retrieving files...",
+                complete=False,
+                file_path=None,
+            )
+
+        # Terminal error from Real-Debrid.
+        error_txt = f"Real-Debrid status error: {status}"
+        with state.lock:
+            state.phase = "error"
+            state.error_message = error_txt
+        return DownloadStatus.error(error_txt)
+
+    def _maybe_start_download_thread(
+        self,
+        state: _DownloadState,
+        links: list[str],
+        files: list[dict[str, Any]],
+    ) -> None:
+        """Spawn a background thread to unrestrict and download files."""
+        with state.lock:
+            already_running = state.phase in (
+                "unrestricting",
+                "downloading_http",
+                "complete",
+            )
+            thread_alive = state.download_thread is not None and state.download_thread.is_alive()
+            if already_running or thread_alive:
+                return
+            state.phase = "unrestricting"
+            t = threading.Thread(
+                target=self._process_and_download,
+                args=(state, links, files),
+                daemon=True,
+            )
+            state.download_thread = t
+            t.start()
+
+    # ------------------------------------------------------------------
+    # File download pipeline
+    # ------------------------------------------------------------------
+
+    def _process_and_download(
+        self,
+        state: _DownloadState,
+        links: list[str],
+        files: list[dict[str, Any]],
+    ) -> None:
+        """Unrestrict links and download files via HTTP.
+
+        Runs in a background thread spawned by ``_maybe_start_download_thread``.
+        """
+        try:
+            if not links:
+                msg = "No download links returned by Real-Debrid"
+                _raise_runtime_error(msg)
+
+            # Match selected files with links
+            selected_files = [f for f in files if f.get("selected") == 1]
+
+            # Filter relevant ebook / audiobook files
+            relevant_indices: list[int] = []
+            for i, f_info in enumerate(selected_files):
+                path_str = f_info.get("path", "").lower()
+                if path_str.endswith(_BOOK_EXTENSIONS):
+                    relevant_indices.append(i)
+
+            if not relevant_indices:
+                relevant_indices = list(range(len(links)))
+
+            with state.lock:
+                state.phase = "downloading_http"
+
+            total = len(relevant_indices)
+            for idx, rel_idx in enumerate(relevant_indices):
+                if rel_idx >= len(links):
+                    continue
+                link = links[rel_idx]
+
+                # Unrestrict the Real-Debrid link to get direct CDN download URL
+                unrestrict_url = f"{_API_BASE}/unrestrict/link"
+                unl_resp = requests.post(
+                    unrestrict_url,
+                    headers=self._auth_headers(),
+                    data={"link": link},
+                    timeout=_API_TIMEOUT,
+                    verify=get_ssl_verify(unrestrict_url),
+                )
+                unl_resp.raise_for_status()
+                unl_data = unl_resp.json()
+
+                direct_url = unl_data.get("download")
+                filename = unl_data.get("filename")
+                if not direct_url:
+                    msg = f"Failed to unrestrict Real-Debrid link: {link}"
+                    _raise_runtime_error(msg)
+
+                # Determine relative file path
+                if rel_idx < len(selected_files):
+                    rel_path_str = selected_files[rel_idx].get("path", "").lstrip("/")
+                    rel_path = Path(rel_path_str)
+                else:
+                    rel_path = Path(filename or f"file_{idx + 1}")
+
+                dest = state.target_dir / rel_path
+                dest.parent.mkdir(parents=True, exist_ok=True)
+
+                logger.info(
+                    "Downloading Real-Debrid file %d/%d: %s",
+                    idx + 1,
+                    total,
+                    rel_path,
+                )
+
+                buf = download_url(
+                    direct_url,
+                    referer="https://real-debrid.com/",
+                )
+                if not buf:
+                    msg = f"Failed to download from {direct_url}"
+                    _raise_runtime_error(msg)
+
+                with dest.open("wb") as fh:
+                    fh.write(buf.getvalue())
+
+                with state.lock:
+                    state.progress = 50.0 + (idx + 1) / total * 50.0
+
+            with state.lock:
+                state.phase = "complete"
+                state.progress = 100.0
+
+            logger.info(
+                "Real-Debrid download complete for ID %s at %s",
+                state.torrent_id,
+                state.target_dir,
+            )
+
+        except Exception:
+            logger.exception(
+                "Error in Real-Debrid download for ID %s",
+                state.torrent_id,
+            )
+            with state.lock:
+                state.phase = "error"
+                state.error_message = str(
+                    state.error_message or "Download failed",
+                )

shelfmark/download/clients/rtorrent.py

@@ -4,6 +4,7 @@ Uses xmlrpc to communicate with rTorrent's RPC interface.
 """
 
 import ssl
+import time
 import xmlrpc.client as stdlib_xmlrpc_client
 from typing import Any, NoReturn, Protocol, cast
 from urllib.parse import urlparse
@@ -46,7 +47,13 @@ class _RTorrentLoadProtocol(Protocol):
     def start(self, target: str, url: str, commands: str) -> object: ...
 
 
+class _RTorrentCustom1Protocol(Protocol):
+    def set(self, download_id: str, value: str) -> object: ...
+
+
 class _RTorrentDownloadProtocol(Protocol):
+    custom1: _RTorrentCustom1Protocol
+
     def multicall2(self, *args: object) -> list[list[Any]]: ...
 
     def delete_tied(self, download_id: str) -> object: ...
@@ -160,6 +167,10 @@ class RTorrentClient(DownloadClient):
         try:
             torrent_info = extract_torrent_info(url, expected_hash=expected_hash)
 
+            known_hashes: set[str] | None = None
+            if not (torrent_info.info_hash or expected_hash):
+                known_hashes = self._list_torrent_hashes()
+
             commands = []
 
             is_audiobook = kwargs.get("content_type") == "audiobook"
@@ -196,7 +207,15 @@ class RTorrentClient(DownloadClient):
 
             torrent_hash = torrent_info.info_hash or expected_hash
             if not torrent_hash:
-                _raise_runtime_error("Could not determine torrent hash from URL")
+                # rTorrent fetches .torrent URLs itself, so the add can succeed
+                # even when no hash could be extracted up front. Recover it by
+                # watching for the new download to appear.
+                torrent_hash = self._discover_added_torrent_hash(name, label, known_hashes)
+            if not torrent_hash:
+                message = "Could not determine torrent hash from URL"
+                if torrent_info.fetch_error:
+                    message = f"{message} (torrent file fetch failed: {torrent_info.fetch_error})"
+                _raise_runtime_error(message)
 
             logger.debug("Added torrent to rTorrent: %s", torrent_hash)
 
@@ -319,12 +338,14 @@ class RTorrentClient(DownloadClient):
 
         """
         try:
+            # rtorrent is somehow case sensitive and requires uppercase hashes for look
+            torrent_hash = download_id.upper()
             if delete_files:
-                self._rpc.d.delete_tied(download_id)
-                self._rpc.d.erase(download_id)
+                self._rpc.d.delete_tied(torrent_hash)
+                self._rpc.d.erase(torrent_hash)
             else:
-                self._rpc.d.stop(download_id)
-                self._rpc.d.erase(download_id)
+                self._rpc.d.stop(torrent_hash)
+                self._rpc.d.erase(torrent_hash)
 
             logger.info(
                 "Removed torrent from rTorrent: %s%s",
@@ -338,6 +359,19 @@ class RTorrentClient(DownloadClient):
         else:
             return True
 
+    def set_category(self, download_id: str, category: str) -> bool:
+        """Assign a label to a torrent using rTorrent's custom1 field."""
+        try:
+            # rtorrent is somehow case sensitive and requires uppercase hashes for look
+            self._rpc.d.custom1.set(download_id.upper(), category)
+            logger.info("Set rTorrent label for %s to '%s'", download_id, category)
+        except _RTORRENT_CLIENT_ERRORS as e:
+            error_type = type(e).__name__
+            logger.exception("rTorrent set_category failed (%s)", error_type)
+            return False
+        else:
+            return True
+
     def get_download_path(self, download_id: str) -> str | None:
         """Get the path where torrent files are located.
 
@@ -387,6 +421,56 @@ class RTorrentClient(DownloadClient):
         except _RTORRENT_CLIENT_ERRORS:
             return "/downloads"
 
+    def _list_torrent_hashes(self) -> set[str] | None:
+        """Snapshot the hashes rTorrent currently reports."""
+        try:
+            all_torrents = self._rpc.d.multicall2("", "", "d.hash=")
+        except _RTORRENT_CLIENT_ERRORS as e:
+            logger.debug("Could not snapshot rTorrent downloads: %s", e)
+            return None
+        return {str(row[0]).lower() for row in all_torrents if row and row[0]}
+
+    def _discover_added_torrent_hash(
+        self,
+        name: str,
+        label: str,
+        known_hashes: set[str] | None,
+    ) -> str | None:
+        """Recover the hash of a torrent that was added without a known info_hash.
+
+        rTorrent fetches .torrent URLs itself, so the add can succeed even when
+        no hash could be extracted up front. A `known_hashes` of None means the
+        pre-add snapshot failed, so only an exact name match can identify the
+        new arrival.
+        """
+        for _ in range(20):
+            try:
+                all_torrents = self._rpc.d.multicall2("", "", "d.hash=", "d.name=", "d.custom1=")
+            except _RTORRENT_CLIENT_ERRORS as e:
+                logger.debug("rTorrent hash discovery: %s", e)
+            else:
+                new_torrents = [
+                    row
+                    for row in all_torrents
+                    if row
+                    and row[0]
+                    and (known_hashes is None or str(row[0]).lower() not in known_hashes)
+                ]
+                # The label set at add time distinguishes concurrent arrivals,
+                # but rTorrent may not have applied it yet, so it only ever
+                # narrows a non-empty candidate list.
+                if label:
+                    labeled = [row for row in new_torrents if len(row) > 2 and row[2] == label]
+                    if labeled:
+                        new_torrents = labeled
+                for row in new_torrents:
+                    if len(row) > 1 and row[1] == name:
+                        return str(row[0]).lower()
+                if known_hashes is not None and len(new_torrents) == 1:
+                    return str(new_torrents[0][0]).lower()
+            time.sleep(0.5)
+        return None
+
     def _get_torrent_path(self, download_id: str) -> str | None:
         """Get the file path of a torrent by hash.
 

shelfmark/download/clients/settings.py

@@ -159,6 +159,7 @@ def _test_qbittorrent_connection(current_values: dict[str, Any] | None = None) -
     raw_url = _resolve_string_setting(current_values, config.get, "QBITTORRENT_URL")
     username = _resolve_string_setting(current_values, config.get, "QBITTORRENT_USERNAME")
     password = _resolve_string_setting(current_values, config.get, "QBITTORRENT_PASSWORD")
+    api_key = _resolve_string_setting(current_values, config.get, "QBITTORRENT_API_KEY")
 
     if not raw_url:
         return {"success": False, "message": "qBittorrent URL is required"}
@@ -174,6 +175,7 @@ def _test_qbittorrent_connection(current_values: dict[str, Any] | None = None) -
             host=url,
             username=username,
             password=password,
+            api_key=api_key or None,
             VERIFY_WEBUI_CERTIFICATE=get_ssl_verify(url),
         )
         client.auth_log_in()
@@ -181,9 +183,18 @@ def _test_qbittorrent_connection(current_values: dict[str, Any] | None = None) -
     except ImportError:
         return {"success": False, "message": "qbittorrent-api package not installed"}
     except _QBITTORRENT_SETTINGS_ERRORS as e:
+        if isinstance(e, _QBittorrentLoginFailed):
+            # LoginFailed carries no message of its own, so name the rejected credential.
+            rejected = "API key" if api_key else "username or password"
+            return {"success": False, "message": f"qBittorrent rejected the {rejected}"}
         return {"success": False, "message": f"Connection failed: {e!s}"}
     else:
-        return {"success": True, "message": f"Connected to qBittorrent (API v{api_version})"}
+        # Both credentials can be set at once, so name the one that actually authenticated.
+        used = " using the API key" if api_key else ""
+        return {
+            "success": True,
+            "message": f"Connected to qBittorrent (API v{api_version}){used}",
+        }
 
 
 def _test_transmission_connection(current_values: dict[str, Any] | None = None) -> dict[str, Any]:
@@ -520,6 +531,40 @@ def _test_sabnzbd_connection(current_values: dict[str, Any] | None = None) -> di
         return {"success": True, "message": f"Connected to SABnzbd {version}"}
 
 
+def _test_alldebrid_connection(current_values: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Test the AllDebrid API connection using current form values."""
+    from shelfmark.core.config import config
+    from shelfmark.download.clients.alldebrid import AllDebridClient
+
+    current_values = current_values or {}
+    api_key = _resolve_string_setting(current_values, config.get, "ALLDEBRID_API_KEY")
+
+    if not api_key:
+        return {"success": False, "message": "AllDebrid API Key is required"}
+
+    client = AllDebridClient()
+    client._api_key = api_key
+    success, message = client.test_connection()
+    return {"success": success, "message": message}
+
+
+def _test_realdebrid_connection(current_values: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Test the Real-Debrid API connection using current form values."""
+    from shelfmark.core.config import config
+    from shelfmark.download.clients.realdebrid import RealDebridClient
+
+    current_values = current_values or {}
+    api_key = _resolve_string_setting(current_values, config.get, "REALDEBRID_API_KEY")
+
+    if not api_key:
+        return {"success": False, "message": "Real-Debrid API Key is required"}
+
+    client = RealDebridClient()
+    client._api_key = api_key
+    success, message = client.test_connection()
+    return {"success": success, "message": message}
+
+
 # ==================== Download Clients Tab ====================
 
 
@@ -544,13 +589,45 @@ def prowlarr_clients_settings() -> list[SettingsField]:
             description="Choose which torrent client to use",
             options=[
                 {"value": "", "label": "None"},
+                {"value": "alldebrid", "label": "AllDebrid"},
                 {"value": "qbittorrent", "label": "qBittorrent"},
+                {"value": "realdebrid", "label": "Real-Debrid"},
                 {"value": "transmission", "label": "Transmission"},
                 {"value": "deluge", "label": "Deluge"},
                 {"value": "rtorrent", "label": "rTorrent"},
             ],
             default="",
         ),
+        # --- AllDebrid Settings ---
+        PasswordField(
+            key="ALLDEBRID_API_KEY",
+            label="API Key",
+            description="AllDebrid API Key (apiv4) from your AllDebrid account settings",
+            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "alldebrid"},
+        ),
+        ActionButton(
+            key="test_alldebrid",
+            label="Test Connection",
+            description="Verify your AllDebrid configuration",
+            style="primary",
+            callback=_test_alldebrid_connection,
+            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "alldebrid"},
+        ),
+        # --- Real-Debrid Settings ---
+        PasswordField(
+            key="REALDEBRID_API_KEY",
+            label="API Key",
+            description="Real-Debrid API Key (Secret Token) from your Real-Debrid account settings",
+            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "realdebrid"},
+        ),
+        ActionButton(
+            key="test_realdebrid",
+            label="Test Connection",
+            description="Verify your Real-Debrid configuration",
+            style="primary",
+            callback=_test_realdebrid_connection,
+            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "realdebrid"},
+        ),
         # --- qBittorrent Settings ---
         TextField(
             key="QBITTORRENT_URL",
@@ -572,6 +649,12 @@ def prowlarr_clients_settings() -> list[SettingsField]:
             description="qBittorrent Web UI password",
             show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "qbittorrent"},
         ),
+        PasswordField(
+            key="QBITTORRENT_API_KEY",
+            label="API Key",
+            description="Found in qBittorrent: Options > Web UI > API Key (qBittorrent 5.2.0+). Used instead of the username and password when set.",
+            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "qbittorrent"},
+        ),
         ActionButton(
             key="test_qbittorrent",
             label="Test Connection",
@@ -771,14 +854,23 @@ def prowlarr_clients_settings() -> list[SettingsField]:
         SelectField(
             key="PROWLARR_TORRENT_ACTION",
             label="Torrent Completion Action",
-            description="Remove deletes the torrent from your client immediately after import (stops seeding, files are kept); Keep leaves it in the client to continue seeding",
+            description="Choose whether to keep, remove, or move the torrent to another category or label after import",
             options=[
                 {"value": "keep", "label": "Keep"},
                 {"value": "remove", "label": "Remove"},
+                {"value": "change_category", "label": "Change Category"},
             ],
             default="keep",
             show_when={"field": "PROWLARR_TORRENT_CLIENT", "notEmpty": True},
         ),
+        TextField(
+            key="PROWLARR_TORRENT_POST_IMPORT_CATEGORY",
+            label="Post-Import Category",
+            description="Category or label to assign after a successful import",
+            placeholder="imported",
+            default="",
+            show_when={"field": "PROWLARR_TORRENT_ACTION", "value": "change_category"},
+        ),
         # --- Usenet Client Selection ---
         HeadingField(
             key="usenet_heading",

shelfmark/download/clients/torrent_utils.py

@@ -5,8 +5,10 @@ from __future__ import annotations
 import base64
 import hashlib
 import re
+import time
 from binascii import Error as BinasciiError
 from dataclasses import dataclass
+from threading import Lock
 from urllib.parse import ParseResult, parse_qs, urljoin, urlparse
 
 import requests
@@ -19,6 +21,7 @@ from shelfmark.download.network import get_ssl_verify
 logger = setup_logger(__name__)
 
 _MAGNET_RESPONSE_MAX_BYTES = 2000
+_TORRENT_FETCH_MAX_REDIRECTS = 5
 _BASE32_BTMH_TAG_BYTES = 34
 _BTIH_INFO_BYTE_HEX = 0x20
 _BTIH_PREFIX_BYTE = 0x12
@@ -35,6 +38,15 @@ _TORRENT_FETCH_ERRORS = (
 _TORRENT_PARSE_ERRORS = (IndexError, KeyError, TypeError, ValueError)
 _TRUSTED_TORRENT_FETCH_URL_CONFIG_KEYS = ("PROWLARR_URL", "NEWZNAB_URL")
 
+# Successful torrent fetches are reused for a short window so one add attempt
+# hits the download link only once. Tracker download links (e.g. private
+# trackers behind Prowlarr's proxy) can be slow, rate-limited, or single-use,
+# and both find_existing() and add_download() resolve the same URL (#1111).
+_TORRENT_FETCH_CACHE_TTL_SECONDS = 120.0
+_TORRENT_FETCH_CACHE_MAX_ENTRIES = 8
+_torrent_fetch_cache_lock = Lock()
+_torrent_fetch_cache: dict[str, tuple[float, TorrentInfo]] = {}
+
 type BencodeValue = dict[str | bytes, BencodeValue] | list[BencodeValue] | int | bytes | str
 
 
@@ -54,6 +66,9 @@ class TorrentInfo:
     magnet_url: str | None = None
     """The actual magnet URL, if available."""
 
+    fetch_error: str | None = None
+    """Why fetching the .torrent URL failed, or None if it succeeded/was skipped."""
+
     def with_info_hash(self, info_hash: str | None) -> TorrentInfo:
         """Return a copy with the info_hash replaced when provided."""
         if info_hash:
@@ -62,6 +77,7 @@ class TorrentInfo:
                 torrent_data=self.torrent_data,
                 is_magnet=self.is_magnet,
                 magnet_url=self.magnet_url,
+                fetch_error=self.fetch_error,
             )
         return self
 
@@ -96,21 +112,62 @@ def extract_torrent_info(
     if not fetch_torrent:
         return TorrentInfo(info_hash=expected_hash, torrent_data=None, is_magnet=False)
 
+    info = _get_cached_torrent_fetch(url)
+    if info is None:
+        info = _fetch_torrent_info(url)
+        if info.fetch_error is None:
+            _store_cached_torrent_fetch(url, info)
+
+    return info.with_info_hash(info.info_hash or expected_hash)
+
+
+def _get_cached_torrent_fetch(url: str) -> TorrentInfo | None:
+    with _torrent_fetch_cache_lock:
+        entry = _torrent_fetch_cache.get(url)
+        if entry is None:
+            return None
+        fetched_at, info = entry
+        if time.monotonic() - fetched_at > _TORRENT_FETCH_CACHE_TTL_SECONDS:
+            del _torrent_fetch_cache[url]
+            return None
+    logger.debug("Reusing recently fetched torrent data for: %s...", url[:80])
+    return info
+
+
+def _store_cached_torrent_fetch(url: str, info: TorrentInfo) -> None:
+    with _torrent_fetch_cache_lock:
+        _torrent_fetch_cache[url] = (time.monotonic(), info)
+        while len(_torrent_fetch_cache) > _TORRENT_FETCH_CACHE_MAX_ENTRIES:
+            oldest_url = min(_torrent_fetch_cache, key=lambda key: _torrent_fetch_cache[key][0])
+            del _torrent_fetch_cache[oldest_url]
+
+
+def clear_torrent_fetch_cache() -> None:
+    """Drop all cached torrent fetches (used by tests)."""
+    with _torrent_fetch_cache_lock:
+        _torrent_fetch_cache.clear()
+
+
+def _fetch_torrent_info(url: str) -> TorrentInfo:
+    """Fetch a .torrent URL and parse out the info_hash and raw torrent data.
+
+    On failure, the returned TorrentInfo carries the reason in `fetch_error`
+    so callers can surface it instead of a generic hash error.
+    """
     # A release source can legitimately hand us a download URL on a different
     # origin than the configured Prowlarr/Newznab endpoint (e.g. a direct
-    # tracker link, or Prowlarr reached through a separate proxy). We still need
-    # to fetch the .torrent to recover the info_hash when the source did not
-    # provide one, so the prefetch runs regardless of origin. The Prowlarr API
-    # key, however, is only ever sent to a trusted origin so it can never leak
-    # to an arbitrary indexer/tracker host.
-    trusted_origin = _is_trusted_torrent_fetch_url(url)
-
+    # tracker link, or Prowlarr reached through a separate proxy), and a trusted
+    # Prowlarr download URL commonly redirects to the indexer's own download
+    # link. We still need to fetch the .torrent to recover the info_hash when
+    # the source did not provide one, so the prefetch runs regardless of origin
+    # and follows cross-origin redirects. The Prowlarr API key, however, is
+    # re-evaluated per hop and only ever sent to a trusted origin so it can
+    # never leak to an arbitrary indexer/tracker host.
     headers: dict[str, str] = {"Accept": "application/x-bittorrent"}
-    if trusted_origin:
-        # TODO(shelfmark): Move this source-specific Prowlarr auth handling into a source hook.
-        api_key = str(config.get("PROWLARR_API_KEY", "") or "").strip()
-        if api_key:
-            headers["X-Api-Key"] = api_key
+    # TODO(shelfmark): Move this source-specific Prowlarr auth handling into a source hook.
+    api_key = str(config.get("PROWLARR_API_KEY", "") or "").strip()
+    if api_key:
+        headers["X-Api-Key"] = api_key
 
     def resolve_url(current: str, location: str) -> str:
         if not location:
@@ -121,44 +178,47 @@ def extract_torrent_info(
     try:
         logger.debug("Fetching torrent file from: %s...", url[:80])
 
-        # Use allow_redirects=False to handle magnet link redirects manually
-        # Some indexers redirect download URLs to magnet links
-        resp = requests.get(
-            url,
-            timeout=30,
-            allow_redirects=False,
-            headers=headers,
-            verify=get_ssl_verify(url),
-        )
+        # Redirects are followed manually: some indexers redirect download URLs
+        # to magnet links, and each hop must decide anew whether it may see the
+        # API key.
+        current_url = url
+        redirects_remaining = _TORRENT_FETCH_MAX_REDIRECTS
+        while True:
+            request_headers = dict(headers)
+            if not _is_trusted_torrent_fetch_url(current_url):
+                request_headers.pop("X-Api-Key", None)
 
-        # Check if this is a redirect to a magnet link
-        if resp.status_code in (301, 302, 303, 307, 308):
-            redirect_url = resolve_url(url, resp.headers.get("Location", ""))
+            resp = requests.get(
+                current_url,
+                timeout=30,
+                allow_redirects=False,
+                headers=request_headers,
+                verify=get_ssl_verify(current_url),
+            )
+
+            if resp.status_code not in (301, 302, 303, 307, 308):
+                break
+
+            redirect_url = resolve_url(current_url, resp.headers.get("Location", ""))
             if redirect_url.startswith("magnet:"):
                 logger.debug("Download URL redirected to magnet link")
-                info_hash = extract_hash_from_magnet(redirect_url)
-                if not info_hash and expected_hash:
-                    info_hash = expected_hash
                 return TorrentInfo(
-                    info_hash=info_hash,
+                    info_hash=extract_hash_from_magnet(redirect_url),
                     torrent_data=None,
                     is_magnet=True,
                     magnet_url=redirect_url,
                 )
-            if not _is_trusted_torrent_fetch_url(redirect_url):
-                logger.debug(
-                    "Skipping torrent prefetch redirect to untrusted URL: %s...",
-                    redirect_url[:80],
+            if redirects_remaining <= 0:
+                logger.warning("Too many redirects fetching torrent file: %s...", url[:80])
+                return TorrentInfo(
+                    info_hash=None,
+                    torrent_data=None,
+                    is_magnet=False,
+                    fetch_error="too many redirects",
                 )
-                return TorrentInfo(info_hash=expected_hash, torrent_data=None, is_magnet=False)
-            # Not a magnet redirect, follow it manually
+            redirects_remaining -= 1
             logger.debug("Following redirect to: %s...", redirect_url[:80])
-            resp = requests.get(
-                redirect_url,
-                timeout=30,
-                headers=headers,
-                verify=get_ssl_verify(redirect_url),
-            )
+            current_url = redirect_url
 
         resp.raise_for_status()
         torrent_data = resp.content
@@ -169,25 +229,22 @@ def extract_torrent_info(
             text_content = torrent_data.decode("utf-8", errors="ignore").strip()
             if text_content.startswith("magnet:"):
                 logger.debug("Download URL returned magnet link as response body")
-                info_hash = extract_hash_from_magnet(text_content)
-                if not info_hash and expected_hash:
-                    info_hash = expected_hash
                 return TorrentInfo(
-                    info_hash=info_hash,
+                    info_hash=extract_hash_from_magnet(text_content),
                     torrent_data=None,
                     is_magnet=True,
                     magnet_url=text_content,
                 )
 
-        info_hash = extract_info_hash_from_torrent(torrent_data) or expected_hash
+        info_hash = extract_info_hash_from_torrent(torrent_data)
         if info_hash:
             logger.debug("Extracted hash from torrent file: %s", info_hash)
         else:
             logger.warning("Could not extract hash from torrent file")
         return TorrentInfo(info_hash=info_hash, torrent_data=torrent_data, is_magnet=False)
     except _TORRENT_FETCH_ERRORS as e:
-        logger.debug("Could not fetch torrent file: %s", e)
-        return TorrentInfo(info_hash=expected_hash, torrent_data=None, is_magnet=False)
+        logger.warning("Could not fetch torrent file: %s", e)
+        return TorrentInfo(info_hash=None, torrent_data=None, is_magnet=False, fetch_error=str(e))
 
 
 def _is_trusted_torrent_fetch_url(url: str) -> bool:

shelfmark/download/clients/transmission.py

@@ -390,6 +390,30 @@ class TransmissionClient(DownloadClient):
         else:
             return True
 
+    def _get_torrent_labels(self, download_id: str) -> list[str]:
+        """Return a torrent's current labels, preserving their order."""
+        torrent = self._client.get_torrent(download_id)
+        raw_labels = getattr(torrent, "labels", None) or []
+        return [str(label) for label in raw_labels if str(label)]
+
+    def set_category(self, download_id: str, category: str) -> bool:
+        """Add the post-import label to a torrent, keeping labels set elsewhere."""
+        try:
+            existing_labels = self._get_torrent_labels(download_id)
+            if category in existing_labels:
+                logger.debug(
+                    "Transmission torrent %s already has label '%s'", download_id, category
+                )
+                return True
+
+            self._client.change_torrent(ids=download_id, labels=[*existing_labels, category])
+            logger.info("Added Transmission label '%s' to %s", category, download_id)
+        except _TRANSMISSION_CLIENT_ERRORS as e:
+            self._log_error("set_category", e)
+            return False
+        else:
+            return True
+
     def get_download_path(self, download_id: str) -> str | None:
         """Get the path where torrent files are located.
 

shelfmark/download/network.py

@@ -852,6 +852,99 @@ def _init_custom_resolver_internal(servers: list[str]) -> dns.resolver.Resolver:
     return custom_resolver
 
 
+# --- ISP / network DNS interference detection ---------------------------------
+# Compare what the (tamperable) system resolver returns for a host against a
+# tamper-resistant DoH lookup. Divergent answers are a strong signal the network is
+# hijacking or NXDOMAIN-blocking the domain (a common reason AA downloads "work" but
+# land on an ISP block page). Used to surface an actionable hint to the user.
+_dns_interference_warned: set[str] = set()
+_dns_interference_active = False
+
+
+def _build_detection_doh_resolver() -> DoHResolver | None:
+    """Build a throwaway DoH resolver for interference checks (no socket patching).
+
+    Honours the DoH provider the user selected (``DNS_PROVIDERS[_current_dns_index]``),
+    falling back to the first configured provider when none is active. The endpoint is
+    pinned to the provider's own nameserver IP so resolving the DoH host can't be
+    redirected by the very DNS layer the check is meant to detect.
+    """
+    if 0 <= _current_dns_index < len(DNS_PROVIDERS):
+        _name, servers, doh_url = DNS_PROVIDERS[_current_dns_index]
+    elif DNS_PROVIDERS:
+        _name, servers, doh_url = DNS_PROVIDERS[0]
+    else:
+        return None
+    server_hostname = urllib.parse.urlparse(doh_url).hostname or ""
+    if not server_hostname or not servers:
+        return None
+    return DoHResolver(doh_url, server_hostname, servers[0])
+
+
+def detect_dns_interference(hostname: str) -> dict[str, list[str]] | None:
+    """Detect network DNS interference by comparing system DNS against DoH.
+
+    Returns ``{"system_ips": [...], "doh_ips": [...]}`` when the two resolvers disagree
+    (no overlapping IPs), otherwise None. No-op for IP literals / local hostnames and
+    when DoH resolution is unavailable, so it never produces a false positive.
+    """
+    host = (hostname or "").strip().lower()
+    if not host or _is_ip_address(host) or _is_local_address(host):
+        return None
+    resolver = _build_detection_doh_resolver()
+    if resolver is None:
+        return None
+    try:
+        system_ips = {str(info[4][0]) for info in original_getaddrinfo(host, 443, socket.AF_INET)}
+    except OSError:
+        return None
+    if not system_ips:
+        return None
+    doh_ips = {ip for ip in resolver.resolve(host, "A") if ip}
+    if not doh_ips or (system_ips & doh_ips):
+        return None
+    return {"system_ips": sorted(system_ips), "doh_ips": sorted(doh_ips)}
+
+
+def note_possible_dns_interference(hostname: str) -> bool:
+    """Check ``hostname`` for DNS interference, logging an actionable warning once.
+
+    Returns True when interference has been detected this session. The check runs at
+    most once per host to avoid repeated DoH lookups and log spam.
+    """
+    global _dns_interference_active
+    host = (hostname or "").strip().lower()
+    if not host or host in _dns_interference_warned:
+        return _dns_interference_active
+    _dns_interference_warned.add(host)
+
+    result = detect_dns_interference(host)
+    if not result:
+        return _dns_interference_active
+
+    _dns_interference_active = True
+    routing_via_doh = _current_dns_index >= 0 and bool(DOH_SERVER)
+    remedy = (
+        "Shelfmark is routing this domain through DNS-over-HTTPS to work around it."
+        if routing_via_doh
+        else "Enable DNS-over-HTTPS (USE_DOH=true) or set a custom DNS provider to bypass it."
+    )
+    logger.warning(
+        "Possible ISP/network DNS interference for %s: system DNS resolves to %s but DoH "
+        "resolves to %s. The network appears to be blocking or redirecting this domain. %s",
+        host,
+        result["system_ips"],
+        result["doh_ips"],
+        remedy,
+    )
+    return True
+
+
+def dns_interference_detected() -> bool:
+    """Whether network DNS interference has been detected this session."""
+    return _dns_interference_active
+
+
 def init_doh_resolver(doh_server: str = "") -> DoHResolver | None:
     """Initialize DNS over HTTPS resolver."""
     server = doh_server or DOH_SERVER

shelfmark/download/orchestrator.py

@@ -170,16 +170,19 @@ def _build_retry_resolution_fields(
     retry_download_url = normalize_optional_text(release_data.get("download_url"))
     protocol = normalize_optional_text(release_data.get("protocol"))
     source = normalize_optional_text(release_data.get("source"))
+    retry_source_context: dict[str, Any] = {}
     if source is not None:
         handler = get_handler(source)
         source_retry_fields = handler.build_retry_resolution_fields(release_data)
-        retry_download_url = (
-            normalize_optional_text(source_retry_fields.get("retry_download_url"))
-            or retry_download_url
-        )
-        protocol = (
-            normalize_optional_text(source_retry_fields.get("retry_download_protocol")) or protocol
-        )
+        if "retry_download_url" in source_retry_fields:
+            retry_download_url = normalize_optional_text(
+                source_retry_fields.get("retry_download_url")
+            )
+        if "retry_download_protocol" in source_retry_fields:
+            protocol = normalize_optional_text(source_retry_fields.get("retry_download_protocol"))
+        raw_retry_source_context = source_retry_fields.get("retry_source_context")
+        if isinstance(raw_retry_source_context, dict):
+            retry_source_context = dict(raw_retry_source_context)
 
     ratio_limit = _optional_number(release_data.get("ratio_limit"))
     if ratio_limit is None and config.get("PROWLARR_USE_SEED_PREFERENCES", False):
@@ -202,6 +205,7 @@ def _build_retry_resolution_fields(
         ),
         "retry_ratio_limit": ratio_limit,
         "retry_seeding_time_limit_minutes": seeding_time_limit_minutes,
+        "retry_source_context": retry_source_context,
         "can_retry_without_staged_source": True,
     }
 
@@ -247,6 +251,7 @@ def queue_release(
         series_name = release_data.get("series_name") or extra.get("series_name")
         series_position = release_data.get("series_position") or extra.get("series_position")
         subtitle = release_data.get("subtitle") or extra.get("subtitle")
+        language = release_data.get("language") or extra.get("language")
 
         books_output_mode = (
             str(config.get("BOOKS_OUTPUT_MODE", "folder", user_id=user_id) or "folder")
@@ -281,6 +286,7 @@ def queue_release(
             series_name=series_name,
             series_position=series_position,
             subtitle=subtitle,
+            language=language,
             search_mode=search_mode,
             output_mode=output_mode,
             output_args=output_args,
@@ -400,6 +406,7 @@ def serialize_task_for_retry(task: DownloadTask) -> dict[str, Any]:
         search_mode = normalized_search_mode or None
 
     raw_output_args = getattr(task, "output_args", None)
+    raw_retry_source_context = getattr(task, "retry_source_context", None)
 
     return {
         "task_id": getattr(task, "task_id", None),
@@ -415,6 +422,7 @@ def serialize_task_for_retry(task: DownloadTask) -> dict[str, Any]:
         "series_name": getattr(task, "series_name", None),
         "series_position": getattr(task, "series_position", None),
         "subtitle": getattr(task, "subtitle", None),
+        "language": getattr(task, "language", None),
         "search_mode": search_mode,
         "output_mode": getattr(task, "output_mode", None),
         "output_args": dict(raw_output_args) if isinstance(raw_output_args, dict) else {},
@@ -428,6 +436,9 @@ def serialize_task_for_retry(task: DownloadTask) -> dict[str, Any]:
         "retry_expected_hash": getattr(task, "retry_expected_hash", None),
         "retry_ratio_limit": getattr(task, "retry_ratio_limit", None),
         "retry_seeding_time_limit_minutes": getattr(task, "retry_seeding_time_limit_minutes", None),
+        "retry_source_context": (
+            dict(raw_retry_source_context) if isinstance(raw_retry_source_context, dict) else {}
+        ),
         "can_retry_without_staged_source": bool(
             getattr(task, "can_retry_without_staged_source", True)
         ),
@@ -453,6 +464,7 @@ def _restore_task_from_retry_payload(payload: object) -> DownloadTask | None:
             search_mode = None
 
     output_args = payload.get("output_args")
+    retry_source_context = payload.get("retry_source_context")
 
     return DownloadTask(
         task_id=task_id,
@@ -468,6 +480,7 @@ def _restore_task_from_retry_payload(payload: object) -> DownloadTask | None:
         series_name=normalize_optional_text(payload.get("series_name")),
         series_position=_optional_number(payload.get("series_position")),
         subtitle=normalize_optional_text(payload.get("subtitle")),
+        language=normalize_optional_text(payload.get("language")),
         search_mode=search_mode,
         output_mode=normalize_optional_text(payload.get("output_mode")),
         output_args=dict(output_args) if isinstance(output_args, dict) else {},
@@ -483,6 +496,9 @@ def _restore_task_from_retry_payload(payload: object) -> DownloadTask | None:
         retry_seeding_time_limit_minutes=_optional_positive_int(
             payload.get("retry_seeding_time_limit_minutes")
         ),
+        retry_source_context=(
+            dict(retry_source_context) if isinstance(retry_source_context, dict) else {}
+        ),
         can_retry_without_staged_source=bool(payload.get("can_retry_without_staged_source", True)),
     )
 

shelfmark/download/postprocess/custom_script.py

@@ -229,6 +229,7 @@ def _build_custom_script_payload(
             "series_name": context.task.series_name,
             "series_position": context.task.series_position,
             "subtitle": context.task.subtitle,
+            "language": context.task.language,
             "original_download_path": context.task.original_download_path,
         },
         "output": {

shelfmark/download/postprocess/transfer.py

@@ -12,6 +12,7 @@ from shelfmark.core.naming import (
     assign_part_numbers,
     build_library_path,
     derive_primary_title,
+    normalize_language_code,
     parse_naming_template,
     sanitize_filename,
 )
@@ -63,6 +64,7 @@ def build_metadata_dict(task: DownloadTask) -> dict:
         "Year": task.year,
         "Series": task.series_name,
         "SeriesPosition": task.series_position,
+        "Language": normalize_language_code(task.language),
         "User": task.username,
     }
 

shelfmark/metadata_providers/README.md

@@ -24,12 +24,12 @@ Dataclass representing a book from a metadata provider:
 ```python
 @dataclass
 class BookMetadata:
-    provider: str                    # Internal provider name (e.g., "hardcover")
-    provider_id: str                 # ID in that provider's system
+    provider: str  # Internal provider name (e.g., "hardcover")
+    provider_id: str  # ID in that provider's system
     title: str
 
     # Optional fields
-    provider_display_name: str       # Human-readable name (e.g., "Hardcover")
+    provider_display_name: str  # Human-readable name (e.g., "Hardcover")
     authors: List[str]
     isbn_10: str
     isbn_13: str
@@ -39,7 +39,7 @@ class BookMetadata:
     publish_year: int
     language: str
     genres: List[str]
-    source_url: str                  # Link to book on provider's site
+    source_url: str  # Link to book on provider's site
     display_fields: List[DisplayField]  # Provider-specific display data
 ```
 
@@ -50,9 +50,9 @@ Provider-specific metadata for UI cards (ratings, page counts, reader counts, et
 ```python
 @dataclass
 class DisplayField:
-    label: str       # e.g., "Rating", "Pages", "Readers"
-    value: str       # e.g., "4.5", "496", "8,041"
-    icon: str        # Icon name: "star", "book", "users", "editions"
+    label: str  # e.g., "Rating", "Pages", "Readers"
+    value: str  # e.g., "4.5", "496", "8,041"
+    icon: str  # Icon name: "star", "book", "users", "editions"
 ```
 
 ### MetadataSearchOptions
@@ -64,7 +64,7 @@ Unified search options that work across all providers:
 class MetadataSearchOptions:
     query: str
     search_type: SearchType = SearchType.GENERAL  # GENERAL, TITLE, AUTHOR, ISBN
-    language: str = None                          # ISO 639-1 code (e.g., "en")
+    language: str = None  # ISO 639-1 code (e.g., "en")
     sort: SortOrder = SortOrder.RELEVANCE
     limit: int = 40
     page: int = 1
@@ -88,10 +88,10 @@ All providers must implement this interface:
 
 ```python
 class MetadataProvider(ABC):
-    name: str                        # Internal identifier
-    display_name: str                # Human-readable name
-    requires_auth: bool              # True if API key required
-    supported_sorts: List[SortOrder] # Supported sort options
+    name: str  # Internal identifier
+    display_name: str  # Human-readable name
+    requires_auth: bool  # True if API key required
+    supported_sorts: List[SortOrder]  # Supported sort options
 
     @abstractmethod
     def search(self, options: MetadataSearchOptions) -> List[BookMetadata]:
@@ -121,9 +121,9 @@ class MetadataProvider(ABC):
 ```python
 from shelfmark.metadata_providers import register_provider
 
+
 @register_provider("my_provider")
-class MyProvider(MetadataProvider):
-    ...
+class MyProvider(MetadataProvider): ...
 ```
 
 ### Getting Providers
@@ -281,11 +281,13 @@ from shelfmark.config.env import (
     METADATA_CACHE_BOOK_TTL,
 )
 
+
 @cacheable(ttl=METADATA_CACHE_SEARCH_TTL, key_prefix="myprovider:search")
 def _search_cached(self, cache_key: str, options: MetadataSearchOptions):
     # Cached search implementation
     pass
 
+
 @cacheable(ttl=METADATA_CACHE_BOOK_TTL, key_prefix="myprovider:book")
 def get_book(self, book_id: str):
     # Cached book lookup
@@ -302,6 +304,7 @@ from shelfmark.metadata_providers.openlibrary import RateLimiter
 # 90 requests per 60 seconds
 rate_limiter = RateLimiter(max_requests=90, window_seconds=60)
 
+
 def make_request(self):
     rate_limiter.wait_if_needed()  # Blocks if rate limited
     # ... make request

shelfmark/release_sources/__init__.py

@@ -163,6 +163,7 @@ class SortOption:
 
     label: str  # Display label in the sort dropdown
     sort_key: str  # Field to sort by on the Release object
+    default_direction: Literal["asc", "desc"] = "desc"  # Which way "best first" runs
 
 
 @dataclass
@@ -261,7 +262,12 @@ def serialize_column_config(config: ReleaseColumnConfig) -> dict[str, Any]:
     # Include extra sort options (sort entries not tied to a column)
     if config.extra_sort_options:
         result["extra_sort_options"] = [
-            {"label": opt.label, "sort_key": opt.sort_key} for opt in config.extra_sort_options
+            {
+                "label": opt.label,
+                "sort_key": opt.sort_key,
+                "default_direction": opt.default_direction,
+            }
+            for opt in config.extra_sort_options
         ]
 
     # Include action button if specified (replaces default expand search)

shelfmark/release_sources/audiobookbay/source.py

@@ -9,6 +9,7 @@ if TYPE_CHECKING:
     from shelfmark.metadata_providers import BookMetadata
 
 from shelfmark.core.config import config
+from shelfmark.core.languages import normalize_language
 from shelfmark.core.logger import setup_logger
 from shelfmark.release_sources import (
     ColumnAlign,
@@ -43,41 +44,6 @@ def _coerce_positive_int(value: object, default: int) -> int:
 
 
 # Map language names to ISO 639-1 codes (matching frontend color maps)
-LANGUAGE_MAP = {
-    "english": "en",
-    "spanish": "es",
-    "french": "fr",
-    "german": "de",
-    "italian": "it",
-    "portuguese": "pt",
-    "russian": "ru",
-    "japanese": "ja",
-    "chinese": "zh",
-    "dutch": "nl",
-    "swedish": "sv",
-    "norwegian": "no",
-    "danish": "da",
-    "finnish": "fi",
-    "polish": "pl",
-    "czech": "cs",
-    "hungarian": "hu",
-    "korean": "ko",
-    "arabic": "ar",
-    "hebrew": "he",
-    "turkish": "tr",
-    "greek": "el",
-    "hindi": "hi",
-    "thai": "th",
-    "vietnamese": "vi",
-    "indonesian": "id",
-    "ukrainian": "uk",
-    "romanian": "ro",
-    "bulgarian": "bg",
-    "catalan": "ca",
-    "croatian": "hr",
-    "slovenian": "sl",
-    "serbian": "sr",
-}
 
 
 def _split_title_and_author(raw_title: str) -> tuple[str, str | None]:
@@ -119,8 +85,9 @@ def _map_language(language: str) -> str | None:
     if not language:
         return None
 
-    lang_lower = language.lower().strip()
-    return LANGUAGE_MAP.get(lang_lower, lang_lower)
+    # Fall back to the raw value so an unrecognised language is still shown
+    # rather than silently dropped from the release row.
+    return normalize_language(language) or language.lower().strip()
 
 
 def _parse_bitrate_to_kbps(bitrate: str | None) -> int | None:

shelfmark/release_sources/direct_download.py

@@ -18,6 +18,7 @@ from bs4.element import NavigableString
 
 from shelfmark.config.env import DEBUG_SKIP_SOURCES, TMP_DIR
 from shelfmark.core.config import config
+from shelfmark.core.languages import language_alias_map
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.models import DownloadTask, SearchFilters, build_filename
 from shelfmark.core.utils import CONTENT_TYPES, get_aa_content_type_dir
@@ -267,7 +268,7 @@ def _fold_text(value: str) -> str:
 
 
 def _language_alias_to_code() -> dict[str, str]:
-    """Build alias→code map from bundled language metadata (lazy, cached)."""
+    """Alias to code map, delegating to the shared language data."""
     global _LANGUAGE_ALIAS_TO_CODE
     cached = _LANGUAGE_ALIAS_TO_CODE
     if cached is not None:
@@ -278,35 +279,7 @@ def _language_alias_to_code() -> dict[str, str]:
         if cached is not None:
             return cached
 
-        mapping: dict[str, str] = {}
-        data_path = Path(__file__).resolve().parents[2] / "data" / "book-languages.json"
-
-        try:
-            raw = json.loads(data_path.read_text(encoding="utf-8"))
-        except OSError, ValueError, TypeError:
-            _LANGUAGE_ALIAS_TO_CODE = {}
-            return _LANGUAGE_ALIAS_TO_CODE
-
-        if not isinstance(raw, list):
-            _LANGUAGE_ALIAS_TO_CODE = {}
-            return _LANGUAGE_ALIAS_TO_CODE
-
-        for item in raw:
-            if not isinstance(item, dict):
-                continue
-            code = _normalize_language_token(str(item.get("code", "")))
-            name = _normalize_language_token(str(item.get("language", "")))
-            if not code:
-                continue
-            mapping.setdefault(code, code)
-            mapping.setdefault(code.replace("-", "_"), code)
-            mapping.setdefault(code.split("-")[0], code)
-            mapping.setdefault(_fold_text(code), code)
-            if name:
-                mapping.setdefault(name, code)
-                mapping.setdefault(_fold_text(name), code)
-
-        _LANGUAGE_ALIAS_TO_CODE = mapping
+        _LANGUAGE_ALIAS_TO_CODE = language_alias_map()
         return _LANGUAGE_ALIAS_TO_CODE
 
 
@@ -1621,6 +1594,12 @@ def _extract_slow_download_url(
 
     link_texts = [a.get_text(strip=True)[:50] for a in soup.find_all("a", href=True)[:10]]
     logger.warning("No download URL found. First 10 links: %s", link_texts)
+    # A bypassed page with no AA download links often means the network served a wrong
+    # page (e.g. an ISP block page) instead of Anna's Archive. Probe for DNS interference
+    # so we can give the user an actionable hint instead of a generic failure.
+    host = urlparse(link).hostname or ""
+    if host:
+        network.note_possible_dns_interference(host)
     return ""
 
 
@@ -2053,7 +2032,14 @@ class DirectDownloadHandler(DownloadHandler):
                 return None
 
             if not success_url:
-                status_callback("error", "All download sources failed")
+                if network.dns_interference_detected():
+                    status_callback(
+                        "error",
+                        "All sources failed - your network/ISP appears to be blocking "
+                        "Anna's Archive. Enable DNS-over-HTTPS in settings.",
+                    )
+                else:
+                    status_callback("error", "All download sources failed")
                 return None
 
             # Return temp path - orchestrator handles post-processing (archive extraction, ingest)

shelfmark/release_sources/irc/client.py

@@ -25,6 +25,8 @@ logger = setup_logger(__name__)
 # Timing
 SOCKET_TIMEOUT = 300.0  # 5 minutes - long because we wait for DCC offers
 RECV_BUFFER = 4096
+# How often a deadline-bound read wakes up to re-check the clock
+POLL_INTERVAL = 2.0
 
 # IRC channel user prefixes that indicate elevated status (ops, voice, etc.)
 # These are the download bots/servers
@@ -248,11 +250,22 @@ class IRCClient:
 
                         # 366 = RPL_ENDOFNAMES - channel join is complete
                         if msg.command == "366":
-                            logger.info(
-                                "Joined #%s - %s servers online",
-                                channel,
-                                len(self.online_servers),
-                            )
+                            if not self.online_servers:
+                                # Joining a channel that doesn't exist on this network
+                                # silently creates an empty one, so an empty name list is
+                                # the only hint that the channel name is wrong.
+                                logger.warning(
+                                    "Joined #%s but no servers are online - the channel may "
+                                    "be empty or not exist on %s",
+                                    channel,
+                                    self.server,
+                                )
+                            else:
+                                logger.info(
+                                    "Joined #%s - %s servers online",
+                                    channel,
+                                    len(self.online_servers),
+                                )
                             return
 
                         # Check for errors (e.g., banned, channel doesn't exist)
@@ -296,27 +309,47 @@ class IRCClient:
         data = f"{message}\r\n".encode()
         self._socket.sendall(data)
 
-    def _recv_lines(self) -> Iterator[str]:
-        """Receive and yield complete CRLF-delimited IRC lines."""
-        sock = self._require_socket()
-        while True:
-            # Check if we have a complete line in buffer
-            while "\r\n" in self._buffer:
-                line, self._buffer = self._buffer.split("\r\n", 1)
-                if line:
-                    yield line
+    def _recv_lines(self, deadline: float | None = None) -> Iterator[str]:
+        """Receive and yield complete CRLF-delimited IRC lines.
 
-            # Read more data
-            try:
-                data = sock.recv(RECV_BUFFER)
-                if not data:
-                    return  # Connection closed
-                self._buffer += data.decode("utf-8", errors="replace")
-            except TimeoutError:
-                continue  # Keep waiting
-            except OSError as e:
-                logger.warning("Socket error: %s", e)
-                return  # Connection error
+        A deadline stops the read once it passes, even if nothing ever arrives.
+        Callers time out by watching the messages they receive, so on a channel
+        with no traffic at all there is nothing to watch: the recv would just
+        keep blocking for SOCKET_TIMEOUT and retrying forever.
+        """
+        sock = self._require_socket()
+        original_timeout = sock.gettimeout()
+
+        try:
+            while True:
+                # Check if we have a complete line in buffer
+                while "\r\n" in self._buffer:
+                    line, self._buffer = self._buffer.split("\r\n", 1)
+                    if line:
+                        yield line
+
+                if deadline is not None:
+                    remaining = deadline - time.time()
+                    if remaining <= 0:
+                        return
+                    # Wake up often enough to notice the deadline pass
+                    sock.settimeout(min(remaining, POLL_INTERVAL))
+
+                # Read more data
+                try:
+                    data = sock.recv(RECV_BUFFER)
+                    if not data:
+                        return  # Connection closed
+                    self._buffer += data.decode("utf-8", errors="replace")
+                except TimeoutError:
+                    continue  # Keep waiting (the deadline is re-checked above)
+                except OSError as e:
+                    logger.warning("Socket error: %s", e)
+                    return  # Connection error
+        finally:
+            if deadline is not None:
+                with suppress(OSError):
+                    sock.settimeout(original_timeout)
 
     def _parse_message(self, line: str) -> IRCMessage:
         """Parse an IRC message line into components.
@@ -427,9 +460,14 @@ class IRCClient:
             return False
         return True
 
-    def read_messages(self, *, auto_handle: bool = True) -> Iterator[IRCMessage]:
+    def read_messages(
+        self,
+        *,
+        auto_handle: bool = True,
+        deadline: float | None = None,
+    ) -> Iterator[IRCMessage]:
         """Read and yield IRC messages, optionally auto-handling PING/VERSION."""
-        for line in self._recv_lines():
+        for line in self._recv_lines(deadline):
             msg = self._parse_message(line)
 
             # Auto-handle certain events
@@ -453,13 +491,9 @@ class IRCClient:
     ) -> DCCOffer | None:
         """Wait for a DCC SEND offer. Returns None on timeout or no results."""
         target_event = IRCEvent.SEARCH_RESULT if result_type else IRCEvent.BOOK_RESULT
-        start = time.time()
-
-        for msg in self.read_messages():
-            if time.time() - start > timeout:
-                logger.warning("Timeout waiting for DCC offer")
-                return None
+        deadline = time.time() + timeout
 
+        for msg in self.read_messages(deadline=deadline):
             if msg.event == target_event:
                 if not self._is_allowed_dcc_sender(msg, expected_senders):
                     continue
@@ -491,6 +525,8 @@ class IRCClient:
                     count = match.group(1)
                     logger.info("Found %s matches", count)
 
+        if time.time() >= deadline:
+            logger.warning("Timeout waiting for DCC offer")
         return None
 
     @property

shelfmark/release_sources/irc/settings.py

@@ -72,7 +72,10 @@ def irc_settings() -> list[SettingsField]:
             key="IRC_CHANNEL",
             label="Channel",
             placeholder="e.g. ebooks",
-            description="Channel name without the # prefix",
+            description=(
+                "Channel name without the # prefix. Used for all searches unless a "
+                "separate audiobook channel is configured below."
+            ),
             required=True,
             env_supported=True,
         ),
@@ -95,6 +98,38 @@ def irc_settings() -> list[SettingsField]:
             required=True,
             env_supported=True,
         ),
+        HeadingField(
+            key="audiobook_heading",
+            title="Audiobooks",
+            description=(
+                "Some networks index audiobooks in a separate channel from ebooks "
+                "(for example #ebooks for ebooks and #bookz for audiobooks). "
+                "Configure that channel here to search it for audiobook requests. "
+                "Leave these blank to search the main channel above for both."
+            ),
+        ),
+        TextField(
+            key="IRC_AUDIOBOOK_CHANNEL",
+            label="Audiobook channel",
+            placeholder="e.g. bookz",
+            description=(
+                "Optional. Channel name (without the # prefix) to use for audiobook "
+                "searches. Leave blank to use the main channel above for audiobooks too."
+            ),
+            required=False,
+            env_supported=True,
+        ),
+        TextField(
+            key="IRC_AUDIOBOOK_SEARCH_BOT",
+            label="Audiobook search bot",
+            placeholder="e.g. search",
+            description=(
+                "Optional. Search bot for the audiobook channel. Leave blank to reuse "
+                "the main search bot above. Only used when an audiobook channel is set."
+            ),
+            required=False,
+            env_supported=True,
+        ),
         HeadingField(
             key="cache_heading",
             title="Search Cache",

shelfmark/release_sources/irc/source.py

@@ -240,6 +240,19 @@ class IRCReleaseSource(ReleaseSource):
         nick = _config_text("IRC_NICK")
         search_bot = _config_text("IRC_SEARCH_BOT")
 
+        # Audiobooks may be indexed in a separate channel from ebooks on some networks
+        # (e.g. #ebooks for ebooks, #bookz for audiobooks). When an audiobook channel is
+        # configured and an audiobook was requested, route the search there (with its own
+        # search bot if set). Otherwise fall back to the main channel/bot, which keeps the
+        # single-channel networks that index both formats working unchanged.
+        if is_audiobook(content_type):
+            audiobook_channel = _config_text("IRC_AUDIOBOOK_CHANNEL")
+            if audiobook_channel:
+                channel = audiobook_channel
+                audiobook_search_bot = _config_text("IRC_AUDIOBOOK_SEARCH_BOT")
+                if audiobook_search_bot:
+                    search_bot = audiobook_search_bot
+
         # Never post an unaddressed query to the channel. A bare book title looks like
         # spam to everyone else in the channel and gets the nick banned. Searches must
         # be addressed to a search bot ("@<bot> <query>").

shelfmark/release_sources/prowlarr/api.py

@@ -158,36 +158,55 @@ class ProwlarrClient:
             logger.info("Prowlarr connection successful: version %s", version)
             return True, f"Connected to Prowlarr {version}"
 
-    def get_indexers(self) -> list[dict[str, Any]]:
-        """Get all configured indexers."""
+    def get_indexers(self, *, raise_on_error: bool = False) -> list[dict[str, Any]]:
+        """Get all configured indexers.
+
+        Args:
+            raise_on_error: When True, propagate API failures instead of
+                returning an empty list. Callers that must distinguish
+                "no indexers" from "the request failed" should set this.
+
+        """
         try:
             return _normalize_json_object_list(
                 self._request("GET", "/api/v1/indexer"),
                 context="Prowlarr indexer list",
             )
         except _PROWLARR_CLIENT_ERRORS:
+            if raise_on_error:
+                raise
             logger.exception("Failed to get indexers")
             return []
 
-    def get_enabled_indexers_detailed(self) -> list[dict[str, Any]]:
+    def get_enabled_indexers_detailed(
+        self, *, raise_on_error: bool = False
+    ) -> list[dict[str, Any]]:
         """Get enabled indexers, including implementation metadata.
 
         Note: Prowlarr indexer "name" is user-configurable; prefer
         "implementation"/"implementationName" for stable identification.
         """
-        indexers = self.get_indexers()
+        indexers = self.get_indexers(raise_on_error=raise_on_error)
         return [idx for idx in indexers if idx.get("enable", False)]
 
-    def get_enriched_indexer_ids(self, *, restrict_to: list[int] | None = None) -> list[int]:
+    def get_enriched_indexer_ids(
+        self,
+        *,
+        restrict_to: list[int] | None = None,
+        indexers: list[dict[str, Any]] | None = None,
+    ) -> list[int]:
         """Return enabled indexer IDs that benefit from extra Torznab handling.
 
         Args:
             restrict_to: Optional list of candidate indexer IDs to consider.
+            indexers: Optional already-fetched enabled indexer list, so callers
+                that need the full records for other reasons can avoid a second
+                round trip.
 
         """
         enriched_ids: list[int] = []
 
-        for idx in self.get_enabled_indexers_detailed():
+        for idx in indexers if indexers is not None else self.get_enabled_indexers_detailed():
             idx_id_int = coerce_int_like(idx.get("id"))
             if idx_id_int is None:
                 continue
@@ -214,10 +233,17 @@ class ProwlarrClient:
 
         Prowlarr exposes seedTime in minutes, which is also the unit expected by
         torrent clients.
+
+        Raises:
+            requests.exceptions.RequestException (and other client errors) when
+            the indexer list cannot be fetched. An empty dict strictly means
+            "no share limits are configured", never "the request failed" -
+            callers rely on this to avoid silently dropping seed limits.
+
         """
         settings_by_indexer: dict[int, IndexerSeedSettings] = {}
 
-        for idx in self.get_enabled_indexers_detailed():
+        for idx in self.get_enabled_indexers_detailed(raise_on_error=True):
             idx_id_int = coerce_int_like(idx.get("id"))
             if idx_id_int is None:
                 continue

shelfmark/release_sources/prowlarr/handler.py

@@ -1,10 +1,15 @@
 """Prowlarr download handler - resolves releases and delegates lifecycle to shared clients."""
 
 from typing import TYPE_CHECKING, Any
+from urllib.parse import urlparse
+
+import requests
 
 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.request_helpers import normalize_optional_text
+from shelfmark.core.search_plan import build_release_search_plan
+from shelfmark.core.utils import normalize_http_url
 from shelfmark.download.clients import (
     DownloadClient,
     get_client,
@@ -23,9 +28,13 @@ from shelfmark.download.clients.base_handler import (
     DownloadRequest,
     ExternalClientHandler,
 )
+from shelfmark.metadata_providers import BookMetadata
 from shelfmark.release_sources import register_handler
-from shelfmark.release_sources.prowlarr.cache import get_release, remove_release
+from shelfmark.release_sources.prowlarr.api import IndexerSeedSettings, ProwlarrClient
+from shelfmark.release_sources.prowlarr.cache import cache_release, get_release, remove_release
+from shelfmark.release_sources.prowlarr.source import ProwlarrSource
 from shelfmark.release_sources.prowlarr.utils import (
+    build_source_id,
     coerce_int_like,
     get_preferred_download_url,
     get_protocol,
@@ -37,6 +46,16 @@ if TYPE_CHECKING:
     from shelfmark.core.models import DownloadTask
 
 logger = setup_logger(__name__)
+
+# Errors that ProwlarrClient can raise when fetching indexer settings.
+_SEED_SETTINGS_FALLBACK_ERRORS = (
+    requests.exceptions.RequestException,
+    OSError,
+    RuntimeError,
+    TypeError,
+    ValueError,
+)
+
 __all__ = [
     "ProwlarrHandler",
     "POLL_INTERVAL",
@@ -49,6 +68,11 @@ __all__ = [
 POLL_INTERVAL = _DEFAULT_POLL_INTERVAL
 COMPLETED_PATH_RETRY_INTERVAL = _DEFAULT_COMPLETED_PATH_RETRY_INTERVAL
 COMPLETED_PATH_MAX_ATTEMPTS = _DEFAULT_COMPLETED_PATH_MAX_ATTEMPTS
+EXPIRED_LINK_REFRESH_ERROR = (
+    "The indexer download link expired and the release could not be refreshed. "
+    "Search again for a fresh result."
+)
+HASH_DETECTION_ERROR = "Could not determine torrent hash from URL"
 
 
 def _coerce_positive_minutes(raw_minutes: object) -> int | None:
@@ -62,6 +86,47 @@ def _coerce_positive_minutes(raw_minutes: object) -> int | None:
 class ProwlarrHandler(ExternalClientHandler):
     """Handler for Prowlarr downloads via configured torrent or usenet client."""
 
+    @staticmethod
+    def _build_prowlarr_client() -> ProwlarrClient | None:
+        """Build a ProwlarrClient from config, or None if not configured."""
+        raw_url = config.get("PROWLARR_URL", "")
+        raw_api_key = config.get("PROWLARR_API_KEY", "")
+        url = normalize_optional_text(raw_url) if isinstance(raw_url, str) else None
+        api_key = normalize_optional_text(raw_api_key) if isinstance(raw_api_key, str) else None
+        if not url or not api_key:
+            return None
+        normalized_url = normalize_http_url(url)
+        if not normalized_url:
+            return None
+        return ProwlarrClient(normalized_url, api_key)
+
+    def _fetch_seed_settings_fallback(self, raw_indexer_id: object) -> IndexerSeedSettings | None:
+        """Fetch share limits for one indexer directly from Prowlarr.
+
+        Used when the cached release is missing its search-time seed-limit
+        enrichment so that transient failures during search cannot cause a
+        torrent to be added without its configured share limits.
+        """
+        indexer_id = coerce_int_like(raw_indexer_id)
+        if indexer_id is None:
+            return None
+
+        client = self._build_prowlarr_client()
+        if client is None:
+            return None
+
+        try:
+            settings = client.get_indexer_seed_settings(restrict_to=[indexer_id])
+        except _SEED_SETTINGS_FALLBACK_ERRORS:
+            logger.warning(
+                "Grab-time seed settings fallback failed for indexerId=%s",
+                indexer_id,
+                exc_info=True,
+            )
+            return None
+
+        return settings.get(indexer_id)
+
     def _get_client(self, protocol: str) -> DownloadClient | None:
         """Compatibility shim so module-level patching still works in tests."""
         return get_client(protocol)
@@ -81,18 +146,30 @@ class ProwlarrHandler(ExternalClientHandler):
 
     def build_retry_resolution_fields(self, release_data: dict[str, Any]) -> dict[str, Any]:
         source_id = normalize_optional_text(release_data.get("source_id"))
-        if source_id is None:
-            return {}
+        extra = release_data.get("extra")
+        if not isinstance(extra, dict):
+            extra = {}
 
-        prowlarr_result = get_release(source_id)
-        if prowlarr_result is None:
-            return {}
+        retry_source_context: dict[str, Any] = {}
+        indexer_id = release_data.get("indexer_id") or extra.get("indexer_id")
+        if indexer_id is not None:
+            retry_source_context["indexer_id"] = indexer_id
+
+        indexer = normalize_optional_text(release_data.get("indexer") or extra.get("indexer"))
+        if indexer is not None and indexer.lower() != "unknown":
+            retry_source_context["indexer"] = indexer
+
+        info_url = normalize_optional_text(release_data.get("info_url") or extra.get("info_url"))
+        if info_url is not None:
+            retry_source_context["info_url"] = info_url
+
+        if source_id is not None:
+            retry_source_context["source_id"] = source_id
 
         return {
-            "retry_download_url": normalize_optional_text(
-                get_preferred_download_url(prowlarr_result)
-            ),
-            "retry_download_protocol": normalize_optional_text(get_protocol(prowlarr_result)),
+            "retry_download_url": None,
+            "retry_download_protocol": None,
+            "retry_source_context": retry_source_context,
         }
 
     @classmethod
@@ -139,13 +216,12 @@ class ProwlarrHandler(ExternalClientHandler):
         # Look up the cached release
         prowlarr_result = get_release(task.task_id)
         if not prowlarr_result:
-            restored_request = self._restore_download_request_from_task(task)
-            if restored_request is None:
-                logger.warning("Release cache miss: %s", task.task_id)
-                status_callback("error", "Release not found in cache (may have expired)")
+            logger.info("Prowlarr release cache miss, refreshing: %s", task.task_id)
+            prowlarr_result = self._refresh_release(task)
+            if prowlarr_result is None:
+                logger.warning("Prowlarr release refresh failed: %s", task.task_id)
+                status_callback("error", EXPIRED_LINK_REFRESH_ERROR)
                 return None
-            logger.info("Restored Prowlarr download request for retry: %s", task.task_id)
-            return restored_request
 
         # Extract download URL
         download_url = get_preferred_download_url(prowlarr_result)
@@ -171,6 +247,28 @@ class ProwlarrHandler(ExternalClientHandler):
             seeding_time_limit = _coerce_positive_minutes(raw_configured_seed_time)
             ratio_limit = float(raw_configured_ratio) if raw_configured_ratio is not None else None
 
+            # Fallback: search-time enrichment can be missing when the indexer
+            # settings fetch transiently failed during the search (#795).
+            # Re-resolve the limits from Prowlarr at grab time so torrents are
+            # never sent to the client without their configured share limits.
+            if seeding_time_limit is None and ratio_limit is None and protocol == "torrent":
+                fallback = self._fetch_seed_settings_fallback(prowlarr_result.get("indexerId"))
+                if fallback:
+                    seeding_time_limit = _coerce_positive_minutes(
+                        fallback.get("seeding_time_limit_minutes")
+                    )
+                    raw_ratio = fallback.get("ratio_limit")
+                    ratio_limit = float(raw_ratio) if raw_ratio is not None else None
+
+            if seeding_time_limit is None and ratio_limit is None and protocol == "torrent":
+                logger.warning(
+                    "Prowlarr seed preferences are enabled but no share limits "
+                    "could be resolved for release '%s' (indexerId=%s); the "
+                    "torrent will use the client's global limits",
+                    release_name,
+                    prowlarr_result.get("indexerId"),
+                )
+
         return DownloadRequest(
             url=download_url,
             protocol=protocol,
@@ -180,6 +278,92 @@ class ProwlarrHandler(ExternalClientHandler):
             ratio_limit=ratio_limit,
         )
 
+    def _refresh_release(self, task: DownloadTask) -> dict[str, Any] | None:
+        """Re-query Prowlarr and cache the exact original release if it still exists."""
+        title = normalize_optional_text(task.title)
+        if title is None:
+            return None
+
+        context = getattr(task, "retry_source_context", None)
+        if not isinstance(context, dict):
+            context = {}
+
+        indexer = normalize_optional_text(context.get("indexer"))
+        book = BookMetadata(
+            provider="shelfmark",
+            provider_id=task.task_id,
+            title=title,
+            authors=[task.author] if task.author else [],
+            search_title=title,
+            search_author=task.author,
+        )
+        plan = build_release_search_plan(
+            book,
+            indexers=[indexer] if indexer is not None else None,
+        )
+
+        source = ProwlarrSource()
+        results = source.search(book, plan, content_type=task.content_type or "ebook")
+        for release in results:
+            raw_release = get_release(release.source_id)
+            if raw_release is None:
+                continue
+            if not self._raw_release_matches_task(raw_release, task.task_id):
+                continue
+
+            cache_release(task.task_id, raw_release)
+            logger.info("Refreshed Prowlarr release: %s", task.task_id)
+            return raw_release
+
+        return None
+
+    @staticmethod
+    def _raw_release_matches_task(raw_release: dict[str, Any], task_id: str) -> bool:
+        wanted = normalize_optional_text(task_id)
+        if wanted is None:
+            return False
+
+        bare = [
+            identity
+            for identity in (
+                normalize_optional_text(raw_release.get("guid")),
+                normalize_optional_text(raw_release.get("infoUrl")),
+            )
+            if identity is not None
+        ]
+
+        identities = [*bare, build_source_id(raw_release)]
+        indexer_id = coerce_int_like(raw_release.get("indexerId"))
+        if indexer_id is not None:
+            identities.extend(f"{indexer_id}:{identity}" for identity in bare)
+
+        return wanted in identities
+
+    def _refresh_download_request_after_add_failure(
+        self,
+        *,
+        task: DownloadTask,
+        request: DownloadRequest,
+        error: Exception,
+        status_callback: Callable[[str, str | None], None],
+    ) -> DownloadRequest | None:
+        """Refresh once when a cached Prowlarr torrent proxy URL has expired."""
+        if request.protocol != "torrent":
+            return None
+        if HASH_DETECTION_ERROR not in str(error):
+            return None
+
+        parsed = urlparse(request.url)
+        if parsed.scheme.lower() not in {"http", "https"}:
+            return None
+
+        logger.info("Refreshing stale Prowlarr torrent URL for %s", task.task_id)
+        remove_release(task.task_id)
+        refreshed_request = self._resolve_download(task, status_callback)
+        if refreshed_request is None:
+            raise RuntimeError(EXPIRED_LINK_REFRESH_ERROR) from error
+        return refreshed_request
+
     def _on_download_complete(self, task: DownloadTask) -> None:
         """Remove completed release from the Prowlarr cache."""
         remove_release(task.task_id)

shelfmark/release_sources/prowlarr/settings.py

@@ -190,6 +190,18 @@ def prowlarr_config_settings() -> list[SettingsField]:
             description="Automatically retry search without category filtering if no results are found",
             show_when={"field": "PROWLARR_ENABLED", "value": True},
         ),
+        CheckboxField(
+            key="PROWLARR_COLLAPSE_DUPLICATES",
+            label="Show one row per release",
+            default=True,
+            description=(
+                "Collapse a release that several indexer entries returned down to a single row, "
+                "keeping the entry with the best Prowlarr priority. Turn this off to see every "
+                "entry that carried it, which is what makes results from filter-specific entries "
+                "(freeleech and the like) visible."
+            ),
+            show_when={"field": "PROWLARR_ENABLED", "value": True},
+        ),
         CheckboxField(
             key="PROWLARR_USE_SEED_PREFERENCES",
             label="Use Prowlarr seed preferences",

shelfmark/release_sources/prowlarr/source.py

@@ -2,13 +2,17 @@
 
 import re
 import time
+from threading import Lock
 from typing import TYPE_CHECKING, ClassVar, NoReturn
 
+import requests
+
 if TYPE_CHECKING:
     from shelfmark.core.search_plan import ReleaseSearchPlan
     from shelfmark.metadata_providers import BookMetadata
 
 from shelfmark.core.config import config
+from shelfmark.core.languages import normalize_language
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.request_helpers import normalize_optional_text
 from shelfmark.core.search_plan import ReleaseSearchVariant
@@ -30,6 +34,7 @@ from shelfmark.release_sources import (
 from shelfmark.release_sources.prowlarr.api import IndexerSeedSettings, ProwlarrClient
 from shelfmark.release_sources.prowlarr.cache import cache_release
 from shelfmark.release_sources.prowlarr.utils import (
+    build_source_id,
     coerce_float_like,
     coerce_int_like,
     get_protocol,
@@ -41,6 +46,14 @@ _SIZE_UNIT_BASE = 1024
 _TWO_FORMATS = 2
 _PROWLARR_SOURCE_ERRORS = (AttributeError, OSError, RuntimeError, TypeError, ValueError)
 
+# Prowlarr indexer priority is 1-50 and lower is preferred; unknown sorts last.
+_UNRANKED_INDEXER_RANK = 51
+
+# Errors that can surface from ProwlarrClient.get_indexer_seed_settings(). The
+# client raises requests exceptions (subclasses of OSError via IOError lineage
+# is not guaranteed), so include RequestException explicitly.
+_PROWLARR_SEED_SETTINGS_ERRORS = (*_PROWLARR_SOURCE_ERRORS, requests.exceptions.RequestException)
+
 
 def _raise_timeout_error(message: str) -> NoReturn:
     raise TimeoutError(message)
@@ -61,6 +74,118 @@ def _coerce_indexer_id(value: object) -> int | None:
     return coerce_int_like(value)
 
 
+def _identity_text(value: object) -> str | None:
+    """Trimmed text for an identity field, or None when there is nothing usable."""
+    if isinstance(value, str):
+        return value.strip() or None
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return str(value)
+    return None
+
+
+def _release_identity(result: dict) -> str | None:
+    """Identify the underlying release, independent of which indexer surfaced it.
+
+    Strong identifiers only. Title is deliberately excluded because matching on
+    it here would merge two genuinely different releases that happen to share a
+    name, and every caller of this either drops or overwrites a row on a match.
+    Returns None when nothing identifies the result.
+    """
+    for field in ("guid", "downloadUrl", "magnetUrl", "infoUrl"):
+        identity = _identity_text(result.get(field))
+        if identity is not None:
+            return identity
+    return None
+
+
+def _result_dedup_key(result: dict) -> tuple[int | None, str] | None:
+    """Dedup key for a raw Prowlarr result, or None if it cannot be identified.
+
+    One tracker is often configured in Prowlarr as several indexer entries that
+    differ only by a server-side search filter, say a "freeleech only" entry
+    alongside an unfiltered one. Those entries return the same guid for the same
+    torrent, so keying on the guid alone throws away the filtered entry's copy
+    and with it the only signal that the release matched the filter. Including
+    the indexer id keeps the entries distinct.
+
+    Title is an acceptable last resort here, unlike in _release_identity, because
+    the indexer id is part of the key: it only ever collapses a literal repeat
+    from one indexer, never two rows from different entries.
+    """
+    identity = _release_identity(result) or _identity_text(result.get("title"))
+    if identity is None:
+        return None
+    return (_coerce_indexer_id(result.get("indexerId")), identity)
+
+
+def _build_indexer_priority(indexers: list[dict]) -> dict[int, int]:
+    """Map indexer id to the priority configured in Prowlarr. Lower is preferred.
+
+    Users already rank their indexers in Prowlarr, and on trackers configured as
+    several entries that ranking is usually the meaningful one: a "freeleech
+    only" entry is typically given a better priority than the unfiltered entry
+    beside it. Reusing it avoids asking for the same ordering a second time.
+    """
+    priority: dict[int, int] = {}
+    for indexer in indexers:
+        indexer_id = _coerce_indexer_id(indexer.get("id"))
+        if indexer_id is None:
+            continue
+        rank = coerce_int_like(indexer.get("priority"))
+        if rank is not None:
+            priority[indexer_id] = rank
+
+    return priority
+
+
+def _rank_for_indexer_id(indexer_id: object, priority: dict[int, int]) -> int:
+    """Preference rank for an indexer id. Lower wins, unknown ranks last."""
+    coerced = _coerce_indexer_id(indexer_id)
+    if coerced is None:
+        return _UNRANKED_INDEXER_RANK
+    return priority.get(coerced, _UNRANKED_INDEXER_RANK)
+
+
+def _indexer_rank(result: dict, priority: dict[int, int]) -> int:
+    """Preference rank of the indexer that surfaced a raw result."""
+    return _rank_for_indexer_id(result.get("indexerId"), priority)
+
+
+def _release_indexer_rank(release: Release, priority: dict[int, int]) -> int:
+    """Preference rank of the indexer that surfaced a converted release."""
+    return _rank_for_indexer_id(release.extra.get("indexer_id"), priority)
+
+
+def _collapse_duplicate_indexer_results(
+    results: list[dict], priority: dict[int, int]
+) -> list[dict]:
+    """Reduce a release to a single row, keeping the preferred indexer entry.
+
+    Opt-in behaviour for users who want one row per torrent. Ties keep the
+    result that was queried first, and the winner holds the loser's position so
+    the overall result order stays stable.
+    """
+    position_by_identity: dict[str, int] = {}
+    kept: list[dict] = []
+
+    for result in results:
+        identity = _release_identity(result)
+        if identity is None:
+            kept.append(result)
+            continue
+
+        existing_position = position_by_identity.get(identity)
+        if existing_position is None:
+            position_by_identity[identity] = len(kept)
+            kept.append(result)
+            continue
+
+        if _indexer_rank(result, priority) < _indexer_rank(kept[existing_position], priority):
+            kept[existing_position] = result
+
+    return kept
+
+
 def _parse_size(size_bytes: int | None) -> str | None:
     """Convert bytes to human-readable size string."""
     if size_bytes is None or size_bytes <= 0:
@@ -102,50 +227,6 @@ AUDIOBOOK_FORMATS = ["m4b", "mp3", "m4a", "flac", "ogg", "wma", "aac", "wav", "o
 # Combined list for format detection (audiobook formats first for priority)
 ALL_BOOK_FORMATS = AUDIOBOOK_FORMATS + EBOOK_FORMATS
 
-# Map 3-char MAM language codes to 2-char ISO codes used by frontend color maps
-MAM_LANGUAGE_MAP = {
-    "eng": "en",
-    "ita": "it",
-    "spa": "es",
-    "fra": "fr",
-    "fre": "fr",
-    "ger": "de",
-    "deu": "de",
-    "por": "pt",
-    "rus": "ru",
-    "jpn": "ja",
-    "jap": "ja",
-    "chi": "zh",
-    "zho": "zh",
-    "dut": "nl",
-    "nld": "nl",
-    "swe": "sv",
-    "nor": "no",
-    "dan": "da",
-    "fin": "fi",
-    "pol": "pl",
-    "cze": "cs",
-    "ces": "cs",
-    "hun": "hu",
-    "kor": "ko",
-    "ara": "ar",
-    "heb": "he",
-    "tur": "tr",
-    "gre": "el",
-    "ell": "el",
-    "hin": "hi",
-    "tha": "th",
-    "vie": "vi",
-    "ind": "id",
-    "ukr": "uk",
-    "rom": "ro",
-    "ron": "ro",
-    "bul": "bg",
-    "cat": "ca",
-    "hrv": "hr",
-    "slv": "sl",
-    "srp": "sr",
-}
 
 # Backend safeguard: cap total Prowlarr search time per request.
 PROWLARR_SEARCH_TIMEOUT_SECONDS = 120.0
@@ -193,8 +274,9 @@ def _extract_mam_language(raw_title: str) -> str | None:
 
         for token in tokens:
             lang_code = token.lower()
-            if lang_code in MAM_LANGUAGE_MAP:
-                return MAM_LANGUAGE_MAP[lang_code]
+            resolved = normalize_language(lang_code)
+            if resolved is not None:
+                return resolved
 
     return None
 
@@ -379,8 +461,7 @@ def _prowlarr_result_to_release(
         formats_display = _formats_display(formats)
         language_detected = _extract_mam_language(str(raw_title or ""))
 
-    # Build the source_id from GUID or generate from indexer + title
-    source_id = result.get("guid") or f"{indexer}:{hash(raw_title)}"
+    source_id = build_source_id(result)
 
     # Cache the raw Prowlarr result so handler can look it up by source_id
     cache_release(source_id, result)
@@ -443,6 +524,36 @@ def _prowlarr_result_to_release(
     )
 
 
+# Last successfully fetched per-indexer share limits. Used as a fallback when
+# a transient Prowlarr API failure prevents fetching fresh settings during a
+# search, so results are never silently cached without seed limits (#795).
+_seed_settings_lock = Lock()
+_last_known_seed_settings: dict[int, IndexerSeedSettings] = {}
+
+
+def _fetch_indexer_seed_settings(
+    client: ProwlarrClient,
+    indexer_ids: list[int] | None,
+) -> dict[int, IndexerSeedSettings]:
+    """Fetch per-indexer share limits, falling back to last-known-good on failure."""
+    try:
+        fetched = client.get_indexer_seed_settings(restrict_to=indexer_ids)
+    except _PROWLARR_SEED_SETTINGS_ERRORS:
+        with _seed_settings_lock:
+            fallback = dict(_last_known_seed_settings)
+        logger.warning(
+            "Failed to fetch Prowlarr indexer seed settings; "
+            "falling back to last known settings for %s indexer(s)",
+            len(fallback),
+            exc_info=True,
+        )
+        return fallback
+
+    with _seed_settings_lock:
+        _last_known_seed_settings.update(fetched)
+    return fetched
+
+
 def _apply_indexer_seed_settings(
     result: dict,
     indexer_seed_settings: dict[int, IndexerSeedSettings],
@@ -574,6 +685,11 @@ class ProwlarrSource(ReleaseSource):
             ],
             extra_sort_options=[
                 SortOption(label="Peers", sort_key="seeders"),
+                SortOption(
+                    label="Indexer priority",
+                    sort_key="extra.indexer_priority",
+                    default_direction="asc",
+                ),
             ],
             grid_template="minmax(0,2fr) minmax(140px,1fr) 50px 50px 90px 80px",
             leading_cell=LeadingCellConfig(
@@ -779,11 +895,15 @@ class ProwlarrSource(ReleaseSource):
         try:
             auto_expand_enabled = config.get("PROWLARR_AUTO_EXPAND", False)
             deadline = time.monotonic() + PROWLARR_SEARCH_TIMEOUT_SECONDS
+            enabled_indexers = client.get_enabled_indexers_detailed()
+            indexer_priority = _build_indexer_priority(enabled_indexers)
             # Some indexers benefit from title+author queries and extra format detection.
-            enriched_indexer_ids = client.get_enriched_indexer_ids(restrict_to=indexer_ids)
+            enriched_indexer_ids = client.get_enriched_indexer_ids(
+                restrict_to=indexer_ids, indexers=enabled_indexers
+            )
             enriched_indexer_ids_set = set(enriched_indexer_ids)
             indexer_seed_settings = (
-                client.get_indexer_seed_settings(restrict_to=indexer_ids)
+                _fetch_indexer_seed_settings(client, indexer_ids)
                 if config.get("PROWLARR_USE_SEED_PREFERENCES", False)
                 else {}
             )
@@ -821,7 +941,7 @@ class ProwlarrSource(ReleaseSource):
 
                 return results
 
-            seen_keys: set[str] = set()
+            seen_keys: set[tuple[int | None, str]] = set()
             all_results: list[dict] = []
 
             for idx, variant in enumerate(variants, start=1):
@@ -849,18 +969,22 @@ class ProwlarrSource(ReleaseSource):
                     self.last_search_type = "expanded"
 
                 for r in raw_results:
-                    key = (
-                        r.get("guid")
-                        or r.get("downloadUrl")
-                        or r.get("magnetUrl")
-                        or r.get("infoUrl")
-                        or f"{r.get('indexerId')}:{r.get('title')}"
-                    )
-                    if key in seen_keys:
-                        continue
-                    seen_keys.add(key)
+                    key = _result_dedup_key(r)
+                    if key is not None:
+                        if key in seen_keys:
+                            continue
+                        seen_keys.add(key)
                     all_results.append(r)
 
+            if config.get("PROWLARR_COLLAPSE_DUPLICATES", True):
+                before_collapse = len(all_results)
+                all_results = _collapse_duplicate_indexer_results(all_results, indexer_priority)
+                if len(all_results) != before_collapse:
+                    logger.debug(
+                        "Prowlarr: collapsed %s duplicate result(s) across indexer entries",
+                        before_collapse - len(all_results),
+                    )
+
             results: list[Release] = []
             enriched_source_ids: set[str] = set()
 
@@ -879,13 +1003,19 @@ class ProwlarrSource(ReleaseSource):
                     content_type,
                     enable_format_detection=is_enriched,
                 )
+                if idx_id_int is not None and idx_id_int in indexer_priority:
+                    release.extra["indexer_priority"] = indexer_priority[idx_id_int]
                 results.append(release)
 
                 if is_enriched:
                     enriched_source_ids.add(release.source_id)
 
-            # Sort results: enriched indexers first, then others
-            results.sort(key=lambda r: 0 if r.source_id in enriched_source_ids else 1)
+            results.sort(
+                key=lambda r: (
+                    _release_indexer_rank(r, indexer_priority),
+                    0 if r.source_id in enriched_source_ids else 1,
+                )
+            )
 
             if results:
                 torrent_count = sum(1 for r in results if r.protocol == ReleaseProtocol.TORRENT)

shelfmark/release_sources/prowlarr/utils.py

@@ -32,6 +32,28 @@ def coerce_int_like(value: object) -> int | None:
     return int(normalized)
 
 
+def build_source_id(result: dict) -> str:
+    """Build the Release.source_id for a raw Prowlarr result.
+
+    Qualified by the indexer id because one tracker is often configured in
+    Prowlarr as several indexer entries that differ only by a server-side search
+    filter, and those entries return the same guid for the same torrent. Without
+    the qualifier the entries collide in the release cache and a grab routes
+    through whichever entry happened to cache last.
+    """
+    guid = result.get("guid")
+    if guid:
+        base = str(guid)
+    else:
+        indexer = result.get("indexer", "Unknown")
+        base = f"{indexer}:{hash(result.get('title', 'Unknown'))}"
+
+    indexer_id = coerce_int_like(result.get("indexerId"))
+    if indexer_id is None:
+        return base
+    return f"{indexer_id}:{base}"
+
+
 def coerce_float_like(value: object) -> float | None:
     """Return a float for float-like config/API values, else None."""
     if isinstance(value, bool):

src/frontend/package.json

@@ -17,24 +17,24 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@tailwindcss/vite": "^4.3.0",
+    "@tailwindcss/vite": "^4.3.3",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "react-router-dom": "^7.17.0",
+    "react-router-dom": "^7.18.1",
     "socket.io-client": "^4.7.5"
   },
   "devDependencies": {
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.1.1",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.2",
-    "knip": "^6.16.1",
-    "oxfmt": "^0.54.0",
-    "oxlint": "^1.69.0",
-    "oxlint-tsgolint": "^0.23.0",
+    "@vitejs/plugin-react": "^6.0.3",
+    "knip": "^6.27.0",
+    "oxfmt": "^0.59.0",
+    "oxlint": "^1.74.0",
+    "oxlint-tsgolint": "^0.25.0",
     "tailwindcss": "^4.2.2",
-    "typescript": "^6.0.3",
-    "vite": "^8.0.16",
-    "vitest": "^4.1.8"
+    "typescript": "^7.0.2",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10"
   }
 }

src/frontend/src/App.tsx

@@ -1098,6 +1098,9 @@ function App() {
         series_name: book.series_name,
         series_position: book.series_position,
         subtitle: book.subtitle,
+        // From the release, never the book: book.language is the provider's
+        // canonical edition, which would mislabel a translated release.
+        language: release.language ?? undefined,
       };
     },
     [],

src/frontend/src/components/ReleaseCell.tsx

@@ -382,7 +382,11 @@ export const ReleaseCell = ({
           className={`flex items-center ${alignClass} gap-1.5 truncate text-xs text-gray-600 dark:text-gray-300`}
         >
           <span className={`h-2 w-2 shrink-0 rounded-full ${dotColor}`} title={protocolLabel} />
-          <span className="truncate">{displayValue}</span>
+          {/* Titled because one tracker can appear as several indexer entries whose
+              names share a prefix, and truncation would make the rows look identical */}
+          <span className="truncate" title={displayValue}>
+            {displayValue}
+          </span>
           {peers && <span className="shrink-0 text-gray-400 dark:text-gray-500">{peers}</span>}
         </div>
       );

src/frontend/src/components/ReleaseModal.tsx

@@ -956,7 +956,7 @@ const ReleaseModalSession = ({
     const fromExtra = (columnConfig.extra_sort_options || []).map((opt) => ({
       label: opt.label,
       sortKey: opt.sort_key,
-      defaultDirection: 'desc' as const, // Extra sort options are typically numeric (e.g., peers)
+      defaultDirection: opt.default_direction ?? ('desc' as const),
     }));
     return [...fromColumns, ...fromExtra];
   }, [sortableColumns, columnConfig.extra_sort_options]);

src/frontend/src/components/resultsViews/CardView.tsx

@@ -67,6 +67,7 @@ export const CardView = ({
   };
 
   return (
+    // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- mouse handlers drive a decorative hover shadow only; no interactive behavior requiring keyboard support
     <article
       className="book-card space-between animate-pop-up relative flex h-full w-full flex-col transition-shadow duration-300 max-sm:h-[180px] max-sm:flex-row sm:max-w-[292px] sm:flex-col"
       style={{

src/frontend/src/components/resultsViews/CompactView.tsx

@@ -70,6 +70,7 @@ export const CompactView = ({
   };
 
   return (
+    // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- mouse handlers drive a decorative hover shadow only; no interactive behavior requiring keyboard support
     <article
       className="book-card animate-pop-up relative flex! h-[180px]! w-full flex-row! transition-shadow duration-300"
       style={{

src/frontend/src/components/settings/SelfSettingsModal.tsx

@@ -21,7 +21,6 @@ import {
   normalizeUserOverrideSections,
   UserOverridesSections,
 } from './users';
-import type { PerUserSettings } from './users/types';
 import { UserAccountCardContent, UserEditActions, UserIdentityHeader } from './users/UserCard';
 import { useUserOverridesState } from './users/useUserOverridesState';
 
@@ -153,7 +152,7 @@ const SelfSettingsModalSession = ({
         normalizeUserOverrideSections(context.visibleUserSettingsSections, 'self'),
       );
       applyUserOverridesContext({
-        settings: (context.user.settings || {}) as PerUserSettings,
+        settings: context.user.settings || {},
         userOverridableKeys: context.userOverridableKeys || [],
       });
       setEditPassword('');

src/frontend/src/components/shared/Tooltip.tsx

@@ -188,6 +188,7 @@ export function Tooltip({
         isVisible &&
         coords &&
         createPortal(
+          // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- interactive tooltip stays open while hovered; keyboard users are served by focus handlers on the trigger element
           <div
             ref={tooltipRef}
             role="tooltip"

src/frontend/src/hooks/useUsersFetch.ts

@@ -146,7 +146,7 @@ export const useUsersFetch = ({ onShowToast }: UseUsersFetchParams) => {
     if (fullUser.settings) {
       userSettings = {
         ...fullUser.settings,
-      } as PerUserSettings;
+      };
     }
     const userOverridableSettings = new Set<string>();
 
@@ -162,7 +162,7 @@ export const useUsersFetch = ({ onShowToast }: UseUsersFetchParams) => {
         userSettings = {
           ...userSettings,
           ...deliveryResult.value.userOverrides,
-        } as PerUserSettings;
+        };
       }
       deliveryResult.value.keys.forEach((key) => userOverridableSettings.add(key));
     }
@@ -173,7 +173,7 @@ export const useUsersFetch = ({ onShowToast }: UseUsersFetchParams) => {
         userSettings = {
           ...userSettings,
           ...searchResult.value.userOverrides,
-        } as PerUserSettings;
+        };
       }
       searchResult.value.keys.forEach((key) => userOverridableSettings.add(key));
     }
@@ -184,7 +184,7 @@ export const useUsersFetch = ({ onShowToast }: UseUsersFetchParams) => {
         userSettings = {
           ...userSettings,
           ...notificationResult.value.userOverrides,
-        } as PerUserSettings;
+        };
       }
       notificationResult.value.keys.forEach((key) => userOverridableSettings.add(key));
     }

src/frontend/src/services/api.ts

@@ -500,6 +500,7 @@ export type DownloadReleasePayload = {
   series_name?: string;
   series_position?: number;
   subtitle?: string;
+  language?: string; // Release language code, for the {Language} naming variable
   search_author?: string;
   search_mode?: 'direct' | 'universal';
 };

src/frontend/src/tests/namingTemplatePreview.test.ts

@@ -48,4 +48,47 @@ describe('namingTemplatePreview', () => {
     expect(preview.unknownTokens).toEqual(['NotAThing']);
     expect(preview.value).toBe('Arthur Conan Doyle');
   });
+
+  it('offers Language as a core variable for both content types', () => {
+    const language = NAMING_TEMPLATE_TOKENS.find((token) => token.token === 'Language');
+
+    expect(language?.group).toBe('Core');
+    expect(language?.audiobookOnly).toBeFalsy();
+  });
+
+  it('separates translated editions into their own folder', () => {
+    const template = '{Author}/{Title}{ (Language)}';
+
+    const swedish = renderNamingTemplate(
+      template,
+      {
+        ...SAMPLE_NAMING_METADATA,
+        Author: 'Andy Weir',
+        Title: 'Project Hail Mary',
+        Language: 'sv',
+      },
+      { allowPathSeparators: true },
+    );
+    const english = renderNamingTemplate(
+      template,
+      { ...SAMPLE_NAMING_METADATA, Author: 'Andy Weir', Title: 'Project Hail Mary', Language: '' },
+      { allowPathSeparators: true },
+    );
+
+    expect(swedish.value).toBe('Andy Weir/Project Hail Mary (sv)');
+    expect(english.value).toBe('Andy Weir/Project Hail Mary');
+    expect(swedish.value).not.toBe(english.value);
+  });
+
+  it('keeps the picker and the known-token list in lockstep', () => {
+    // KNOWN_TOKENS is a hand-maintained duplicate of the Python list. A token
+    // added to the picker but not to it would render as an unknown variable.
+    for (const token of NAMING_TEMPLATE_TOKENS) {
+      const preview = renderNamingTemplate(`{${token.token}}`, SAMPLE_NAMING_METADATA, {
+        allowPathSeparators: true,
+      });
+
+      expect(preview.unknownTokens, `${token.token} is missing from KNOWN_TOKENS`).toEqual([]);
+    }
+  });
 });

src/frontend/src/tests/requestPayload.test.ts

@@ -138,4 +138,29 @@ describe('requestPayload utilities', () => {
     );
     expect(getRequestSuccessMessage(payloadUntitled)).toBe('Request submitted: Untitled');
   });
+
+  it('takes the language from the release, not the book', () => {
+    // book.language is the metadata provider's canonical edition. Using it would
+    // label a Swedish release "en" and put both editions back in one folder.
+    const data = buildReleaseDataFromMetadataRelease(
+      { ...baseBook, language: 'en' },
+      { ...baseRelease, language: 'sv' },
+      'ebook',
+    );
+
+    expect(data.language).toBe('sv');
+  });
+
+  it('leaves language undefined when the release has none', () => {
+    const data = buildReleaseDataFromMetadataRelease(baseBook, baseRelease, 'ebook');
+
+    expect(data.language).toBeUndefined();
+  });
+
+  it('uses the book language when browsing a source directly', () => {
+    // In direct mode the book record IS the release record.
+    const data = buildReleaseDataFromDirectBook({ ...baseBook, language: 'de' });
+
+    expect(data.language).toBe('de');
+  });
 });

src/frontend/src/types/index.ts

@@ -414,6 +414,7 @@ export interface LeadingCellConfig {
 export interface ExtraSortOption {
   label: string; // Display label in the sort dropdown
   sort_key: string; // Field to sort by on the Release object
+  default_direction?: 'asc' | 'desc'; // Which way "best first" runs (defaults to desc)
 }
 
 export interface SourceActionButton {

src/frontend/src/utils/namingTemplatePreview.ts

@@ -48,6 +48,13 @@ export const NAMING_TEMPLATE_TOKENS: NamingTemplateToken[] = [
     value: '1902',
     group: 'Core',
   },
+  {
+    token: 'Language',
+    label: 'Language',
+    description: 'Release language code, so translations do not share a folder',
+    value: 'en',
+    group: 'Core',
+  },
   {
     token: 'User',
     label: 'User',
@@ -98,6 +105,7 @@ const KNOWN_TOKENS = [
   'primarytitle',
   'originalname',
   'partnumber',
+  'language',
   'subtitle',
   'author',
   'series',

src/frontend/src/utils/requestPayload.ts

@@ -90,6 +90,7 @@ export const buildReleaseDataFromMetadataRelease = (
     series_position: book.series_position,
     series_count: book.series_count,
     subtitle: book.subtitle,
+    language: release.language,
     ...(isSourceBackedReleaseContext ? { search_mode: 'direct' as const } : {}),
   };
 };
@@ -106,6 +107,8 @@ export const buildReleaseDataFromDirectBook = (book: Book) => {
     size: book.size,
     preview: book.preview,
     content_type: 'ebook' as const,
+    // Browsing a source directly means the book record IS the release record.
+    language: book.language,
     search_mode: 'direct' as const,
   };
 };

tests/README.md

@@ -169,6 +169,7 @@ uv run pytest tests/ --cov=shelfmark -m "not integration"
 ```python
 from unittest.mock import MagicMock, patch
 
+
 class TestMyFeature:
     def test_something(self, monkeypatch):
         # Mock config values
@@ -188,6 +189,7 @@ class TestMyFeature:
 import pytest
 from .conftest import APIClient, DownloadTracker
 
+
 @pytest.mark.e2e
 class TestMyEndpoint:
     def test_endpoint_works(self, protected_api_client: APIClient):

tests/audiobookbay/test_scraper_contract.py

@@ -0,0 +1,103 @@
+"""Cluster 7 (audiobook/ABB) parse-contract guards.
+
+ABB forces ``https://`` for search and detail fetches, so it can't be exercised
+hermetically in the HTTP e2e docker platform. Its recurring bugs are instead in
+*parsing*: magnet/info-hash extraction ("Fix ABB magnet parsing", and the
+qbittorrent hash-length issue #386) and DOM/layout drift. These contract tests
+feed golden HTML through the real scraper — the same fail-on-drift philosophy as
+the AA layout-drift guard — and run in normal CI.
+
+They deliberately cover cases the existing ``test_scraper.py`` does not: info-hash
+*normalization* (whitespace/case), the in-page magnet *fallback*, and a layout
+drift that must degrade to an empty result rather than crash.
+"""
+
+from __future__ import annotations
+
+import re
+from unittest.mock import patch
+
+from shelfmark.release_sources.audiobookbay import scraper
+
+# Detail page where the Info Hash is lowercase and split by whitespace/newlines —
+# the exact shape that produced malformed magnets / wrong hash lengths (#386).
+DETAIL_HTML_MESSY_HASH = """
+<html><body><table>
+  <tr><td>Info Hash</td><td>abc123def456789012345678
+  901234567890abcd</td></tr>
+  <tr><td>Tracker 1</td><td>udp://tracker.openbittorrent.com:80</td></tr>
+</table></body></html>
+"""
+
+# Info Hash cell is junk, but a full magnet link is posted elsewhere on the page.
+DETAIL_HTML_MAGNET_FALLBACK = """
+<html><body>
+  <table><tr><td>Info Hash</td><td>n/a</td></tr></table>
+  <p>Mirror: magnet:?xt=urn:btih:1111111111111111111111111111111111111111&dn=x</p>
+</body></html>
+"""
+
+# DOM drift: results are present but the .post / .postTitle structure changed.
+SEARCH_HTML_LAYOUT_DRIFT = """
+<html><body>
+  <article class="result-card">
+    <header><a href="/abss/drifted/">Drifted Audiobook - Author</a></header>
+    <span class="lang">English</span>
+  </article>
+</body></html>
+"""
+
+
+def _patch_detail(html: str):
+    return patch(
+        "shelfmark.release_sources.audiobookbay.scraper.downloader.html_get_page",
+        return_value=html,
+    )
+
+
+def test_info_hash_is_normalized_to_canonical_btih() -> None:
+    """Whitespace/newlines are stripped and the hash upper-cased to a valid
+    40-char btih (regression for #386 / 'Fix ABB magnet parsing')."""
+    with _patch_detail(DETAIL_HTML_MESSY_HASH):
+        magnet = scraper.extract_magnet_link("https://audiobookbay.lu/abss/x/", "audiobookbay.lu")
+    assert magnet is not None, "messy-but-valid info hash should still yield a magnet"
+    btih = re.search(r"xt=urn:btih:([0-9A-Fa-f]+)", magnet)
+    assert btih is not None, magnet
+    assert btih.group(1) == "ABC123DEF456789012345678901234567890ABCD"
+    assert len(btih.group(1)) == 40
+    assert "tr=" in magnet  # tracker carried through
+
+
+def test_magnet_fallback_when_info_hash_cell_is_junk() -> None:
+    """When the Info Hash cell is invalid, the scraper recovers the hash from an
+    in-page magnet link rather than failing."""
+    with _patch_detail(DETAIL_HTML_MAGNET_FALLBACK):
+        magnet = scraper.extract_magnet_link("https://audiobookbay.lu/abss/y/", "audiobookbay.lu")
+    assert magnet is not None
+    assert "btih:1111111111111111111111111111111111111111" in magnet
+
+
+def test_missing_info_hash_returns_none_not_crash() -> None:
+    """No hash anywhere -> None (clean failure), never an exception."""
+    with _patch_detail("<html><body><p>nothing here</p></body></html>"):
+        assert (
+            scraper.extract_magnet_link("https://audiobookbay.lu/abss/z/", "audiobookbay.lu")
+            is None
+        )
+
+
+def test_search_layout_drift_degrades_to_empty() -> None:
+    """A changed results DOM yields zero parsed results without raising — the
+    ABB analogue of the AA layout-drift guard."""
+    with (
+        patch(
+            "shelfmark.release_sources.audiobookbay.scraper.downloader.html_get_page",
+            return_value=(SEARCH_HTML_LAYOUT_DRIFT, "https://audiobookbay.lu/?s=test"),
+        ),
+        patch(
+            "shelfmark.release_sources.audiobookbay.scraper.config.get",
+            return_value=0.0,
+        ),
+    ):
+        results = scraper.search_audiobookbay("test", max_pages=1, hostname="audiobookbay.lu")
+    assert results == [], f"drifted DOM should parse to no results, got {results!r}"

tests/bypass/test_internal_bypasser.py

@@ -274,6 +274,75 @@ def test_run_child_process_writes_failure_for_unexpected_exception(monkeypatch,
     assert "plain SeleniumBase startup failure" in result["traceback"]
 
 
+def test_run_child_process_applies_parent_dns_config(monkeypatch, tmp_path):
+    """Regression test for issue #1028: the helper subprocess must mirror the parent's
+    DNS provider, otherwise it pre-resolves AA hostnames against (possibly hijacked)
+    system DNS and Chrome loads the wrong page."""
+    import io
+    import json
+
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    result_path = tmp_path / "result.json"
+    request = {
+        "url": "https://annas-archive.pk/slow_download/abc/0/0",
+        "retry": 1,
+        "result_path": str(result_path),
+        "dns_config": {
+            "provider": "cloudflare",
+            "servers": ["1.1.1.1", "1.0.0.1"],
+            "doh_url": "https://cloudflare-dns.com/dns-query",
+            "doh_enabled": True,
+            "is_auto_mode": True,
+        },
+    }
+
+    applied: list[tuple] = []
+    monkeypatch.setattr(
+        internal_bypasser.network,
+        "set_dns_provider",
+        lambda provider, manual=None, *, use_doh=None: applied.append((provider, manual, use_doh)),
+    )
+    monkeypatch.setattr(internal_bypasser, "get", lambda *_a, **_k: "<html>ok</html>")
+    monkeypatch.setattr(internal_bypasser.sys, "stdin", io.StringIO(json.dumps(request)))
+
+    assert internal_bypasser._run_child_process() == 0
+    assert applied == [("cloudflare", None, True)]
+
+
+def test_apply_parent_dns_config_skips_auto_and_empty(monkeypatch):
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    calls: list = []
+    monkeypatch.setattr(
+        internal_bypasser.network,
+        "set_dns_provider",
+        lambda *a, **k: calls.append((a, k)),
+    )
+
+    internal_bypasser._apply_parent_dns_config({"provider": "auto"})
+    internal_bypasser._apply_parent_dns_config({})
+
+    assert calls == []
+
+
+def test_apply_parent_dns_config_forwards_manual_servers(monkeypatch):
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    calls: list = []
+    monkeypatch.setattr(
+        internal_bypasser.network,
+        "set_dns_provider",
+        lambda provider, manual=None, *, use_doh=None: calls.append((provider, manual, use_doh)),
+    )
+
+    internal_bypasser._apply_parent_dns_config(
+        {"provider": "manual", "servers": ["9.9.9.9"], "doh_enabled": False}
+    )
+
+    assert calls == [("manual", ["9.9.9.9"], False)]
+
+
 def test_prepare_child_browser_env_uses_writable_runtime_paths(monkeypatch, tmp_path):
     import stat
 

tests/config/test_entrypoint_permissions.py

@@ -257,3 +257,119 @@ def test_entrypoint_root_bootstrap_fails_closed_when_config_repair_fails(tmp_pat
     assert f"Configured runtime identity: {os.getuid()}:{os.getgid()}" in result.stdout
     assert f"chown -R {os.getuid()}:{os.getgid()} /path/to/config" in result.stdout
     assert "Startup mode: root" not in result.stdout
+
+
+def test_entrypoint_rejects_wireguard_in_non_root_mode(tmp_path):
+    result, _, _, _ = _run_entrypoint(tmp_path, extra_env={"USING_WIREGUARD": "true"})
+
+    assert result.returncode == 1
+    assert "USING_WIREGUARD=true requires the container to start as root." in result.stderr
+    assert "Non-root mode skips the privileged network setup WireGuard depends on." in result.stderr
+
+
+def test_entrypoint_rejects_tor_and_wireguard_together(tmp_path):
+    result, _, _, _ = _run_entrypoint(
+        tmp_path,
+        extra_env={"USING_TOR": "true", "USING_WIREGUARD": "true"},
+    )
+
+    assert result.returncode == 1
+    assert (
+        "USING_TOR and USING_WIREGUARD are mutually exclusive; enable only one egress mode."
+        in result.stderr
+    )
+    # The mutual-exclusion check must fire before either egress script runs, so
+    # neither the Tor nor the WireGuard privileged-setup errors should appear.
+    assert "requires the container to start as root" not in result.stderr
+
+
+def test_entrypoint_mutual_exclusion_precedes_tor_startup(tmp_path):
+    # Even in root mode, enabling both must fail fast on mutual exclusion rather
+    # than starting tor.sh and then aborting.
+    result, _, _, _ = _run_entrypoint(
+        tmp_path,
+        simulate_root_startup=True,
+        extra_env={"USING_TOR": "true", "USING_WIREGUARD": "true"},
+    )
+
+    assert result.returncode == 1
+    assert (
+        "USING_TOR and USING_WIREGUARD are mutually exclusive; enable only one egress mode."
+        in result.stderr
+    )
+
+
+def test_entrypoint_aborts_before_gunicorn_when_wireguard_fails(tmp_path):
+    """Security invariant: if wireguard.sh exits non-zero (any fail-closed path),
+    entrypoint.sh must abort under `set -e` so gunicorn NEVER starts. A booting
+    app after a failed egress setup would be a kill-switch bypass / IP leak.
+    """
+    # Run the REAL entrypoint from a temp cwd that provides a stub `./wireguard.sh`
+    # which exits 1, plus a stub `./tor.sh` (unused here) for completeness.
+    work = tmp_path / "work"
+    work.mkdir()
+    real_entrypoint = ENTRYPOINT_PATH.read_text()
+    (work / "entrypoint.sh").write_text(real_entrypoint)
+    (work / "entrypoint.sh").chmod(0o755)
+    _write_executable(
+        work / "wireguard.sh",
+        "#!/bin/sh\necho 'stub wireguard.sh failing closed' >&2\nexit 1\n",
+    )
+    _write_executable(work / "tor.sh", "#!/bin/sh\nexit 0\n")
+
+    bin_dir, runtime_home_file, runtime_args_file = _build_stub_bin(tmp_path)
+    config_dir = tmp_path / "config"
+    config_dir.mkdir(exist_ok=True)
+
+    env = os.environ.copy()
+    env.update(
+        {
+            "BUILD_VERSION": "test-build",
+            "CONFIG_DIR": str(config_dir),
+            "DEBUG": "false",
+            "ENABLE_LOGGING": "false",
+            "ENTRYPOINT_GUNICORN_ARGS_FILE": str(runtime_args_file),
+            "ENTRYPOINT_GUNICORN_HOME_FILE": str(runtime_home_file),
+            "ENTRYPOINT_REAL_ID": ID_PATH,
+            "ENTRYPOINT_REAL_MKDIR": MKDIR_PATH,
+            "ENTRYPOINT_REAL_STAT": STAT_PATH,
+            "ENTRYPOINT_STUB_GID": str(os.getgid()),
+            "ENTRYPOINT_STUB_HOME": str(tmp_path / "runtime-home"),
+            "ENTRYPOINT_STUB_UID": str(os.getuid()),
+            # Root startup so the WireGuard branch runs ./wireguard.sh (our stub).
+            "ENTRYPOINT_STUB_CURRENT_GID": "0",
+            "ENTRYPOINT_STUB_CURRENT_UID": "0",
+            "ENTRYPOINT_STUB_STAT_OWNER": "0:0",
+            "FLASK_PORT": "8084",
+            "LOG_LEVEL": "info",
+            "LOG_ROOT": str(tmp_path / "logs"),
+            "PATH": f"{bin_dir}:{env.get('PATH', '')}",
+            "PGID": str(os.getgid()),
+            "PUID": str(os.getuid()),
+            "RELEASE_VERSION": "test-release",
+            "TMP_DIR": str(tmp_path / "tmp"),
+            "TZ": "",
+            "USING_EXTERNAL_BYPASSER": "true",
+            "USING_WIREGUARD": "true",
+        }
+    )
+
+    with _entrypoint_lock():
+        result = subprocess.run(
+            [BASH_PATH, str(work / "entrypoint.sh")],
+            capture_output=True,
+            cwd=work,
+            env=env,
+            text=True,
+            check=False,
+        )
+
+    # Entrypoint must have aborted with the stub's non-zero status...
+    assert result.returncode != 0
+    # ...the failure must actually come from wireguard.sh (not some unrelated
+    # earlier abort), proven by the stub's marker on stderr...
+    assert "stub wireguard.sh failing closed" in result.stderr
+    # ...and gunicorn must NEVER have been invoked (args file never written).
+    assert not runtime_args_file.exists(), (
+        "gunicorn was started despite wireguard.sh failing — kill-switch bypass!"
+    )

tests/config/test_environment.py

@@ -507,6 +507,15 @@ class TestConcurrencyConfiguration:
         assert interval >= 1
         assert interval <= 10
 
+    def test_completed_path_timeout_default(self):
+        """Completed external-client path wait should default to the legacy grace period."""
+        from shelfmark.core.config import config
+
+        config.refresh()
+
+        timeout = config.get("DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT", 60)
+        assert timeout == 60
+
 
 # =============================================================================
 # Cache Configuration Tests

tests/config/test_generate_env_docs.py

@@ -53,7 +53,7 @@ def test_generated_env_docs_include_custom_component_value_fields() -> None:
 
     assert (
         "| `TEMPLATE_AUDIOBOOK_ORGANIZE` | Use / to create folders. Variables: "
-        "{Author}, {Title}, {Year}, {User}, {OriginalName} "
+        "{Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} "
         "(source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, "
         "{PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix:"
     ) in docs

tests/config/test_security_handlers.py

@@ -0,0 +1,82 @@
+"""Tests for the OIDC Test Connection handler."""
+
+from unittest.mock import MagicMock, patch
+
+from shelfmark.config.security_handlers import check_oidc_connection
+
+DISCOVERY_URL = "https://auth.example.com/.well-known/openid-configuration"
+
+DISCOVERY_DOCUMENT = {
+    "issuer": "https://auth.example.com",
+    "authorization_endpoint": "https://auth.example.com/authorize",
+    "token_endpoint": "https://auth.example.com/token",
+    "jwks_uri": "https://auth.example.com/jwks",
+}
+
+
+def _mock_response(payload):
+    response = MagicMock()
+    response.json.return_value = payload
+    response.raise_for_status.return_value = None
+    return response
+
+
+def _run_check(responses):
+    """Run check_oidc_connection with requests.get returning the given responses."""
+    with (
+        patch("requests.get", side_effect=responses) as mock_get,
+        patch("shelfmark.config.security_handlers.get_ssl_verify", return_value=True),
+    ):
+        result = check_oidc_connection(
+            load_security_config=lambda: {"OIDC_DISCOVERY_URL": DISCOVERY_URL},
+            current_values={},
+            logger=MagicMock(),
+        )
+    return result, mock_get
+
+
+class TestCheckOIDCConnection:
+    def test_succeeds_when_discovery_and_jwks_are_valid(self):
+        responses = [
+            _mock_response(DISCOVERY_DOCUMENT),
+            _mock_response({"keys": [{"kty": "RSA", "kid": "abc"}]}),
+        ]
+        result, mock_get = _run_check(responses)
+        assert result["success"] is True
+        assert "Connected to" in result["message"]
+        jwks_call = mock_get.call_args_list[1]
+        assert jwks_call.args[0] == DISCOVERY_DOCUMENT["jwks_uri"]
+
+    def test_fails_with_signing_key_guidance_when_jwks_is_empty(self):
+        responses = [
+            _mock_response(DISCOVERY_DOCUMENT),
+            _mock_response({}),
+        ]
+        result, _ = _run_check(responses)
+        assert result["success"] is False
+        assert "no token signing keys" in result["message"]
+        assert "Signing Key" in result["message"]
+
+    def test_fails_with_signing_key_guidance_when_jwks_keys_list_is_empty(self):
+        responses = [
+            _mock_response(DISCOVERY_DOCUMENT),
+            _mock_response({"keys": []}),
+        ]
+        result, _ = _run_check(responses)
+        assert result["success"] is False
+        assert "no token signing keys" in result["message"]
+
+    def test_fails_when_discovery_document_missing_jwks_uri(self):
+        document = {k: v for k, v in DISCOVERY_DOCUMENT.items() if k != "jwks_uri"}
+        responses = [_mock_response(document)]
+        result, _ = _run_check(responses)
+        assert result["success"] is False
+        assert "jwks_uri" in result["message"]
+
+    def test_fails_when_jwks_request_errors(self):
+        jwks_response = MagicMock()
+        jwks_response.raise_for_status.side_effect = RuntimeError("boom")
+        responses = [_mock_response(DISCOVERY_DOCUMENT), jwks_response]
+        result, _ = _run_check(responses)
+        assert result["success"] is False
+        assert "Connection failed" in result["message"]

tests/config/test_tor_script_rules.py

@@ -1,9 +1,20 @@
 from __future__ import annotations
 
+import os
+import shutil
+import signal
+import socket
+import subprocess
+from contextlib import suppress
 from pathlib import Path
 
+import pytest
+
 TOR_SCRIPT_PATH = Path(__file__).resolve().parents[2] / "tor.sh"
 
+IPTABLES_BLOCK_START = 'echo "[*] Setting up iptables rules..."'
+IPTABLES_BLOCK_END = 'echo "[✓] Transparent Tor routing enabled."'
+
 
 def _generated_tor_healthcheck_script() -> str:
     script = TOR_SCRIPT_PATH.read_text()
@@ -14,17 +25,208 @@ def _generated_tor_healthcheck_script() -> str:
 
 
 def _tor_script_rule_lines() -> list[str]:
-    return [
-        line.strip()
-        for line in TOR_SCRIPT_PATH.read_text().splitlines()
-        if line.strip().startswith("iptables ")
-    ]
+    """Return the iptables invocations in tor.sh, in file order.
+
+    Rules that are applied on a best-effort basis are written as
+    ``if iptables ...; then``, so the shell wrapper is stripped to keep the
+    ordering assertions below comparing rules rather than syntax.
+    """
+    lines = []
+    for raw_line in TOR_SCRIPT_PATH.read_text().splitlines():
+        line = raw_line.strip().removeprefix("if ")
+        if line.startswith("iptables "):
+            lines.append(line)
+    return lines
 
 
 def _line_index(lines: list[str], needle: str) -> int:
     return next(index for index, line in enumerate(lines) if needle in line)
 
 
+def _tor_iptables_block() -> str:
+    """Extract the firewall setup section of tor.sh so it can be executed."""
+    script = TOR_SCRIPT_PATH.read_text()
+    start = script.index(IPTABLES_BLOCK_START)
+    end = script.index(IPTABLES_BLOCK_END)
+    return script[start:end]
+
+
+# Verbatim stderr of an iptables build whose kernel lacks the xt_owner module,
+# as reported from Synology DSM in issue #1150.
+MISSING_XT_OWNER_STDERR = (
+    "Warning: Extension owner revision 0 not supported, missing kernel module?\n"
+    "iptables: No chain/target/match by that name.\n"
+)
+
+IPTABLES_STUB = f"""#!/bin/bash
+if [ "$FAKE_OWNER_MATCH_SUPPORTED" != "1" ]; then
+    case "$*" in
+        *--uid-owner*)
+            printf '%s' {MISSING_XT_OWNER_STDERR!r} >&2
+            exit 1
+            ;;
+    esac
+fi
+echo "$*" >> "$FAKE_IPTABLES_LOG"
+exit 0
+"""
+
+# tor.sh resolves the Tor uid with `id -u debian-tor`; that account only exists
+# inside the image, so stub it out with the uid the Debian tor package uses.
+ID_STUB = """#!/bin/bash
+echo 107
+"""
+
+
+def _run_tor_iptables_block(tmp_path: Path, *, owner_match_supported: bool):
+    """Run tor.sh's firewall block against a fake iptables.
+
+    Returns the completed process plus the rules the fake iptables accepted.
+    """
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    for name, source in (("iptables", IPTABLES_STUB), ("id", ID_STUB)):
+        stub = bin_dir / name
+        stub.write_text(source)
+        stub.chmod(0o755)
+
+    applied_rules_log = tmp_path / "applied-rules.log"
+    # tor.sh runs under `set -e`, which is what turns a rejected rule into a
+    # container restart loop, so reproduce that here.
+    result = subprocess.run(
+        ["bash", "-c", "set -e\n" + _tor_iptables_block()],
+        capture_output=True,
+        text=True,
+        env={
+            "PATH": f"{bin_dir}:/usr/bin:/bin",
+            "FAKE_IPTABLES_LOG": str(applied_rules_log),
+            "FAKE_OWNER_MATCH_SUPPORTED": "1" if owner_match_supported else "0",
+        },
+    )
+    applied_rules = applied_rules_log.read_text().splitlines() if applied_rules_log.exists() else []
+    return result, applied_rules
+
+
+requires_bash = pytest.mark.skipif(
+    shutil.which("bash") is None, reason="bash is required to execute tor.sh"
+)
+
+# The watchdog shells out to `timeout`, which is not present on stock macOS.
+requires_timeout = pytest.mark.skipif(
+    shutil.which("timeout") is None, reason="coreutils timeout is required"
+)
+
+SUPERVISORCTL_STUB = """#!/bin/bash
+# Emulates `supervisorctl status tor`. Normally reports FAKE_TOR_STATE, but when
+# FAKE_TOR_FAIL_FIRST is set the first call reports a transient failure so the
+# watchdog's retry behaviour can be exercised.
+if [ -n "$FAKE_TOR_FAIL_FIRST" ] && [ ! -f "$FAKE_TOR_CALL_MARKER" ]; then
+    touch "$FAKE_TOR_CALL_MARKER"
+    echo "tor    FATAL     Exited too quickly"
+    exit 3
+fi
+echo "tor    $FAKE_TOR_STATE   pid 42, uptime 0:01:00"
+"""
+
+
+def _watchdog_path_env(bin_dir: Path) -> str:
+    """PATH exposing the stubs plus the real bash/timeout the watchdog calls."""
+    parts = [str(bin_dir)]
+    for tool in ("bash", "timeout"):
+        resolved = shutil.which(tool)
+        if resolved:
+            parts.append(str(Path(resolved).parent))
+    parts += ["/usr/bin", "/bin"]
+    return ":".join(parts)
+
+
+def _run_tor_watchdog(
+    tmp_path: Path,
+    *,
+    tor_state: str = "RUNNING",
+    bootstrapped: bool = True,
+    trans_port_open: bool = True,
+    fail_first: bool = False,
+    run_for: float = 2.0,
+):
+    """Run tor.sh's watchdog against a fake Tor and see if it resets the container.
+
+    Returns ``(reset_signal, stdout)`` where ``reset_signal`` is the signal the
+    stand-in for PID 1 received, or ``None`` if it was left alone.
+    """
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    supervisorctl = bin_dir / "supervisorctl"
+    supervisorctl.write_text(SUPERVISORCTL_STUB)
+    supervisorctl.chmod(0o755)
+
+    notices_log = tmp_path / "notices.log"
+    notices_log.write_text(
+        "Bootstrapped 100%: Done\n" if bootstrapped else "Bootstrapped 45%: Loading\n"
+    )
+
+    script = tmp_path / "tor_healthcheck.sh"
+    script.write_text(_generated_tor_healthcheck_script())
+    script.chmod(0o755)
+
+    listener = socket.socket()
+    listener.bind(("127.0.0.1", 0))
+    trans_port = listener.getsockname()[1]
+    if trans_port_open:
+        listener.listen(5)
+    else:
+        # Closing it leaves a port nothing is listening on, which is what a dead
+        # or wedged Tor looks like from the outside.
+        listener.close()
+
+    # Stands in for PID 1: the watchdog signals it instead of dumb-init.
+    container_process = subprocess.Popen(
+        ["sleep", "120"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
+    )
+
+    env = {
+        "PATH": _watchdog_path_env(bin_dir),
+        "TOR_CHECK_INTERVAL": "0.2",
+        "TOR_NOTICES_LOG": str(notices_log),
+        "TOR_TRANS_PORT": str(trans_port),
+        "TOR_CONTAINER_PID": str(container_process.pid),
+        "FAKE_TOR_STATE": tor_state,
+        "FAKE_TOR_CALL_MARKER": str(tmp_path / "supervisorctl.called"),
+    }
+    if fail_first:
+        env["FAKE_TOR_FAIL_FIRST"] = "1"
+
+    watchdog = subprocess.Popen(
+        ["bash", str(script)],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        env=env,
+        start_new_session=True,
+    )
+    try:
+        try:
+            container_process.wait(timeout=run_for)
+        except subprocess.TimeoutExpired:
+            pass
+        reset_signal = (
+            -container_process.returncode if container_process.poll() is not None else None
+        )
+    finally:
+        # Only the watchdog gets its own session; signalling the group is how we
+        # reap the `sleep` and `timeout` children it spawns.
+        with suppress(ProcessLookupError, PermissionError):
+            os.killpg(os.getpgid(watchdog.pid), signal.SIGKILL)
+        with suppress(ProcessLookupError):
+            container_process.kill()
+        with suppress(OSError):
+            listener.close()
+        container_process.wait()
+        stdout = watchdog.communicate()[0] or ""
+
+    return reset_signal, stdout
+
+
 def test_tor_nat_rules_bypass_private_networks_before_tcp_redirect():
     lines = _tor_script_rule_lines()
     tcp_redirect_index = _line_index(lines, "--syn -j REDIRECT --to-ports 9040")
@@ -63,3 +265,119 @@ def test_tor_healthcheck_uses_local_tor_state_without_clear_net_probe():
     assert "curl " not in healthcheck_script
     assert "supervisorctl status tor" in healthcheck_script
     assert "Bootstrapped 100%" in healthcheck_script
+
+
+@requires_bash
+def test_tor_iptables_setup_survives_kernel_without_owner_match(tmp_path):
+    """Regression test for issue #1150.
+
+    Synology (and other NAS/embedded) kernels ship without xt_owner. The owner
+    exemption is a best-effort optimisation, so a kernel that rejects it must
+    not abort tor.sh and put the container into a restart loop.
+    """
+    result, _ = _run_tor_iptables_block(tmp_path, owner_match_supported=False)
+
+    assert result.returncode == 0, (
+        "tor.sh aborted on a kernel without xt_owner:\n"
+        f"stdout:\n{result.stdout}\nstderr:\n{result.stderr}"
+    )
+
+
+@requires_bash
+def test_tor_routing_still_applied_when_owner_match_unsupported(tmp_path):
+    """Degrading past the owner rule must not skip the rules that torify traffic."""
+    _, applied_rules = _run_tor_iptables_block(tmp_path, owner_match_supported=False)
+
+    assert any("--syn -j REDIRECT --to-ports 9040" in rule for rule in applied_rules)
+    for cidr in ("127.0.0.0/8", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"):
+        assert any(f"-d {cidr} -j RETURN" in rule for rule in applied_rules)
+    for protocol in ("udp", "tcp"):
+        assert any(f"-p {protocol} --dport 53" in rule for rule in applied_rules)
+
+
+@requires_bash
+def test_tor_warns_when_owner_match_unsupported(tmp_path):
+    """The degraded path has to be visible in the logs, not silent."""
+    result, _ = _run_tor_iptables_block(tmp_path, owner_match_supported=False)
+
+    assert "owner" in result.stdout.lower()
+    assert "[!]" in result.stdout
+
+
+@requires_bash
+def test_tor_exempts_own_traffic_when_owner_match_supported(tmp_path):
+    """On a normal kernel the exemption must still be installed."""
+    result, applied_rules = _run_tor_iptables_block(tmp_path, owner_match_supported=True)
+
+    assert result.returncode == 0, result.stderr
+    owner_rules = [rule for rule in applied_rules if "--uid-owner" in rule]
+    assert len(owner_rules) == 1
+    assert "-j RETURN" in owner_rules[0]
+
+    owner_index = applied_rules.index(owner_rules[0])
+    redirect_index = next(
+        index for index, rule in enumerate(applied_rules) if "--syn -j REDIRECT" in rule
+    )
+    assert owner_index < redirect_index
+
+
+@requires_bash
+@requires_timeout
+def test_tor_watchdog_resets_container_when_tor_dies(tmp_path):
+    """A Tor that is no longer running must take the container down with it."""
+    reset_signal, stdout = _run_tor_watchdog(tmp_path, tor_state="STOPPED")
+
+    assert reset_signal == signal.SIGTERM, f"container was not reset:\n{stdout}"
+
+
+@requires_bash
+@requires_timeout
+def test_tor_watchdog_resets_container_when_tor_stops_accepting_connections(tmp_path):
+    """Tor can be 'running' yet unusable; the container must still be reset."""
+    reset_signal, stdout = _run_tor_watchdog(tmp_path, tor_state="RUNNING", trans_port_open=False)
+
+    assert reset_signal == signal.SIGTERM, f"container was not reset:\n{stdout}"
+
+
+@requires_bash
+@requires_timeout
+def test_tor_watchdog_leaves_healthy_tor_alone(tmp_path):
+    """A healthy Tor must never be reset, no matter how many cycles run."""
+    reset_signal, stdout = _run_tor_watchdog(tmp_path)
+
+    assert reset_signal is None, f"healthy Tor was reset:\n{stdout}"
+
+
+@requires_bash
+@requires_timeout
+def test_tor_watchdog_retries_once_before_resetting(tmp_path):
+    """A single transient failure is retried, not escalated to a reset."""
+    reset_signal, stdout = _run_tor_watchdog(tmp_path, fail_first=True)
+
+    assert reset_signal is None, f"transient failure caused a reset:\n{stdout}"
+    assert "Healthcheck failed (1/2)" in stdout
+    assert "Tor recovered." in stdout
+
+
+@requires_bash
+@requires_timeout
+def test_tor_watchdog_waits_for_first_bootstrap_before_policing(tmp_path):
+    """A slow first bootstrap must not be mistaken for a failure.
+
+    Otherwise every user on a slow link would be reset into a restart loop
+    before Tor ever had a chance to come up.
+    """
+    reset_signal, stdout = _run_tor_watchdog(
+        tmp_path, tor_state="STOPPED", bootstrapped=False, trans_port_open=False
+    )
+
+    assert reset_signal is None, f"reset during initial bootstrap:\n{stdout}"
+    assert "Waiting for initial Tor bootstrap" in stdout
+
+
+def test_tor_watchdog_escalates_to_container_reset_not_in_place_restart():
+    """The watchdog must signal PID 1 rather than bounce Tor under supervisor."""
+    healthcheck_script = _generated_tor_healthcheck_script()
+
+    assert "kill -TERM" in healthcheck_script
+    assert "supervisorctl restart" not in healthcheck_script

tests/conftest.py

@@ -29,6 +29,16 @@ sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 import pytest
 
 
+@pytest.fixture(autouse=True)
+def _clear_torrent_fetch_cache():
+    """Keep the shared torrent fetch cache from leaking between tests."""
+    from shelfmark.download.clients.torrent_utils import clear_torrent_fetch_cache
+
+    clear_torrent_fetch_cache()
+    yield
+    clear_torrent_fetch_cache()
+
+
 @pytest.fixture
 def sample_prowlarr_result():
     """Sample Prowlarr API search result."""

tests/core/fixtures/language_alias_baseline.json

@@ -0,0 +1,280 @@
+{
+  "_comment": "Frozen snapshot of the per-source language handling as it was before consolidation into shelfmark.core.languages. prowlarr_three_letter and audiobookbay_names were explicit maps; direct_download_derived is what its loader built from the data file, including the underscore spelling of a hyphenated code. Every alias here must still resolve to the same code. The one deliberate change: Traditional Chinese was canonically 'zh‑Hant' with a U+2011 non-breaking hyphen and is now the ASCII 'zh-Hant', so expectations for it name the new code while the old spelling remains a resolvable alias.",
+  "audiobookbay_names": {
+    "afrikaans": "af",
+    "arabic": "ar",
+    "bangla": "bn",
+    "bengali": "bn",
+    "bosnian": "bs",
+    "bulgarian": "bg",
+    "burmese": "my",
+    "catalan": "ca",
+    "chinese": "zh",
+    "croatian": "hr",
+    "czech": "cs",
+    "danish": "da",
+    "dutch": "nl",
+    "english": "en",
+    "estonian": "et",
+    "farsi": "fa",
+    "filipino": "fil",
+    "finnish": "fi",
+    "french": "fr",
+    "german": "de",
+    "greek": "el",
+    "gujarati": "gu",
+    "hebrew": "he",
+    "hindi": "hi",
+    "hungarian": "hu",
+    "icelandic": "is",
+    "indonesian": "id",
+    "irish": "ga",
+    "italian": "it",
+    "japanese": "ja",
+    "javanese": "jv",
+    "kannada": "kn",
+    "korean": "ko",
+    "latin": "la",
+    "latvian": "lv",
+    "lithuanian": "lt",
+    "malay": "ms",
+    "malayalam": "ml",
+    "manx": "gv",
+    "marathi": "mr",
+    "norwegian": "no",
+    "persian": "fa",
+    "polish": "pl",
+    "portuguese": "pt",
+    "punjabi": "pa",
+    "romanian": "ro",
+    "russian": "ru",
+    "sanskrit": "sa",
+    "scottish gaelic": "gd",
+    "serbian": "sr",
+    "slovenian": "sl",
+    "spanish": "es",
+    "swedish": "sv",
+    "tagalog": "fil",
+    "tamil": "ta",
+    "telugu": "te",
+    "thai": "th",
+    "turkish": "tr",
+    "ukrainian": "uk",
+    "urdu": "ur",
+    "vietnamese": "vi"
+  },
+  "direct_download_derived": {
+    "af": "af",
+    "afrikaans": "af",
+    "albanian": "sq",
+    "ar": "ar",
+    "arabic": "ar",
+    "armenian": "hy",
+    "az": "az",
+    "azerbaijani": "az",
+    "ba": "ba",
+    "bangla": "bn",
+    "bashkir": "ba",
+    "be": "be",
+    "belarusian": "be",
+    "bg": "bg",
+    "bn": "bn",
+    "bo": "bo",
+    "bulgarian": "bg",
+    "ca": "ca",
+    "catalan": "ca",
+    "chinese": "zh",
+    "croatian": "hr",
+    "cs": "cs",
+    "czech": "cs",
+    "da": "da",
+    "danish": "da",
+    "de": "de",
+    "dutch": "nl",
+    "el": "el",
+    "en": "en",
+    "english": "en",
+    "eo": "eo",
+    "es": "es",
+    "esperanto": "eo",
+    "fa": "fa",
+    "fi": "fi",
+    "fil": "fil",
+    "filipino": "fil",
+    "finnish": "fi",
+    "fr": "fr",
+    "french": "fr",
+    "ga": "ga",
+    "galician": "gl",
+    "georgian": "ka",
+    "german": "de",
+    "gl": "gl",
+    "greek": "el",
+    "gu": "gu",
+    "gujarati": "gu",
+    "he": "he",
+    "hebrew": "he",
+    "hi": "hi",
+    "hindi": "hi",
+    "hr": "hr",
+    "hu": "hu",
+    "hungarian": "hu",
+    "hy": "hy",
+    "id": "id",
+    "indonesian": "id",
+    "irish": "ga",
+    "it": "it",
+    "italian": "it",
+    "ja": "ja",
+    "japanese": "ja",
+    "javanese": "jv",
+    "jv": "jv",
+    "ka": "ka",
+    "kannada": "kn",
+    "kazakh": "kk",
+    "kinyarwanda": "rw",
+    "kk": "kk",
+    "kn": "kn",
+    "ko": "ko",
+    "korean": "ko",
+    "ky": "ky",
+    "kyrgyz": "ky",
+    "la": "la",
+    "latin": "la",
+    "latvian": "lv",
+    "lithuanian": "lt",
+    "lt": "lt",
+    "lv": "lv",
+    "malay": "ms",
+    "malayalam": "ml",
+    "marathi": "mr",
+    "ml": "ml",
+    "mn": "mn",
+    "mongolian": "mn",
+    "mr": "mr",
+    "ms": "ms",
+    "nl": "nl",
+    "no": "no",
+    "norwegian": "no",
+    "pa": "pa",
+    "persian": "fa",
+    "pl": "pl",
+    "polish": "pl",
+    "portuguese": "pt",
+    "pt": "pt",
+    "punjabi": "pa",
+    "qu": "qu",
+    "quechua": "qu",
+    "ro": "ro",
+    "romanian": "ro",
+    "ru": "ru",
+    "russian": "ru",
+    "rw": "rw",
+    "serbian": "sr",
+    "shan": "shn",
+    "shn": "shn",
+    "sk": "sk",
+    "sl": "sl",
+    "slovak": "sk",
+    "slovenian": "sl",
+    "spanish": "es",
+    "sq": "sq",
+    "sr": "sr",
+    "sv": "sv",
+    "sw": "sw",
+    "swahili": "sw",
+    "swedish": "sv",
+    "ta": "ta",
+    "tamil": "ta",
+    "te": "te",
+    "telugu": "te",
+    "th": "th",
+    "thai": "th",
+    "tibetan": "bo",
+    "tr": "tr",
+    "traditional chinese": "zh-Hant",
+    "turkish": "tr",
+    "ug": "ug",
+    "uk": "uk",
+    "ukrainian": "uk",
+    "ur": "ur",
+    "urdu": "ur",
+    "uyghur": "ug",
+    "vi": "vi",
+    "vietnamese": "vi",
+    "zh": "zh",
+    "zh‑hant": "zh-Hant"
+  },
+  "prowlarr_three_letter": {
+    "afr": "af",
+    "ara": "ar",
+    "ben": "bn",
+    "bos": "bs",
+    "bul": "bg",
+    "bur": "my",
+    "cat": "ca",
+    "ces": "cs",
+    "chi": "zh",
+    "cze": "cs",
+    "dan": "da",
+    "deu": "de",
+    "dut": "nl",
+    "ell": "el",
+    "eng": "en",
+    "est": "et",
+    "fas": "fa",
+    "fin": "fi",
+    "fra": "fr",
+    "fre": "fr",
+    "ger": "de",
+    "gla": "gd",
+    "gle": "ga",
+    "glv": "gv",
+    "gre": "el",
+    "guj": "gu",
+    "heb": "he",
+    "hin": "hi",
+    "hrv": "hr",
+    "hun": "hu",
+    "ice": "is",
+    "ind": "id",
+    "isl": "is",
+    "ita": "it",
+    "jap": "ja",
+    "jav": "jv",
+    "jpn": "ja",
+    "kan": "kn",
+    "kor": "ko",
+    "lat": "la",
+    "lav": "lv",
+    "lit": "lt",
+    "mal": "ml",
+    "mar": "mr",
+    "may": "ms",
+    "msa": "ms",
+    "mya": "my",
+    "nld": "nl",
+    "nor": "no",
+    "pan": "pa",
+    "per": "fa",
+    "pol": "pl",
+    "por": "pt",
+    "rom": "ro",
+    "ron": "ro",
+    "rus": "ru",
+    "san": "sa",
+    "slv": "sl",
+    "spa": "es",
+    "srp": "sr",
+    "swe": "sv",
+    "tam": "ta",
+    "tel": "te",
+    "tgl": "fil",
+    "tha": "th",
+    "tur": "tr",
+    "ukr": "uk",
+    "urd": "ur",
+    "vie": "vi",
+    "zho": "zh"
+  }
+}

tests/core/test_config_api.py

@@ -131,3 +131,46 @@ def test_frontend_dist_resolves_from_repo_root(main_module):
 
     assert main_module.PROJECT_ROOT == expected_project_root
     assert main_module.FRONTEND_DIST == expected_project_root / "frontend-dist"
+
+
+def test_config_endpoint_serves_languages_without_resolution_aliases(main_module, client):
+    """book_languages is a client contract, not a dump of the language data file.
+
+    data/book-languages.json also carries the aliases used to resolve a source's
+    spelling of a language to a code. Those are server-side only: the frontend
+    Language type is {code, language}, and shipping the aliases inflated every
+    config response by around 40%.
+    """
+    _set_session(client, user_id="reader-1", db_user_id=1, is_admin=False)
+
+    with (
+        patch("shelfmark.config.env._is_config_dir_writable", return_value=True),
+        patch("shelfmark.core.onboarding.is_onboarding_complete", return_value=True),
+    ):
+        resp = client.get("/api/config")
+
+    assert resp.status_code == 200
+    languages = resp.get_json()["book_languages"]
+
+    assert languages, "no languages served"
+    offending = [entry for entry in languages if set(entry) != {"code", "language"}]
+    assert offending == [], f"unexpected keys leaked to clients: {offending[:3]}"
+
+
+def test_language_data_file_is_only_read_by_the_shared_module(main_module):
+    """Reading data/book-languages.json anywhere else reintroduces the drift the
+    shared module exists to prevent, and bypasses the alias handling."""
+    del main_module
+
+    repo_root = Path(__file__).resolve().parents[2]
+    allowed = {Path("shelfmark/core/languages.py")}
+
+    offenders = []
+    for path in (repo_root / "shelfmark").rglob("*.py"):
+        relative = path.relative_to(repo_root)
+        if relative in allowed:
+            continue
+        if "book-languages" in path.read_text(encoding="utf-8"):
+            offenders.append(str(relative))
+
+    assert offenders == [], f"should use shelfmark.core.languages instead: {offenders}"

tests/core/test_language_template_variable.py

@@ -0,0 +1,196 @@
+"""Tests for the {Language} template variable.
+
+Different-language editions of one book resolve to the same title, so without a
+language token they render to the same path and land in one folder. Audiobookshelf
+treats a folder as exactly one library item, so the two editions become a single
+book with both files as tracks (calibrain/shelfmark#1138).
+"""
+
+import pytest
+
+from shelfmark.core.models import DownloadTask
+from shelfmark.core.naming import (
+    KNOWN_TOKENS,
+    normalize_language_code,
+    parse_naming_template,
+)
+from shelfmark.download.orchestrator import (
+    _restore_task_from_retry_payload,
+    serialize_task_for_retry,
+)
+from shelfmark.download.postprocess.transfer import build_metadata_dict
+
+
+class TestLanguageInKnownTokens:
+    def test_language_in_known_tokens(self):
+        assert "language" in KNOWN_TOKENS
+
+    def test_language_token_parsed(self):
+        assert parse_naming_template("{Language}", {"Language": "sv"}) == "sv"
+
+    def test_language_token_case_insensitive(self):
+        assert parse_naming_template("{language}", {"Language": "sv"}) == "sv"
+
+
+class TestKnownTokensOrdering:
+    """find_placeholder() does a substring find over KNOWN_TOKENS in list order.
+
+    Nothing else guards this contract, so a future token added in the wrong
+    position would silently shadow an existing one.
+    """
+
+    def test_tokens_are_ordered_longest_first(self):
+        lengths = [len(token) for token in KNOWN_TOKENS]
+        assert lengths == sorted(lengths, reverse=True)
+
+    def test_no_token_is_shadowed_by_an_earlier_substring(self):
+        for shorter_index, shorter in enumerate(KNOWN_TOKENS):
+            for longer_index, longer in enumerate(KNOWN_TOKENS):
+                if shorter is longer or shorter not in longer:
+                    continue
+                assert shorter_index > longer_index, (
+                    f"{shorter!r} precedes {longer!r} and would shadow it"
+                )
+
+
+class TestLanguageTemplateSubstitution:
+    """The acceptance cases from the issue."""
+
+    TEMPLATE = "{Author}/{Title}{ (Language)}/{Author} - {Title}"
+    BASE = {"Author": "Andy Weir", "Title": "Project Hail Mary"}
+
+    def test_translated_edition_gets_its_own_folder(self):
+        result = parse_naming_template(
+            self.TEMPLATE, {**self.BASE, "Language": "sv"}, allow_path_separators=True
+        )
+        assert result == "Andy Weir/Project Hail Mary (sv)/Andy Weir - Project Hail Mary"
+
+    def test_untagged_edition_is_unchanged(self):
+        result = parse_naming_template(
+            self.TEMPLATE, {**self.BASE, "Language": None}, allow_path_separators=True
+        )
+        assert result == "Andy Weir/Project Hail Mary/Andy Weir - Project Hail Mary"
+
+    def test_the_two_editions_do_not_collide(self):
+        english = parse_naming_template(
+            self.TEMPLATE, {**self.BASE, "Language": None}, allow_path_separators=True
+        )
+        swedish = parse_naming_template(
+            self.TEMPLATE, {**self.BASE, "Language": "sv"}, allow_path_separators=True
+        )
+        assert english != swedish
+
+    def test_language_as_a_leading_folder(self):
+        result = parse_naming_template(
+            "{Language/}{Author}/{Title}",
+            {**self.BASE, "Language": "sv"},
+            allow_path_separators=True,
+        )
+        assert result == "sv/Andy Weir/Project Hail Mary"
+
+    def test_language_in_a_filename_template(self):
+        result = parse_naming_template(
+            "{Author} - {Title}{ (Language)}", {**self.BASE, "Language": "sv"}
+        )
+        assert result == "Andy Weir - Project Hail Mary (sv)"
+
+    def test_language_is_sanitized(self):
+        result = parse_naming_template("{Title}{ (Language)}", {"Title": "Book", "Language": "s/v"})
+        assert "/" not in result
+
+
+class TestNormalizeLanguageCode:
+    def test_lowercases(self):
+        assert normalize_language_code("EN") == "en"
+        assert normalize_language_code("Sv") == "sv"
+
+    def test_strips_whitespace(self):
+        assert normalize_language_code("  sv  ") == "sv"
+
+    def test_placeholders_render_empty(self):
+        for placeholder in ("unknown", "unk", "n/a", "na", "-", "--", "none", "null", ""):
+            assert normalize_language_code(placeholder) == "", placeholder
+
+    def test_placeholders_are_matched_case_insensitively(self):
+        assert normalize_language_code("Unknown") == ""
+
+    def test_none_renders_empty(self):
+        assert normalize_language_code(None) == ""
+
+
+class TestBuildMetadataWithLanguage:
+    def test_language_reaches_the_template_metadata(self):
+        task = DownloadTask(task_id="t", source="prowlarr", title="Book", language="sv")
+        assert build_metadata_dict(task)["Language"] == "sv"
+
+    def test_language_is_normalized_on_the_way_out(self):
+        task = DownloadTask(task_id="t", source="prowlarr", title="Book", language="SV")
+        assert build_metadata_dict(task)["Language"] == "sv"
+
+    def test_placeholder_language_does_not_reach_the_path(self):
+        # Anna's Archive reports the literal string "unknown" when it cannot tell.
+        task = DownloadTask(task_id="t", source="direct", title="Book", language="unknown")
+        assert build_metadata_dict(task)["Language"] == ""
+
+    def test_missing_language_renders_empty(self):
+        task = DownloadTask(task_id="t", source="prowlarr", title="Book")
+        assert build_metadata_dict(task)["Language"] == ""
+
+
+class TestLanguageSurvivesRetry:
+    """DownloadTask is not rebuilt from dataclasses.fields(), so each of the
+    three orchestrator sites has to carry the field explicitly."""
+
+    def test_roundtrip_preserves_language(self):
+        task = DownloadTask(task_id="t", source="prowlarr", title="Book", language="sv")
+        restored = _restore_task_from_retry_payload(serialize_task_for_retry(task))
+        assert restored is not None
+        assert restored.language == "sv"
+
+    def test_legacy_payload_without_language_restores_cleanly(self):
+        task = DownloadTask(task_id="t", source="prowlarr", title="Book", language="sv")
+        payload = serialize_task_for_retry(task)
+        del payload["language"]
+
+        restored = _restore_task_from_retry_payload(payload)
+
+        assert restored is not None
+        assert restored.language is None
+
+
+class TestEverySpellingCollapsesToOneFolder:
+    """Sources report the same language differently; if the token rendered each
+    spelling verbatim they would land in separate folders, which is the exact
+    collision this token exists to prevent (reported on PR #1142)."""
+
+    TEMPLATE = "{Author}/{Title}{ (Language)}/{Title}"
+
+    def _folder(self, language):
+        task = DownloadTask(
+            task_id="t", source="prowlarr", title="Dune", author="Frank Herbert", language=language
+        )
+        return parse_naming_template(
+            self.TEMPLATE, build_metadata_dict(task), allow_path_separators=True
+        )
+
+    @pytest.mark.parametrize(
+        "spellings",
+        [
+            ("en", "eng", "English", "english", "ENG", "  Eng  "),
+            ("sv", "swe", "Swedish"),
+            ("de", "ger", "deu", "German"),
+            ("ml", "mal", "Malayalam"),
+            ("fa", "per", "fas", "Farsi", "Persian"),
+        ],
+    )
+    def test_all_spellings_of_a_language_share_one_folder(self, spellings):
+        rendered = {self._folder(spelling) for spelling in spellings}
+        assert len(rendered) == 1, f"{spellings} produced {sorted(rendered)}"
+
+    def test_a_language_we_cannot_resolve_is_kept_rather_than_dropped(self):
+        # It still separates editions, and cannot collide with a resolved code
+        # precisely because nothing resolves to it.
+        assert "klingon" in self._folder("Klingon")
+
+    def test_different_languages_still_get_different_folders(self):
+        assert self._folder("English") != self._folder("Swedish")

tests/core/test_languages.py

@@ -0,0 +1,256 @@
+"""Tests for the shared language resolution used by every release source."""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from shelfmark.core.languages import (
+    LANGUAGE_DATA_PATH,
+    known_language_codes,
+    language_alias_map,
+    language_name,
+    normalize_language,
+    supported_book_languages,
+)
+
+BASELINE = json.loads(
+    (Path(__file__).parent / "fixtures" / "language_alias_baseline.json").read_text(
+        encoding="utf-8"
+    )
+)
+
+
+class TestBaselineEquivalence:
+    """Every alias the per-source maps used to handle must still resolve the same.
+
+    These maps lived in prowlarr/source.py and audiobookbay/source.py before they
+    were consolidated here. The fixture is a frozen snapshot taken before the
+    move, so a regression shows up as a concrete alias rather than a vague
+    behaviour change.
+    """
+
+    @pytest.mark.parametrize(
+        ("alias", "expected"), sorted(BASELINE["prowlarr_three_letter"].items())
+    )
+    def test_prowlarr_three_letter_aliases_unchanged(self, alias, expected):
+        assert normalize_language(alias) == expected
+
+    @pytest.mark.parametrize(("alias", "expected"), sorted(BASELINE["audiobookbay_names"].items()))
+    def test_audiobookbay_names_unchanged(self, alias, expected):
+        assert normalize_language(alias) == expected
+
+    @pytest.mark.parametrize(
+        ("alias", "expected"), sorted(BASELINE["direct_download_derived"].items())
+    )
+    def test_direct_download_derived_aliases_unchanged(self, alias, expected):
+        # Direct Download built its aliases from the data file rather than a
+        # literal map, so consolidating silently dropped the spellings it
+        # derived -- notably the underscore form of a hyphenated code.
+        assert normalize_language(alias) == expected
+
+
+class TestNormalizeLanguage:
+    def test_accepts_two_letter_codes(self):
+        assert normalize_language("en") == "en"
+        assert normalize_language("sv") == "sv"
+
+    def test_accepts_three_letter_codes_in_both_iso_639_2_forms(self):
+        # Bibliographic and terminological forms differ for these.
+        assert normalize_language("ger") == normalize_language("deu") == "de"
+        assert normalize_language("fre") == normalize_language("fra") == "fr"
+        assert normalize_language("per") == normalize_language("fas") == "fa"
+        assert normalize_language("ice") == normalize_language("isl") == "is"
+        assert normalize_language("may") == normalize_language("msa") == "ms"
+
+    def test_accepts_english_names(self):
+        assert normalize_language("Swedish") == "sv"
+        assert normalize_language("Scottish Gaelic") == "gd"
+
+    def test_is_case_and_whitespace_insensitive(self):
+        assert normalize_language("  ENG  ") == "en"
+        assert normalize_language("sWeDiSh") == "sv"
+
+    def test_returns_none_for_placeholders(self):
+        for placeholder in ("unknown", "unk", "n/a", "na", "-", "--", "none", "null", "", "   "):
+            assert normalize_language(placeholder) is None, placeholder
+
+    def test_returns_none_for_unknown_values(self):
+        assert normalize_language("xyz") is None
+        assert normalize_language("Klingon") is None
+
+    def test_returns_none_for_none(self):
+        assert normalize_language(None) is None
+
+
+class TestLanguageData:
+    def test_every_alias_resolves_to_a_known_code(self):
+        codes = known_language_codes()
+        assert set(language_alias_map().values()) <= codes
+
+    def test_codes_are_ascii(self):
+        # "zh-Hant" once used a U+2011 non-breaking hyphen, which silently
+        # defeats any comparison against the normal spelling.
+        entries = json.loads(LANGUAGE_DATA_PATH.read_text(encoding="utf-8"))
+        assert [e["code"] for e in entries if not e["code"].isascii()] == []
+
+    def test_codes_are_unique(self):
+        entries = json.loads(LANGUAGE_DATA_PATH.read_text(encoding="utf-8"))
+        codes = [e["code"] for e in entries]
+        assert len(codes) == len(set(codes))
+
+    def test_language_name_round_trips(self):
+        assert language_name("sv") == "Swedish"
+        assert language_name("ml") == "Malayalam"
+        assert language_name("zzz") is None
+        assert language_name(None) is None
+
+
+class TestMyAnonamouseCoverage:
+    """MyAnonamouse offers 62 languages and Prowlarr passes its code through
+    untransformed, so every one has to resolve here or the language is lost."""
+
+    # Observed in live MyAnonamouse data via Prowlarr.
+    OBSERVED = {"ENG": "en", "SWE": "sv", "MAL": "ml"}
+
+    @pytest.mark.parametrize(("tag", "expected"), sorted(OBSERVED.items()))
+    def test_observed_tags_resolve(self, tag, expected):
+        assert normalize_language(tag) == expected
+
+    def test_every_offered_language_resolves(self):
+        # Names as MyAnonamouse's own searchLanguages selector lists them.
+        offered = [
+            "English",
+            "Afrikaans",
+            "Arabic",
+            "Bengali",
+            "Bosnian",
+            "Bulgarian",
+            "Burmese",
+            "Catalan",
+            "Chinese",
+            "Croatian",
+            "Czech",
+            "Danish",
+            "Dutch",
+            "Estonian",
+            "Farsi",
+            "Finnish",
+            "French",
+            "German",
+            "Greek",
+            "Gujarati",
+            "Hebrew",
+            "Hindi",
+            "Hungarian",
+            "Icelandic",
+            "Indonesian",
+            "Irish",
+            "Italian",
+            "Japanese",
+            "Javanese",
+            "Kannada",
+            "Korean",
+            "Lithuanian",
+            "Latin",
+            "Latvian",
+            "Malay",
+            "Malayalam",
+            "Manx",
+            "Marathi",
+            "Norwegian",
+            "Polish",
+            "Portuguese",
+            "Punjabi",
+            "Romanian",
+            "Russian",
+            "Scottish Gaelic",
+            "Sanskrit",
+            "Serbian",
+            "Slovenian",
+            "Spanish",
+            "Swedish",
+            "Tagalog",
+            "Tamil",
+            "Telugu",
+            "Thai",
+            "Turkish",
+            "Ukrainian",
+            "Urdu",
+            "Vietnamese",
+        ]
+        unresolved = [name for name in offered if normalize_language(name) is None]
+        assert unresolved == []
+
+
+class TestSupportedBookLanguages:
+    """What the settings dropdown and /api/config expose to clients."""
+
+    def test_exposes_only_the_fields_clients_declare(self):
+        # The frontend Language type is {code, language}. Aliases are an
+        # implementation detail and would bloat every /api/config response.
+        entries = supported_book_languages()
+        assert entries
+        assert all(set(e) == {"code", "language"} for e in entries)
+
+    def test_covers_every_known_code(self):
+        assert {e["code"] for e in supported_book_languages()} == set(known_language_codes())
+
+
+class TestLegacyTraditionalChineseCode:
+    """Traditional Chinese was stored with a U+2011 non-breaking hyphen.
+
+    The canonical code is now the ASCII spelling, but anything persisted
+    earlier still carries U+2011, so both have to resolve to the same language
+    or those users lose their selection (reported on PR #1142).
+    """
+
+    LEGACY = "zh\u2011Hant"
+    CANONICAL = "zh-Hant"
+
+    def test_the_legacy_spelling_still_resolves(self):
+        assert normalize_language(self.LEGACY) == self.CANONICAL
+
+    def test_both_spellings_are_the_same_language(self):
+        assert normalize_language(self.LEGACY) == normalize_language(self.CANONICAL)
+
+    def test_the_legacy_spelling_really_does_use_a_different_character(self):
+        # Guards the test itself: if this ever became a plain hyphen the two
+        # cases above would pass for the wrong reason.
+        assert self.LEGACY != self.CANONICAL
+        assert not self.LEGACY.isascii()
+
+    @pytest.mark.parametrize("dash", ["-", "\u2010", "\u2011", "\u2012", "\u2013", "\u2014"])
+    def test_any_dash_variant_resolves(self, dash):
+        assert normalize_language(f"zh{dash}Hant") == self.CANONICAL
+
+
+class TestCodesDoNotShadowEachOther:
+    """A code must never resolve to a different language than itself.
+
+    'zh' and 'zh-Hant' are distinct entries; registering the base of a
+    hyphenated code as an alias made 'zh' resolve correctly only because
+    Chinese happens to appear first in the data file.
+    """
+
+    def test_chinese_does_not_resolve_to_traditional_chinese(self):
+        assert normalize_language("zh") == "zh"
+        assert normalize_language("zh-Hant") == "zh-Hant"
+
+    def test_every_code_resolves_to_itself(self):
+        for code in known_language_codes():
+            assert normalize_language(code) == code, f"{code} resolved elsewhere"
+
+
+class TestSubtagSeparators:
+    """The U+2011 in the old Traditional Chinese code renders close enough to
+    both a hyphen and an underscore that either is a plausible thing to type."""
+
+    @pytest.mark.parametrize("separator", ["-", "_", "‐", "‑", "–", "—"])
+    def test_any_separator_spelling_resolves(self, separator):
+        assert normalize_language(f"zh{separator}Hant") == "zh-Hant"
+
+    def test_separators_do_not_merge_unrelated_codes(self):
+        # Folding a separator must not make one language answer to another.
+        assert normalize_language("zh") == "zh"
+        assert normalize_language("en_GB") is None

tests/core/test_oidc_routes.py

@@ -413,6 +413,43 @@ class TestOIDCCallbackEndpoint:
         assert error is not None
         assert "issuer validation failed" in error
 
+    @patch("shelfmark.core.oidc_routes._get_oidc_client")
+    def test_callback_redirects_with_signing_key_guidance_on_empty_jwks(
+        self, mock_get_client, client
+    ):
+        fake_client = Mock()
+        fake_client.authorize_access_token.side_effect = KeyError("keys")
+        fake_client.fetch_jwk_set.return_value = {}
+        mock_get_client.return_value = (fake_client, MOCK_OIDC_CONFIG)
+
+        resp = client.get("/api/auth/oidc/callback?code=abc123&state=test-state")
+        error = _get_oidc_error(resp)
+        assert error is not None
+        assert "no token signing keys" in error
+        assert "Signing Key" in error
+
+    @patch("shelfmark.core.oidc_routes._get_oidc_client")
+    def test_callback_uses_generic_error_when_jwks_has_keys(self, mock_get_client, client):
+        fake_client = Mock()
+        fake_client.authorize_access_token.side_effect = KeyError("keys")
+        fake_client.fetch_jwk_set.return_value = {"keys": [{"kty": "RSA", "kid": "abc"}]}
+        mock_get_client.return_value = (fake_client, MOCK_OIDC_CONFIG)
+
+        resp = client.get("/api/auth/oidc/callback?code=abc123&state=test-state")
+        error = _get_oidc_error(resp)
+        assert error == "Authentication failed"
+
+    @patch("shelfmark.core.oidc_routes._get_oidc_client")
+    def test_callback_uses_generic_error_when_jwks_diagnosis_fails(self, mock_get_client, client):
+        fake_client = Mock()
+        fake_client.authorize_access_token.side_effect = KeyError("keys")
+        fake_client.fetch_jwk_set.side_effect = RuntimeError("jwks fetch failed")
+        mock_get_client.return_value = (fake_client, MOCK_OIDC_CONFIG)
+
+        resp = client.get("/api/auth/oidc/callback?code=abc123&state=test-state")
+        error = _get_oidc_error(resp)
+        assert error == "Authentication failed"
+
     @patch("shelfmark.core.oidc_routes._get_oidc_client")
     def test_callback_redirects_when_auto_provision_disabled_and_no_email_match(
         self, mock_get_client, client

tests/core/test_part_number_extraction.py

@@ -43,10 +43,10 @@ class TestNaturalSortKey:
             "file10.mp3",
         ]
 
-    def test_uses_filename_only(self):
+    def test_uses_full_path(self):
         files = [Path("/z/dir/file1.mp3"), Path("/a/dir/file2.mp3")]
         sorted_files = sorted(files, key=natural_sort_key)
-        assert sorted_files[0].name == "file1.mp3"
+        assert sorted_files == [Path("/a/dir/file2.mp3"), Path("/z/dir/file1.mp3")]
 
 
 class TestAssignPartNumbers:
@@ -72,6 +72,23 @@ class TestAssignPartNumbers:
             (Path("Chapter 10.mp3"), "03"),
         ]
 
+    def test_nested_folders_are_numbered_in_folder_order(self):
+        files = [
+            Path("06_Side 6/002.mp3"),
+            Path("01_Side 1/001.mp3"),
+            Path("00_Introduction/001_About.mp3"),
+            Path("06_Side 6/001.mp3"),
+            Path("01_Side 1/002.mp3"),
+        ]
+
+        assert assign_part_numbers(files) == [
+            (Path("00_Introduction/001_About.mp3"), "01"),
+            (Path("01_Side 1/001.mp3"), "02"),
+            (Path("01_Side 1/002.mp3"), "03"),
+            (Path("06_Side 6/001.mp3"), "04"),
+            (Path("06_Side 6/002.mp3"), "05"),
+        ]
+
     def test_custom_zero_padding(self):
         files = [Path("a.mp3"), Path("b.mp3")]
         assert assign_part_numbers(files, zero_pad_width=3) == [
@@ -190,7 +207,10 @@ class TestEdgeCases:
     def test_identical_filenames_different_dirs(self):
         files = [Path("/dir2/track.mp3"), Path("/dir1/track.mp3")]
         result = assign_part_numbers(files)
-        assert len(result) == 2
+        assert result == [
+            (Path("/dir1/track.mp3"), "01"),
+            (Path("/dir2/track.mp3"), "02"),
+        ]
 
     def test_unicode_filenames(self):
         files = [Path("日本語タイトル 02.mp3"), Path("日本語タイトル 01.mp3")]

tests/download/test_doh_resolver_mock.py

@@ -0,0 +1,79 @@
+"""DoH resolver integration against the e2e platform's mock DoH responder.
+
+The config-cluster analysis flagged DNS/DoH as a recurring break surface (#1028,
+#108). A fully hermetic DoH-over-the-network profile isn't feasible in the HTTP
+docker platform (DoH provider URLs are HTTPS + IP-pinned), so we exercise the
+*real* ``DoHResolver`` client against the platform's mock ``doh`` role here, over
+plain HTTP on localhost. This runs in normal CI (not just the nightly docker
+matrix) and guards the DoH JSON-parsing path the app relies on.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import threading
+from pathlib import Path
+from wsgiref.simple_server import WSGIServer, make_server
+
+import pytest
+
+MOCK_PATH = Path(__file__).resolve().parents[1] / "e2e" / "platform" / "mocks" / "mock_services.py"
+
+
+def _load_mock_doh_app(doh_map: str):
+    """Import the platform mock_services module wired for the ``doh`` role.
+
+    The module wires its routes at import time from ``MOCK_ROLE``/``DOH_MAP``, so
+    those must be set before loading it.
+    """
+    os.environ["MOCK_ROLE"] = "doh"
+    os.environ["DOH_MAP"] = doh_map
+    spec = importlib.util.spec_from_file_location("mock_doh_services", MOCK_PATH)
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.app
+
+
+@pytest.fixture(scope="module")
+def doh_url():
+    if not MOCK_PATH.exists():
+        pytest.skip(f"platform mock not found at {MOCK_PATH}")
+    app = _load_mock_doh_app("aa.mock.test=172.30.0.10,cf.mock.test=172.30.0.11")
+    server: WSGIServer = make_server("127.0.0.1", 0, app)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        # Google JSON DoH style uses the /resolve endpoint.
+        yield f"http://127.0.0.1:{server.server_port}/resolve"
+    finally:
+        server.shutdown()
+
+
+def _resolver(doh_url: str):
+    from shelfmark.download.network import DoHResolver
+
+    # hostname/ip args are the DoH server's own identity (used only for recursion
+    # avoidance); the localhost values here are irrelevant to the lookups under test.
+    return DoHResolver(doh_url, "127.0.0.1", "127.0.0.1")
+
+
+def test_doh_resolves_mapped_host(doh_url) -> None:
+    """The real DoH client parses the mock's JSON answer into an A record."""
+    assert _resolver(doh_url).resolve("aa.mock.test", "A") == ["172.30.0.10"]
+
+
+def test_doh_nxdomain_returns_empty_not_error(doh_url) -> None:
+    """An unmapped name yields an empty list (Status 3), not an exception —
+    the path that, when mishandled, surfaced as silent download failures."""
+    assert _resolver(doh_url).resolve("unmapped.invalid", "A") == []
+
+
+def test_doh_resolver_caches_within_ttl(doh_url) -> None:
+    """A second lookup is served from cache (the resolver's documented behaviour)."""
+    resolver = _resolver(doh_url)
+    first = resolver.resolve("cf.mock.test", "A")
+    assert first == ["172.30.0.11"]
+    assert ("cf.mock.test", "A") in resolver._cache
+    assert resolver.resolve("cf.mock.test", "A") == first

tests/download/test_network_dns_failover.py

@@ -137,3 +137,135 @@ def test_system_failover_getaddrinfo_retries_after_dns_switch(monkeypatch):
     assert result == [
         (network.socket.AF_INET, network.socket.SOCK_STREAM, 6, "", ("203.0.113.10", 443))
     ]
+
+
+def _addrinfo(ip):
+    return [(2, 1, 6, "", (ip, 443))]
+
+
+class _FakeDoHResolver:
+    def __init__(self, ips):
+        self._ips = ips
+
+    def resolve(self, _hostname, _record_type):
+        return list(self._ips)
+
+
+def test_build_detection_doh_resolver_uses_selected_provider(monkeypatch):
+    import shelfmark.download.network as network
+
+    monkeypatch.setattr(
+        network,
+        "DNS_PROVIDERS",
+        [
+            ("cloudflare", ["1.1.1.1", "1.0.0.1"], "https://cloudflare-dns.com/dns-query"),
+            ("quad9", ["9.9.9.9", "149.112.112.112"], "https://dns.quad9.net/dns-query"),
+        ],
+    )
+    monkeypatch.setattr(network, "_current_dns_index", 1)  # user selected quad9
+
+    resolver = network._build_detection_doh_resolver()
+
+    assert resolver is not None
+    assert resolver.base_url == "https://dns.quad9.net/dns-query"
+    assert resolver.hostname == "dns.quad9.net"
+    assert resolver.ip == "9.9.9.9"
+
+
+def test_build_detection_doh_resolver_falls_back_to_first_provider(monkeypatch):
+    import shelfmark.download.network as network
+
+    monkeypatch.setattr(
+        network,
+        "DNS_PROVIDERS",
+        [
+            ("cloudflare", ["1.1.1.1", "1.0.0.1"], "https://cloudflare-dns.com/dns-query"),
+            ("quad9", ["9.9.9.9"], "https://dns.quad9.net/dns-query"),
+        ],
+    )
+    monkeypatch.setattr(network, "_current_dns_index", -1)  # system / not yet rotated
+
+    resolver = network._build_detection_doh_resolver()
+
+    assert resolver is not None
+    assert resolver.base_url == "https://cloudflare-dns.com/dns-query"
+    assert resolver.ip == "1.1.1.1"
+
+
+def test_detect_dns_interference_flags_divergent_resolvers(monkeypatch):
+    import shelfmark.download.network as network
+
+    # System DNS (hijacked) returns an ISP block-page IP; DoH returns the real one.
+    monkeypatch.setattr(network, "original_getaddrinfo", lambda *a, **k: _addrinfo("198.51.100.1"))
+    monkeypatch.setattr(
+        network, "_build_detection_doh_resolver", lambda: _FakeDoHResolver(["203.0.113.7"])
+    )
+
+    result = network.detect_dns_interference("annas-archive.pk")
+
+    assert result == {"system_ips": ["198.51.100.1"], "doh_ips": ["203.0.113.7"]}
+
+
+def test_detect_dns_interference_none_when_resolvers_agree(monkeypatch):
+    import shelfmark.download.network as network
+
+    monkeypatch.setattr(network, "original_getaddrinfo", lambda *a, **k: _addrinfo("203.0.113.7"))
+    monkeypatch.setattr(
+        network, "_build_detection_doh_resolver", lambda: _FakeDoHResolver(["203.0.113.7"])
+    )
+
+    assert network.detect_dns_interference("annas-archive.pk") is None
+
+
+def test_detect_dns_interference_none_when_doh_unavailable(monkeypatch):
+    import shelfmark.download.network as network
+
+    monkeypatch.setattr(network, "original_getaddrinfo", lambda *a, **k: _addrinfo("198.51.100.1"))
+    monkeypatch.setattr(network, "_build_detection_doh_resolver", lambda: None)
+
+    assert network.detect_dns_interference("annas-archive.pk") is None
+
+
+def test_detect_dns_interference_skips_ip_and_local(monkeypatch):
+    import shelfmark.download.network as network
+
+    def _should_not_run():
+        raise AssertionError("resolver should not be built for IP/local hosts")
+
+    monkeypatch.setattr(network, "_build_detection_doh_resolver", _should_not_run)
+
+    assert network.detect_dns_interference("1.2.3.4") is None
+    assert network.detect_dns_interference("localhost") is None
+
+
+def test_note_possible_dns_interference_warns_once_and_sets_flag(monkeypatch):
+    import shelfmark.download.network as network
+
+    monkeypatch.setattr(network, "_dns_interference_warned", set())
+    monkeypatch.setattr(network, "_dns_interference_active", False)
+
+    calls: list[str] = []
+    monkeypatch.setattr(
+        network,
+        "detect_dns_interference",
+        lambda host: (
+            calls.append(host) or {"system_ips": ["198.51.100.1"], "doh_ips": ["203.0.113.7"]}
+        ),
+    )
+
+    assert network.note_possible_dns_interference("annas-archive.pk") is True
+    assert network.dns_interference_detected() is True
+    # A repeat check for the same host must not re-run the costly detection.
+    assert network.note_possible_dns_interference("annas-archive.pk") is True
+    assert calls == ["annas-archive.pk"]
+
+
+def test_note_possible_dns_interference_no_detection_keeps_flag_false(monkeypatch):
+    import shelfmark.download.network as network
+
+    monkeypatch.setattr(network, "_dns_interference_warned", set())
+    monkeypatch.setattr(network, "_dns_interference_active", False)
+    monkeypatch.setattr(network, "detect_dns_interference", lambda _host: None)
+
+    assert network.note_possible_dns_interference("annas-archive.pk") is False
+    assert network.dns_interference_detected() is False

tests/download/test_orchestrator_user_output_mode.py

@@ -205,7 +205,7 @@ def test_download_task_rejects_unavailable_source_before_handler(monkeypatch):
     orchestrator.get_handler.assert_not_called()
 
 
-def test_queue_release_persists_generic_retry_resolution_fields(monkeypatch):
+def test_queue_release_persists_prowlarr_retry_context_without_download_url(monkeypatch):
     import shelfmark.download.orchestrator as orchestrator
 
     captured: dict[str, object] = {}
@@ -227,6 +227,7 @@ def test_queue_release_persists_generic_retry_resolution_fields(monkeypatch):
             "protocol": "torrent",
             "indexer": "MyIndexer",
             "extra": {
+                "indexer_id": 12,
                 "configured_ratio_limit": 1.25,
                 "configured_seed_time_minutes": 90,
                 "info_hash": "ABC123",
@@ -239,14 +240,23 @@ def test_queue_release_persists_generic_retry_resolution_fields(monkeypatch):
     assert success is True
     assert error is None
     task = captured["task"]
-    assert task.retry_download_url == "magnet:?xt=urn:btih:abc123"
-    assert task.retry_download_protocol == "torrent"
+    assert task.retry_download_url is None
+    assert task.retry_download_protocol is None
+    assert task.retry_source_context == {
+        "source_id": "prowlarr-release-1",
+        "indexer": "MyIndexer",
+        "indexer_id": 12,
+    }
     assert task.retry_release_name == "Queued Prowlarr Release"
     assert task.retry_expected_hash == "ABC123"
     assert task.retry_ratio_limit == 1.25
     assert task.retry_seeding_time_limit_minutes == 90
     assert task.can_retry_without_staged_source is True
 
+    payload = orchestrator.serialize_task_for_retry(task)
+    assert payload["retry_download_url"] is None
+    assert payload["retry_source_context"] == task.retry_source_context
+
 
 def test_queue_release_prefers_configured_seed_time_minutes_for_retry(monkeypatch):
     import shelfmark.download.orchestrator as orchestrator
@@ -377,3 +387,58 @@ def test_queue_release_returns_error_for_operational_queue_failure(monkeypatch):
 
     assert success is False
     assert error == "Error queueing release: queue offline"
+
+
+def _queue_and_capture(monkeypatch, release_data):
+    import shelfmark.download.orchestrator as orchestrator
+
+    captured: dict[str, object] = {}
+
+    monkeypatch.setattr(orchestrator.config, "get", lambda key, default=None, user_id=None: default)
+    monkeypatch.setattr(
+        orchestrator.book_queue, "add", lambda task: captured.setdefault("task", task) or True
+    )
+    monkeypatch.setattr(orchestrator, "ws_manager", None)
+
+    success, error = orchestrator.queue_release(release_data, user_id=1, username="alice")
+
+    assert success is True, error
+    return captured["task"]
+
+
+def test_queue_release_carries_top_level_language(monkeypatch):
+    task = _queue_and_capture(
+        monkeypatch,
+        {
+            "source": "prowlarr",
+            "source_id": "release-sv",
+            "title": "Project Hail Mary",
+            "language": "sv",
+        },
+    )
+
+    assert task.language == "sv"
+
+
+def test_queue_release_falls_back_to_language_in_extra(monkeypatch):
+    # direct_download sets language inside extra as well as top level.
+    task = _queue_and_capture(
+        monkeypatch,
+        {
+            "source": "direct_download",
+            "source_id": "release-de",
+            "title": "Project Hail Mary",
+            "extra": {"language": "de"},
+        },
+    )
+
+    assert task.language == "de"
+
+
+def test_queue_release_without_language_leaves_it_unset(monkeypatch):
+    task = _queue_and_capture(
+        monkeypatch,
+        {"source": "prowlarr", "source_id": "release-none", "title": "Project Hail Mary"},
+    )
+
+    assert task.language is None

tests/download/test_webseed_torrent_generator.py

@@ -0,0 +1,87 @@
+"""Validate the e2e platform's webseed .torrent generator.
+
+The ``full`` e2e profile relies on a tracker-less webseed torrent so a real
+qBittorrent can complete a real download from the mock origin over HTTP. If the
+generator emits malformed bencode or mismatched piece hashes, qBittorrent would
+silently never complete — so we cross-check the generator against shelfmark's own
+``bencode_decode`` / ``extract_info_hash_from_torrent`` here, in normal CI.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+from shelfmark.download.clients.torrent_utils import (
+    bencode_decode,
+    extract_info_hash_from_torrent,
+)
+
+GEN_PATH = (
+    Path(__file__).resolve().parents[1] / "e2e" / "platform" / "mocks" / "make_webseed_torrent.py"
+)
+
+
+def _load_generator():
+    if not GEN_PATH.exists():
+        pytest.skip(f"generator not found at {GEN_PATH}")
+    spec = importlib.util.spec_from_file_location("make_webseed_torrent", GEN_PATH)
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+PAYLOAD = b"E2E webseed payload \x00\x01\x02 " * 2000  # ~50 KiB -> multiple pieces
+NAME = "sample-book.epub"
+WEBSEED = "http://mock-aa/payload/sample-book.epub"
+
+
+def test_generated_torrent_decodes_with_shelfmark_bencode() -> None:
+    gen = _load_generator()
+    raw = gen.build_webseed_torrent(NAME, PAYLOAD, WEBSEED, piece_length=16384)
+
+    decoded, _ = bencode_decode(raw)
+    assert isinstance(decoded, dict)
+    info = decoded[b"info"]
+    assert info[b"name"] == NAME.encode()
+    assert info[b"length"] == len(PAYLOAD)
+    # url-list (webseed) must point at the file the mock serves.
+    assert decoded[b"url-list"] == [WEBSEED.encode()]
+    # No tracker — the whole point is HTTP-only completion.
+    assert b"announce" not in decoded
+
+
+def test_piece_hashes_match_payload_bytes() -> None:
+    gen = _load_generator()
+    piece_len = 16384
+    raw = gen.build_webseed_torrent(NAME, PAYLOAD, WEBSEED, piece_length=piece_len)
+    decoded, _ = bencode_decode(raw)
+    pieces = decoded[b"info"][b"pieces"]
+
+    expected = b"".join(
+        hashlib.sha1(PAYLOAD[i : i + piece_len]).digest() for i in range(0, len(PAYLOAD), piece_len)
+    )
+    assert pieces == expected, "piece hashes do not match payload — qbit would never complete"
+    assert len(pieces) % 20 == 0
+
+
+def test_info_hash_matches_shelfmark_extractor() -> None:
+    """Our infohash helper must agree with shelfmark's torrent parser."""
+    gen = _load_generator()
+    raw = gen.build_webseed_torrent(NAME, PAYLOAD, WEBSEED)
+
+    ours = gen.info_hash(raw)
+    theirs = extract_info_hash_from_torrent(raw)
+    assert theirs is not None
+    assert ours.lower() == theirs.lower(), (ours, theirs)
+
+
+def test_generator_is_deterministic() -> None:
+    gen = _load_generator()
+    a = gen.build_webseed_torrent(NAME, PAYLOAD, WEBSEED)
+    b = gen.build_webseed_torrent(NAME, PAYLOAD, WEBSEED)
+    assert a == b, "torrent generation must be byte-deterministic for stable infohash"

tests/e2e/platform/.gitignore

@@ -0,0 +1,7 @@
+# Runtime state created by run-e2e.sh: per-profile shelfmark logs, the app's
+# /config (settings, users.db, secrets), downloaded books, and staging dirs.
+.state/
+
+# Python bytecode from the mock services + suite.
+__pycache__/
+*.pyc

tests/e2e/platform/README.md

@@ -0,0 +1,231 @@
+# Shelfmark E2E Docker Testing Platform
+
+A hermetic, container-based end-to-end platform that boots the real Shelfmark app
+against **controllable** dependencies — a fake Anna's Archive, a Cloudflare gate, a
+mock FlareSolverr bypasser, a mock Prowlarr + a real qBittorrent, custom DNS
+servers, HTTP/SOCKS5 proxies, and a Tor profile — and runs a cluster test suite
+under each **config profile**.
+
+It exists to make the recurring bug clusters from the issue/PR analysis impossible
+to reintroduce silently. The biggest one — Tor/Cloudflare/bypasser (37 issues /
+67 fix PRs) — had almost no automated coverage; this platform changes that.
+
+```
+  pytest suite (host :8084)
+        │
+        ▼
+  shelfmark (under test) ── egress depends on the active profile:
+        ├─ direct ──────────────► mock-aa (.10)                  fake Anna's Archive
+        ├─ Cloudflare gate ─────► mock-cf (.11) ─► mock-aa       [full: real Chrome solves it]
+        ├─ FlareSolverr ────────► mock-cf (.11) ─► mock-flaresolverr (.12)  [bypasser-external]
+        ├─ custom DNS ──────────► coredns (.20) / coredns-blocked (.22)     [dns-manual/blocked]
+        ├─ HTTP / SOCKS proxy ──► tinyproxy (.30) / microsocks (.31)        [proxy-http/socks]
+        ├─ Tor (transparent) ───► in-image tor.sh                           [tor]
+        └─ Prowlarr → client ───► mock-prowlarr (.40) ─► qBittorrent        [full: real download]
+
+  (all on one e2e docker network, 172.30.0.0/24, static IPs for DNS determinism)
+```
+
+## Quick start
+
+```bash
+# one profile
+make e2e-platform                       # baseline
+make e2e-platform-profile PROFILE=bypasser-external
+make e2e-platform-profile PROFILE=client-deluge
+make e2e-platform-full                  # heavy: real Chrome + DoH + real qBittorrent
+
+# the whole matrix
+make e2e-platform-matrix
+
+# build the heavy image once, then reuse it (matrix does this automatically)
+make e2e-platform-build
+E2E_NO_BUILD=1 tests/e2e/platform/run-e2e.sh env/dns-doh.env
+
+# debug: leave the stack up after the run
+KEEP_UP=1 tests/e2e/platform/run-e2e.sh env/dns-blocked.env
+```
+
+Requirements: Docker + Compose v2, and `uv` (for the pytest runner). The runner
+builds the Shelfmark image from the repo `Dockerfile`, boots the profile's stack,
+waits for `/api/health`, runs the suite, and tears down. `run-matrix.sh` builds the
+image **once** and reuses it across profiles (`E2E_NO_BUILD=1`) so the slow
+xvfb/chromium layer isn't rebuilt per profile.
+
+## How profiles work
+
+Each profile is an env file in `env/`. It sets:
+- `COMPOSE_PROFILES` — which optional services start (compose `profiles:`).
+- `SM_*` — the app's config, injected as container env. Shelfmark treats
+  deployment ENV as authoritative (`config.get`: "Deployment-level ENV values
+  always win"), so a profile fully determines the app's DNS/proxy/bypasser/source
+  configuration with no runtime mutation.
+- `E2E_PROFILE` — handed to pytest so the suite selects applicable tests.
+
+Tests declare applicability with `@pytest.mark.profiles(...)`. **A test with no
+marker is a profile-agnostic invariant and runs under every profile** — that is
+how one cluster test ("source must be reachable") becomes the config matrix.
+
+## The matrix (cluster × profile)
+
+Status column: ✅ = run live on Docker and passing. Every profile below was run
+end-to-end (`docker compose up` + suite + teardown) and passes.
+
+| Profile | Egress / what it proves | Clusters | Regression targets | Status |
+|---|---|---|---|---|
+| `baseline` | Direct to fake AA; search/parse + #1028 clean-failure | 2,3,4 | #198 #293 #214 #1040 #1028 | ✅ 9 passed |
+| `bypasser-external` | External bypasser wired; CF-gated search fails cleanly | 1 | #284 #202 #410 #369 | ✅ 5 passed |
+| `bypasser-disabled` | CF-gated AA + bypasser OFF → no results (control) | 1 | #202 #410 | ✅ 4 passed |
+| `dns-manual` | AA only resolvable via custom DNS (coredns) | config: DNS | #108 | ✅ 4 passed |
+| `dns-blocked` | System DNS NXDOMAINs AA; custom DNS resolves it | config: DNS | **#1028** | ✅ 4 passed |
+| `dns-doh` | System DNS blocks AA; **DoH over real HTTPS** resolves it | config: DoH | **#1028** #108 | ✅ 3 passed |
+| `proxy-http` | All egress via tinyproxy, **proven by proxy logs** | config: proxy | **#956** | ✅ 6 passed |
+| `proxy-socks` | All egress via SOCKS5 (microsocks), traversal-checked | config: proxy | #956 | ✅ 5 passed |
+| `tor` | `USING_TOR=true` boots clean (restarts=0) | 1/6 Tor boot | #1021 #940 #801 | ✅ 5 passed |
+| `client-transmission` | Prowlarr → **real Transmission** webseed download → /books | 5 clients | #1022 #634 | ✅ 4 passed |
+| `client-deluge` | Prowlarr → **real Deluge** webseed download → /books | 5 clients | #530 | ✅ 4 passed |
+| `full` | **real Chrome solves Cloudflare** + DoH + **real qBittorrent** download → /books (Moby-Dick) | 1,4,5 + DoH | **#284 #1030** #386 #1040 #214 | ✅ 6 passed |
+| *(every profile)* | boots healthy under PUID/PGID, no perm errors | 6 entrypoint | #171 #447 #801 | ✅ |
+
+> **The bypasser is download-time, not search-time.** Running the stack revealed
+> that shelfmark fetches AA search/detail with `allow_bypasser_fallback=False`, so a
+> search behind Cloudflare returns 503 **regardless** of the bypasser; the bypasser
+> (internal Chrome or external FlareSolverr) only runs during a file *download*
+> (`use_bypasser=True`). The bypasser profiles therefore assert a *clean*
+> CF-gated-search failure, while the **`full` profile exercises the real end-to-end
+> CF solve**: AA search/detail are reachable, but the AA slow-download link points
+> at the gate, so downloading Moby-Dick forces the in-image headless Chromium to
+> detect the challenge, solve it (`_bypass_method_cdp_solve`), and fetch the file —
+> verified live (`Challenge detected: cloudflare` → `Bypass successful` → Moby-Dick
+> in `/books`).
+>
+> **`bypasser-external` must set `SM_USING_EXTERNAL_BYPASSER=true`** — shelfmark does
+> **not** derive it from `EXT_BYPASSER_URL`; without it the app silently uses the
+> in-image Chrome bypasser instead of FlareSolverr.
+
+Coverage of the 7 clusters from the analysis:
+
+1. **Bypasser/Tor/Cloudflare** → `bypasser-external`, `bypasser-disabled`, `tor`.
+2. **Search/metadata** → `baseline` (`test_cluster_search_aa.py`, hermetic via the
+   `direct_download` source so no external metadata provider is needed).
+3. **AA parsing/mirrors** → `baseline` parse guards incl. the **layout-drift
+   fail-loud** test (#878/#879/#880).
+4. **Permissions/file-move** → `baseline` (`test_cluster_download_permissions.py`).
+5. **Torrent/usenet clients** → a mock Prowlarr + webseed torrent drives **three
+   real torrent clients** end to end (`full`=qBittorrent, `client-transmission`,
+   `client-deluge`) — completion detection + file move into `/books`. One
+   client-agnostic test (`test_cluster_clients.py`) covers all three.
+6. **Docker/entrypoint/PUID-PGID** → profile-agnostic health + boot-log checks,
+   run under every profile.
+7. **Audiobook/ABB** → parse-contract guards in
+   `tests/audiobookbay/test_scraper_contract.py` (info-hash normalization #386,
+   magnet fallback, layout drift). These run in **normal CI**, not the docker
+   matrix, because ABB hardcodes `https://` for its fetches (see Roadmap).
+
+### Proxy traversal (not just reachability)
+Because the app and the mock AA share the e2e network, a regression that ignores
+the proxy config would still reach AA directly. `test_egress_actually_traverses_proxy`
+drives a search and then inspects the proxy container's logs, so the proxy
+profiles prove the egress *went through* the proxy — a real guard for #956.
+
+### DoH — two layers
+- **Offline** (`tests/download/test_doh_resolver_mock.py`, normal CI): the real
+  `DoHResolver` is driven against the mock `doh` role over localhost HTTP, covering
+  JSON-answer parsing, NXDOMAIN → empty, and caching.
+- **In-stack** (`dns-doh` profile): the mock `doh` role serves the DNS JSON API over
+  **real HTTPS** (self-signed). The system resolver (coredns-blocked) NXDOMAINs
+  `aa.mock.test`, so the host can *only* be resolved via DoH; compose `extra_hosts`
+  redirects the `cloudflare-dns.com` provider to the in-stack mock and
+  `CERTIFICATE_VALIDATION=disabled` accepts the self-signed cert. The search reaching
+  AA proves the app's DoH path resolved the name end to end — **no app code change**.
+
+### The `full` profile — real Chrome + real client (`make e2e-platform-full`)
+The "everything real" heavy profile (test book: **Moby-Dick**), run nightly / on
+demand (excluded from the PR matrix). It spins up, with **no** mock bypasser, and
+**passes live** (6 passed):
+
+- **Real Chrome solves Cloudflare, end to end (VERIFIED).** AA search/detail are
+  reachable (`mock-aa`), but the AA *slow-download* link points at the Cloudflare
+  gate (`mock-cf`), whose challenge page runs JS that issues `cf_clearance` and
+  reloads. Downloading Moby-Dick forces the in-image headless Chromium (seleniumbase
+  CDP, in the `shelfmark` image via `xvfb`+`chromium`) to load the gate, detect the
+  challenge (`Challenge detected: cloudflare`), solve it (`_bypass_method_cdp_solve`),
+  and fetch the cleared "Download now" page → the file lands in `/books`. That
+  outcome is *only* reachable if Chrome solved the gate — the literal "spin a Chrome
+  browser" path and the strongest guard for the #1 cluster. Two subtleties this
+  surfaced, now handled by the mock: the cleared page must exceed the bypasser's
+  `_LOADING_BODY_LENGTH_MAX` (50 chars of innerText) or it loops as "still loading",
+  and the AA detail page must satisfy the brittle `original_nodes[-6]` parse (#880).
+- **DoH** on at boot.
+- **Real qBittorrent download.** A mock Prowlarr (`/api/v1/system/status`,
+  `/api/v1/indexer`, torznab search) returns one release whose `.torrent` is a
+  **tracker-less BEP-19 webseed** pointing at `mock-aa`'s HTTP payload. A real
+  qBittorrent completes the download over HTTP (no tracker/peer/seeder), and
+  shelfmark's completion detection + file move lands the book in `/books`. The
+  webseed torrent is generated by `mocks/make_webseed_torrent.py` (cross-checked
+  against shelfmark's own bencode/infohash parser in
+  `tests/download/test_webseed_torrent_generator.py`), and the whole
+  prowlarr→qBittorrent path is configured declaratively via env (`env/full.env`).
+
+## Components
+
+| Path | Purpose |
+|---|---|
+| `mocks/mock_services.py` | One Flask app, five roles (`origin-aa`, `cloudflare`, `flaresolverr`, `prowlarr`, `doh`) selected by `MOCK_ROLE`. `origin-aa` also serves the webseed payload + `.torrent`. |
+| `mocks/make_webseed_torrent.py` | Stdlib bencode + BEP-19 webseed `.torrent` generator for the `full` real-client download. |
+| `qbittorrent/qBittorrent.conf` | Real qBittorrent config (auth bypassed for the e2e subnet) for the `full` profile. |
+| `env/full.env` | The heavy `full` profile: real Chrome bypasser + DoH + real qBittorrent. |
+| `mocks/fixtures/*.html` | AA search/detail HTML in the **exact** shape the parser expects, plus drift/empty/no-files variants. |
+| `docker-compose.e2e.yml` | The stack; optional services gated by compose profiles, static IPs for DNS determinism. |
+| `dns/Corefile*`, `dns/mock.test.db` | coredns zones — working + ISP-block (NXDOMAIN). |
+| `env/*.env` | The config profiles (matrix rows). |
+| `suite/` | The pytest harness + cluster tests. |
+| `run-e2e.sh` / `run-matrix.sh` | Boot one profile / loop the matrix. |
+| `build-images.sh` | Build the heavy image once (`make e2e-platform-build`); reused via `E2E_NO_BUILD=1`. |
+
+### Fault injection
+The mock AA reproduces historical bugs deterministically. Injection rides inside
+the search query as `E2EINJECT:<name>` (the app builds the AA URL itself and only
+forwards the user query as `q=`). Names: `no_files`, `empty`, `layout_drift`,
+`500`. The harness embeds them via `PlatformClient.direct_search(..., inject=...)`.
+
+## Gating PRs (block merge on e2e failure)
+
+The `.github/workflows/e2e-platform.yml` workflow runs on every PR. On a PR that
+touches relevant code (`shelfmark/**`, `Dockerfile`, `entrypoint.sh`, `tor.sh`,
+`tests/e2e/platform/**`) it runs the fast PR subset **and** the heavy `full`
+profile (real Chrome solving Cloudflare + DoH + real qBittorrent), then a single
+**`e2e required`** job aggregates them: it fails if any e2e job failed, and passes
+(so it never hangs) when the e2e jobs are skipped on an unrelated PR.
+
+The workflow producing a failing check is **not enough on its own** — GitHub only
+*blocks merge* on checks listed in branch protection. A repo **admin** must, once:
+
+- **UI:** Settings → Branches → branch protection rule for `main` →
+  *Require status checks to pass before merging* → add **`e2e required`**.
+- **or `gh` (admin token):**
+  ```bash
+  gh api -X PUT repos/calibrain/shelfmark/branches/main/protection \
+    -H "Accept: application/vnd.github+json" --input - <<'JSON'
+  { "required_status_checks": { "strict": true, "contexts": ["e2e required"] },
+    "enforce_admins": true, "required_pull_request_reviews": null, "restrictions": null }
+  JSON
+  ```
+
+After that, any failure in the e2e platform tests (including the `full` profile)
+blocks the PR from merging. Requiring just the one `e2e required` context covers
+the whole dynamic matrix, so the list never needs updating as profiles change.
+
+## Known limitations / follow-ups
+
+- **rTorrent.** Not in the matrix: its rakshasa-libtorrent has **no GetRight/webseed
+  support**, so the hermetic webseed torrent (which qBittorrent/Transmission/Deluge
+  all complete) leaves rTorrent stuck at 0%. Supporting it needs a real tracker +
+  seeder (peer download) — a follow-up that the webseed design intentionally avoids.
+- **Usenet clients (SABnzbd/NZBGet).** Not yet covered — completing a usenet download
+  hermetically needs a mock NNTP server serving the yEnc-encoded payload plus an NZB,
+  which is a separate (larger) build than the torrent webseed path.
+- **Audiobook (cluster 7) in-stack.** ABB hardcodes `https://`, so it's covered
+  offline (`tests/audiobookbay/test_scraper_contract.py`); an in-stack
+  `audiobookbay` role needs the same self-signed-HTTPS plumbing the `dns-doh` profile
+  now uses for DoH.

tests/e2e/platform/build-images.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Build every buildable image in the e2e stack once (the heavy `shelfmark` image
+# plus the mock-* role images), so run-matrix.sh / run-e2e.sh with E2E_NO_BUILD=1
+# can reuse them instead of rebuilding the xvfb/chromium layer per profile.
+set -euo pipefail
+
+PLATFORM_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$PLATFORM_DIR"
+
+# Activate every profile that owns a buildable service so they all get built.
+# (Download clients, coredns, proxies are pre-built images — nothing to build.)
+export COMPOSE_PROFILES="bypasser-external,full,dns-doh"
+echo "==> building shelfmark + mock images (one cold build of the chromium layer)"
+docker compose -f docker-compose.e2e.yml build
+echo "==> done. Reuse with: E2E_NO_BUILD=1 ./run-e2e.sh env/<profile>.env"

tests/e2e/platform/dns/Corefile

@@ -0,0 +1,13 @@
+# coredns: authoritative for mock.test, forwards everything else.
+mock.test:53 {
+    file /zones/mock.test.db
+    log
+    errors
+}
+
+. :53 {
+    forward . 1.1.1.1 8.8.8.8
+    cache 30
+    log
+    errors
+}

tests/e2e/platform/dns/Corefile.blocked

@@ -0,0 +1,18 @@
+# coredns: ISP-DNS-block simulation. Resolves nothing under mock.test
+# (returns NXDOMAIN), so an app that relies on *system* DNS for book sources
+# fails — while an app that uses its own custom DNS resolver still works.
+# Regression harness for #1028 (internal bypasser used system DNS in subprocess).
+mock.test:53 {
+    template IN ANY mock.test {
+        rcode NXDOMAIN
+    }
+    log
+    errors
+}
+
+. :53 {
+    # Everything else still resolves, so only the book-source host is "blocked".
+    forward . 1.1.1.1 8.8.8.8
+    log
+    errors
+}

tests/e2e/platform/dns/mock.test.db

@@ -0,0 +1,13 @@
+$ORIGIN mock.test.
+$TTL 60
+@   IN  SOA ns.mock.test. admin.mock.test. (
+        1          ; serial
+        7200       ; refresh
+        3600       ; retry
+        1209600    ; expire
+        3600 )     ; minimum
+@   IN  NS  ns.mock.test.
+ns  IN  A   172.30.0.20
+aa  IN  A   172.30.0.10
+cf  IN  A   172.30.0.11
+doh IN  A   172.30.0.21

tests/e2e/platform/docker-compose.e2e.yml

@@ -0,0 +1,332 @@
+# Shelfmark e2e Docker testing platform
+# ---------------------------------------------------------------------------
+# A hermetic stack: the app under test plus *controllable* dependencies
+# (fake Anna's Archive, a Cloudflare gate, a mock FlareSolverr bypasser, a DoH
+# responder, a DNS server, HTTP + SOCKS5 proxies, and a Tor profile).
+#
+# Config profiles are env-driven: pick a profile with an env file under env/
+# (it sets COMPOSE_PROFILES + the SM_* config the app boots with). The runner
+# brings the stack up per profile, runs the matching cluster tests, tears down.
+#
+#   ./run-e2e.sh env/baseline.env
+#   ./run-e2e.sh env/bypasser-external.env
+#   ./run-e2e.sh env/dns-blocked.env
+#
+# See README.md for the full cluster x profile matrix.
+
+x-mock-build: &mock-build
+  build:
+    context: ./mocks
+    dockerfile: Dockerfile
+
+networks:
+  e2e:
+    driver: bridge
+    ipam:
+      config:
+        - subnet: 172.30.0.0/24
+
+services:
+  # ----- App under test --------------------------------------------------- #
+  shelfmark:
+    build:
+      context: ../../..
+      dockerfile: Dockerfile
+      target: ${SM_BUILD_TARGET:-shelfmark}
+    container_name: e2e-shelfmark
+    cap_add:
+      - NET_ADMIN   # required by tor.sh iptables when USING_TOR=true
+      - NET_RAW
+    environment:
+      TZ: UTC
+      DEBUG: "true"
+      ONBOARDING: "false"          # skip wizard; ephemeral storage
+      DISABLE_LOCAL_AUTH: "${SM_DISABLE_LOCAL_AUTH:-true}"
+      PUID: "${SM_PUID:-1000}"
+      PGID: "${SM_PGID:-1000}"
+      # --- source / mirror config (cluster 2/3) ---
+      DIRECT_DOWNLOAD_ENABLED: "${SM_DIRECT_DOWNLOAD_ENABLED:-true}"
+      AA_ADDITIONAL_URLS: "${SM_AA_URL:-http://mock-aa}"
+      # --- bypasser config (cluster 1) ---
+      USE_CF_BYPASS: "${SM_USE_CF_BYPASS:-false}"
+      # Selects the external (FlareSolverr) bypasser; when false the in-image
+      # Chrome (internal) bypasser is used. NOT derived from EXT_BYPASSER_URL.
+      USING_EXTERNAL_BYPASSER: "${SM_USING_EXTERNAL_BYPASSER:-false}"
+      EXT_BYPASSER_URL: "${SM_EXT_BYPASSER_URL:-}"
+      # --- prowlarr indexer + torrent client (cluster 5, `full` profile) ---
+      PROWLARR_ENABLED: "${SM_PROWLARR_ENABLED:-false}"
+      PROWLARR_URL: "${SM_PROWLARR_URL:-}"
+      PROWLARR_API_KEY: "${SM_PROWLARR_API_KEY:-}"
+      PROWLARR_TORRENT_CLIENT: "${SM_PROWLARR_TORRENT_CLIENT:-}"
+      QBITTORRENT_URL: "${SM_QBITTORRENT_URL:-}"
+      QBITTORRENT_USERNAME: "${SM_QBITTORRENT_USERNAME:-}"
+      QBITTORRENT_PASSWORD: "${SM_QBITTORRENT_PASSWORD:-}"
+      QBITTORRENT_CATEGORY: "${SM_QBITTORRENT_CATEGORY:-}"
+      DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT: "${SM_DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT:-60}"
+      # transmission / deluge / rtorrent (client-* profiles)
+      TRANSMISSION_URL: "${SM_TRANSMISSION_URL:-}"
+      TRANSMISSION_USERNAME: "${SM_TRANSMISSION_USERNAME:-}"
+      TRANSMISSION_PASSWORD: "${SM_TRANSMISSION_PASSWORD:-}"
+      DELUGE_HOST: "${SM_DELUGE_HOST:-}"
+      DELUGE_PORT: "${SM_DELUGE_PORT:-}"
+      DELUGE_PASSWORD: "${SM_DELUGE_PASSWORD:-}"
+      RTORRENT_URL: "${SM_RTORRENT_URL:-}"
+      # --- DNS / DoH (config cluster) ---
+      CUSTOM_DNS: "${SM_CUSTOM_DNS:-}"
+      CUSTOM_DNS_MANUAL: "${SM_CUSTOM_DNS_MANUAL:-}"
+      USE_DOH: "${SM_USE_DOH:-false}"
+      # Disable TLS verification so the in-stack DoH-over-HTTPS mock (self-signed)
+      # is accepted in the dns-doh profile. Default keeps verification ON.
+      CERTIFICATE_VALIDATION: "${SM_CERTIFICATE_VALIDATION:-enabled}"
+      # --- proxy (config cluster) ---
+      PROXY_MODE: "${SM_PROXY_MODE:-none}"
+      HTTP_PROXY_URL: "${SM_HTTP_PROXY:-}"
+      HTTP_PROXY: "${SM_HTTP_PROXY:-}"
+      SOCKS5_PROXY: "${SM_SOCKS5_PROXY:-}"
+      NO_PROXY: "${SM_NO_PROXY:-}"
+      # --- tor (cluster 1/6) ---
+      USING_TOR: "${SM_USING_TOR:-false}"
+    ports:
+      - "8084:8084"
+    volumes:
+      - ./.state/config:/config
+      - ./.state/books:/books
+      - ${SM_DOWNLOADS_HOST_DIR:-./.state/downloads}:/downloads
+      - ./.state/tmp:/tmp/shelfmark
+    networks:
+      - e2e
+    dns:
+      # When a DNS profile is active, point the container's system resolver at
+      # our controllable server; otherwise Docker's embedded DNS (127.0.0.11).
+      - ${SM_SYSTEM_DNS:-127.0.0.11}
+    extra_hosts:
+      # Redirect the DoH provider hostname to the in-stack mock-doh (dns-doh
+      # profile). Harmless elsewhere — only the dns-doh profile enables DoH against
+      # the cloudflare provider, and /etc/hosts is consulted before the resolver.
+      - "cloudflare-dns.com:172.30.0.21"
+    restart: "no"
+
+  # ----- Fake Anna's Archive origin (always on) --------------------------- #
+  mock-aa:
+    <<: *mock-build
+    container_name: e2e-mock-aa
+    environment:
+      MOCK_ROLE: origin-aa
+      # When set (the `full` profile sets it to the CF gate), AA slow-download
+      # links point through Cloudflare so a real download forces the internal
+      # Chrome bypasser to solve the challenge. Empty -> same-origin (no CF).
+      SLOW_DOWNLOAD_BASE: "${SM_SLOW_DOWNLOAD_BASE:-}"
+      AA_FILE_BASE: "http://mock-aa"
+    networks:
+      e2e:
+        ipv4_address: 172.30.0.10
+        aliases:
+          - aa.mock.test
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request;urllib.request.urlopen('http://localhost/healthz')"]
+      interval: 3s
+      timeout: 3s
+      retries: 10
+
+  # ----- Cloudflare gate (profiles: bypasser-external, full) -------------- #
+  # `full` puts AA's slow-download behind this gate so the real Chrome bypasser
+  # must solve it; `bypasser-external` puts AA search behind it for the
+  # FlareSolverr negative/positive controls.
+  mock-cf:
+    <<: *mock-build
+    container_name: e2e-mock-cf
+    profiles: ["bypasser-external", "full"]
+    environment:
+      MOCK_ROLE: cloudflare
+      ORIGIN_INTERNAL_URL: http://mock-aa
+    networks:
+      e2e:
+        ipv4_address: 172.30.0.11
+        aliases:
+          - cf.mock.test
+
+  # ----- Mock FlareSolverr external bypasser (profile: bypasser-external) -- #
+  mock-flaresolverr:
+    <<: *mock-build
+    container_name: e2e-mock-flaresolverr
+    profiles: ["bypasser-external"]
+    environment:
+      MOCK_ROLE: flaresolverr
+    networks:
+      e2e:
+        ipv4_address: 172.30.0.12
+
+  # NOTE: the mock `doh` role lives in mock_services.py and is exercised by
+  # tests/download/test_doh_resolver_mock.py (real DoHResolver over localhost HTTP).
+  # An in-stack DoH service is intentionally absent — see README "Known limitations".
+
+  # ----- DNS server (profile: dns-manual) --------------------------------- #
+  coredns:
+    image: coredns/coredns:1.11.1
+    container_name: e2e-coredns
+    profiles: ["dns-manual"]
+    command: ["-conf", "/Corefile"]
+    volumes:
+      - ./dns/Corefile:/Corefile:ro
+      - ./dns/mock.test.db:/zones/mock.test.db:ro
+    networks:
+      e2e:
+        ipv4_address: 172.30.0.20
+
+  # ----- DNS server that NXDOMAINs the AA host (profile: dns-blocked) ------ #
+  # Simulates ISP DNS blocking (#1028); the app must fall back (DoH / direct).
+  coredns-blocked:
+    image: coredns/coredns:1.11.1
+    container_name: e2e-coredns-blocked
+    profiles: ["dns-blocked"]
+    command: ["-conf", "/Corefile"]
+    volumes:
+      - ./dns/Corefile.blocked:/Corefile:ro
+    networks:
+      e2e:
+        ipv4_address: 172.30.0.22
+
+  # ----- HTTP proxy (profile: proxy-http) --------------------------------- #
+  tinyproxy:
+    image: monokal/tinyproxy:latest
+    container_name: e2e-tinyproxy
+    profiles: ["proxy-http"]
+    command: ANY
+    networks:
+      e2e:
+        ipv4_address: 172.30.0.30
+
+  # ----- SOCKS5 proxy (profile: proxy-socks) ------------------------------ #
+  microsocks:
+    image: vimagick/microsocks:latest
+    container_name: e2e-microsocks
+    profiles: ["proxy-socks"]
+    networks:
+      e2e:
+        ipv4_address: 172.30.0.31
+
+  # ----- Mock Prowlarr indexer (full + client-* profiles) ----------------- #
+  # Minimal Prowlarr API returning one torrent release whose .torrent is a
+  # webseed pointing at mock-aa. Drives the real torrent-client download in the
+  # `full` (qBittorrent) and `client-*` (transmission/deluge/rtorrent) profiles.
+  mock-prowlarr:
+    <<: *mock-build
+    container_name: e2e-mock-prowlarr
+    profiles: ["full", "client-transmission", "client-deluge", "client-qbittorrent-delayed"]
+    environment:
+      MOCK_ROLE: prowlarr
+      AA_INTERNAL_URL: http://mock-aa
+    networks:
+      e2e:
+        ipv4_address: 172.30.0.40
+        aliases:
+          - prowlarr.mock.test
+
+  # ----- Real qBittorrent download client (profiles: full, delayed path) --- #
+  # Auth is bypassed for the e2e subnet (qBittorrent.conf) so shelfmark connects
+  # without juggling the image's random temp password.
+  qbittorrent:
+    image: lscr.io/linuxserver/qbittorrent:latest
+    container_name: e2e-qbittorrent
+    profiles: ["full", "client-qbittorrent-delayed"]
+    environment:
+      PUID: "1000"
+      PGID: "1000"
+      TZ: UTC
+      WEBUI_PORT: "8080"
+    volumes:
+      - ./qbittorrent/qBittorrent.conf:/config/qBittorrent/qBittorrent.conf
+      # Normally shared with Shelfmark. In the delayed profile this points at a
+      # client-only directory and the sync sidecar makes it visible later.
+      - ${SM_QBITTORRENT_DOWNLOADS_HOST_DIR:-./.state/downloads}:/downloads
+    networks:
+      - e2e
+
+  # ----- Delayed file visibility sidecar (profile: client-qbittorrent-delayed) #
+  # Simulates a seedbox/remote-sync workflow: qBittorrent writes into one host
+  # directory while Shelfmark sees a separate /downloads directory that is synced
+  # only after a delay. This exercises DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT.
+  delayed-download-sync:
+    image: alpine:3.20
+    container_name: e2e-delayed-download-sync
+    profiles: ["client-qbittorrent-delayed"]
+    environment:
+      SYNC_DELAY_SECONDS: "${SM_DELAYED_DOWNLOAD_SYNC_SECONDS:-20}"
+    command:
+      - /bin/sh
+      - -c
+      - |
+        mkdir -p /synced
+        while true; do
+          found=0
+          for path in /remote/*; do
+            [ -e "$${path}" ] || continue
+            found=1
+            before="$$(du -sk /remote 2>/dev/null | awk '{print $$1}')"
+            sleep "$${SYNC_DELAY_SECONDS}"
+            after="$$(du -sk /remote 2>/dev/null | awk '{print $$1}')"
+            if [ -n "$${before}" ] && [ "$${before}" = "$${after}" ]; then
+              cp -a /remote/. /synced/ 2>/dev/null || true
+            fi
+            break
+          done
+          [ "$${found}" = "1" ] || sleep 1
+        done
+    volumes:
+      - ${SM_QBITTORRENT_DOWNLOADS_HOST_DIR:-./.state/downloads}:/remote:ro
+      - ${SM_DOWNLOADS_HOST_DIR:-./.state/downloads}:/synced
+    networks:
+      - e2e
+
+  # ----- Real Transmission client (profile: client-transmission) ---------- #
+  # Same webseed torrent + mock Prowlarr as `full`, different real client.
+  transmission:
+    image: lscr.io/linuxserver/transmission:latest
+    container_name: e2e-transmission
+    profiles: ["client-transmission"]
+    environment:
+      PUID: "1000"
+      PGID: "1000"
+      TZ: UTC
+      USER: admin
+      PASS: admin
+    volumes:
+      - ./.state/downloads:/downloads
+    networks:
+      - e2e
+
+  # ----- Real Deluge client (profile: client-deluge) ---------------------- #
+  # shelfmark talks to deluge-web (default WebUI password "deluge"), which
+  # connects to the bundled daemon — no daemon auth-file juggling.
+  deluge:
+    image: lscr.io/linuxserver/deluge:latest
+    container_name: e2e-deluge
+    profiles: ["client-deluge"]
+    environment:
+      PUID: "1000"
+      PGID: "1000"
+      TZ: UTC
+    volumes:
+      - ./.state/downloads:/downloads
+    networks:
+      - e2e
+
+  # NOTE: rTorrent is intentionally absent — its rakshasa-libtorrent has no
+  # GetRight/webseed support, so the hermetic webseed torrent can't drive it.
+  # Supporting it would need a real tracker + seeder (see README limitations).
+
+  # ----- DoH-over-HTTPS responder (profile: dns-doh) ---------------------- #
+  # In-stack DoH: serves the DNS JSON API over HTTPS with a self-signed cert.
+  # shelfmark reaches it because the profile (a) maps the DoH provider hostname
+  # to this container via extra_hosts and (b) sets CERTIFICATE_VALIDATION=disabled.
+  mock-doh:
+    <<: *mock-build
+    container_name: e2e-mock-doh
+    profiles: ["dns-doh"]
+    environment:
+      MOCK_ROLE: doh
+      DOH_TLS: "1"
+      DOH_MAP: "aa.mock.test=172.30.0.10,cf.mock.test=172.30.0.11"
+    networks:
+      e2e:
+        ipv4_address: 172.30.0.21

tests/e2e/platform/env/baseline.env

@@ -0,0 +1,8 @@
+# Profile: baseline
+# Direct connection to the fake Anna's Archive, no bypasser, no proxy, system DNS.
+# Exercises clusters 2/3 (search + AA parsing) and the download happy path.
+COMPOSE_PROFILES=
+SM_AA_URL=http://mock-aa
+SM_USE_CF_BYPASS=false
+SM_PROXY_MODE=none
+E2E_PROFILE=baseline

tests/e2e/platform/env/bypasser-disabled.env

@@ -0,0 +1,9 @@
+# Profile: bypasser-disabled  (cluster 1 negative control)
+# AA behind the Cloudflare gate but the bypasser is OFF. Proves the gate really
+# challenges: search must FAIL clearly here, which is what makes the
+# bypasser-external success meaningful (and guards #202/#410 "uses AA when CF
+# bypass disabled" / "config not adhered").
+COMPOSE_PROFILES=bypasser-external
+SM_AA_URL=http://cf.mock.test
+SM_USE_CF_BYPASS=false
+E2E_PROFILE=bypasser-disabled

tests/e2e/platform/env/bypasser-external.env

@@ -0,0 +1,13 @@
+# Profile: bypasser-external  (cluster 1)
+# AA is served behind a Cloudflare gate. The app must detect the challenge and
+# route through the external bypasser (mock FlareSolverr), which returns solved
+# HTML + cf_clearance. Regression surface: #284 #226 #202 #1030 #410 #369 #267.
+COMPOSE_PROFILES=bypasser-external
+SM_AA_URL=http://cf.mock.test
+SM_USE_CF_BYPASS=true
+# Must be set explicitly — shelfmark does NOT derive it from EXT_BYPASSER_URL.
+# Without it the app falls back to the in-image Chrome bypasser and never calls
+# FlareSolverr, so this profile would silently exercise the wrong path.
+SM_USING_EXTERNAL_BYPASSER=true
+SM_EXT_BYPASSER_URL=http://mock-flaresolverr
+E2E_PROFILE=bypasser-external

tests/e2e/platform/env/client-deluge.env

@@ -0,0 +1,13 @@
+# Profile: client-deluge  (cluster 5 — real Deluge client)
+# shelfmark talks to deluge-web (default WebUI password "deluge"), which connects
+# to the bundled daemon — no daemon auth-file juggling.
+COMPOSE_PROFILES=client-deluge
+SM_PROWLARR_ENABLED=true
+SM_PROWLARR_URL=http://mock-prowlarr
+SM_PROWLARR_API_KEY=e2e-test-key
+SM_PROWLARR_TORRENT_CLIENT=deluge
+SM_DELUGE_HOST=deluge
+SM_DELUGE_PORT=8112
+SM_DELUGE_PASSWORD=deluge
+E2E_DOWNLOAD_TIMEOUT=180
+E2E_PROFILE=client-deluge

tests/e2e/platform/env/client-qbittorrent-delayed.env

@@ -0,0 +1,21 @@
+# Profile: client-qbittorrent-delayed  (cluster 5 — delayed completed-path visibility)
+# Same mock Prowlarr + webseed torrent as `full`, but qBittorrent writes to a
+# directory Shelfmark cannot see until the delayed sync sidecar copies it over.
+# This models seedbox / remote-sync setups where the client reports completion
+# before the completed path exists inside Shelfmark.
+COMPOSE_PROFILES=client-qbittorrent-delayed
+SM_PROWLARR_ENABLED=true
+SM_PROWLARR_URL=http://mock-prowlarr
+SM_PROWLARR_API_KEY=e2e-test-key
+SM_PROWLARR_TORRENT_CLIENT=qbittorrent
+SM_QBITTORRENT_URL=http://qbittorrent:8080
+SM_QBITTORRENT_USERNAME=admin
+SM_QBITTORRENT_PASSWORD=adminadmin
+SM_QBITTORRENT_CATEGORY=books
+
+# The sync delay must be longer than the default client path polling interval
+# so Shelfmark actually enters the completed-path wait loop.
+SM_DELAYED_DOWNLOAD_SYNC_SECONDS=20
+SM_DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT=90
+E2E_DOWNLOAD_TIMEOUT=180
+E2E_PROFILE=client-qbittorrent-delayed

tests/e2e/platform/env/client-transmission.env

@@ -0,0 +1,13 @@
+# Profile: client-transmission  (cluster 5 — real Transmission client)
+# Same mock Prowlarr + webseed torrent as `full`, but the torrent goes to a real
+# Transmission. Lean (no Chrome/CF/DoH), so it boots fast.
+COMPOSE_PROFILES=client-transmission
+SM_PROWLARR_ENABLED=true
+SM_PROWLARR_URL=http://mock-prowlarr
+SM_PROWLARR_API_KEY=e2e-test-key
+SM_PROWLARR_TORRENT_CLIENT=transmission
+SM_TRANSMISSION_URL=http://transmission:9091
+SM_TRANSMISSION_USERNAME=admin
+SM_TRANSMISSION_PASSWORD=admin
+E2E_DOWNLOAD_TIMEOUT=180
+E2E_PROFILE=client-transmission