Merge #1865: refactor(primitives): move TrackerPolicy, TORRENT_PEERS_LIMIT, and PrivateMode from configuration to primitives

736a535 fix: update stale docs and EPIC follow-up notes after #1859 (Jose Celano)
0e9d18b docs(primitives): add follow-up issue spec #1864 for TORRENT_PEERS_LIMIT review (Jose Celano)
d33c695 refactor(primitives): move TrackerPolicy, TORRENT_PEERS_LIMIT, and PrivateMode from configuration to primitives (Jose Celano)

Pull request description:

  ## Summary

  Closes #1859. Sub-task of #1669.

  Moves three types out of `torrust-tracker-configuration` and into `torrust-tracker-primitives`:

  - `TrackerPolicy` struct
  - `TORRENT_PEERS_LIMIT` constant
  - `PrivateMode` struct

  This breaks the dependency that `swarm-coordination-registry` and `torrent-repository-benchmarking` had on the configuration crate purely for these domain types.

  ## Changes

  ### New files
  - `packages/primitives/src/policy.rs` — defines `TrackerPolicy` and `TORRENT_PEERS_LIMIT`
  - `packages/primitives/src/mode.rs` — defines `PrivateMode`

  ### Modified files
  - `packages/primitives/src/lib.rs` — exports new modules
  - `packages/configuration/src/lib.rs` — removes `TrackerPolicy` and `TORRENT_PEERS_LIMIT`
  - `packages/configuration/src/v2_0_0/core.rs` — removes `PrivateMode`, updates imports
  - `packages/tracker-core/src/announce_handler.rs` — updates imports
  - `packages/tracker-core/src/torrent/repository/in_memory.rs` — updates imports
  - `packages/tracker-core/src/authentication/mod.rs` — updates imports
  - `packages/tracker-core/src/authentication/service.rs` — updates imports
  - `packages/swarm-coordination-registry/src/swarm/coordinator.rs` — updates imports
  - `packages/swarm-coordination-registry/src/swarm/registry.rs` — updates imports
  - `packages/swarm-coordination-registry/Cargo.toml` — removes `torrust-tracker-configuration` dependency
  - `packages/torrent-repository-benchmarking/Cargo.toml` — removes `torrust-tracker-configuration` dependency
  - All `torrent-repository-benchmarking/src/` and `tests/` files — updates imports

  ### Follow-up
  Issue #1864 tracks a follow-up decision on whether `TORRENT_PEERS_LIMIT` should become a runtime config option rather than a compile-time constant.

  ## Testing

  - `cargo test --workspace` ✅ all pass
  - `cargo clippy --workspace -- -D warnings` ✅ no warnings
  - `linter all` ✅ pass
  - `cargo machete` ✅ pass

ACKs for top commit:
  josecelano:
    ACK 736a535

Tree-SHA512: 855bbbd060e198276ecb6504dcbce160cb889bdfbf02bcbb0257756d26ec09e18195fa78428371c2b5b3b7221370b4e8a3396df4d9141dc4b168870d9f8b1e20

Author: josecelano

Cargo.lock

@@ -1,10 +1,10 @@
 ---
 doc-type: issue
 issue-type: task
-status: open
+status: closed
 priority: p2
 github-issue: 1859
-spec-path: docs/issues/open/1859-1669-move-tracker-policy-and-private-mode-to-primitives/ISSUE.md
+spec-path: docs/issues/closed/1859-1669-move-tracker-policy-and-private-mode-to-primitives/ISSUE.md
 branch: null
 related-pr: null
 last-updated-utc: 2026-06-01 00:00
@@ -118,16 +118,16 @@ list `torrust-tracker-configuration` in their `[dependencies]`.
 
 ## Acceptance Criteria
 
-- [ ] `TrackerPolicy` is defined in `torrust-tracker-primitives`
-- [ ] `TORRENT_PEERS_LIMIT` is defined in `torrust-tracker-primitives`
-- [ ] `PrivateMode` is defined in `torrust-tracker-primitives`
-- [ ] All import sites across the workspace import from `torrust-tracker-primitives`
-- [ ] `swarm-coordination-registry` no longer lists `torrust-tracker-configuration` as a
+- [x] `TrackerPolicy` is defined in `torrust-tracker-primitives`
+- [x] `TORRENT_PEERS_LIMIT` is defined in `torrust-tracker-primitives`
+- [x] `PrivateMode` is defined in `torrust-tracker-primitives`
+- [x] All import sites across the workspace import from `torrust-tracker-primitives`
+- [x] `swarm-coordination-registry` no longer lists `torrust-tracker-configuration` as a
       direct (non-dev) dependency
-- [ ] `torrent-repository-benchmarking` no longer lists `torrust-tracker-configuration`
+- [x] `torrent-repository-benchmarking` no longer lists `torrust-tracker-configuration`
       as a direct (non-dev) dependency
-- [ ] All tests pass (`cargo test --workspace --all-features`)
-- [ ] No new clippy warnings
+- [x] All tests pass (`cargo test --workspace --all-features`)
+- [x] No new clippy warnings
 
 ## Out of Scope
 

…-and-private-mode-to-primitives/ISSUE.md …-and-private-mode-to-primitives/ISSUE.mddocs/issues/open/1859-1669-move-tracker-policy-and-private-mode-to-primitives/ISSUE.md renamed to docs/issues/closed/1859-1669-move-tracker-policy-and-private-mode-to-primitives/ISSUE.md docs/issues/open/1859-1669-move-tracker-policy-and-private-mode-to-primitives/ISSUE.md renamed to docs/issues/closed/1859-1669-move-tracker-policy-and-private-mode-to-primitives/ISSUE.md

@@ -77,9 +77,9 @@ and separately move the three domain primitives that are misplaced in it to
 
 ### Trade-offs acknowledged
 
-- `swarm-coordination-registry` and `torrent-repository-benchmarking` continue to
-  depend on `torrust-tracker-configuration` until the domain primitive move is done
-  in a follow-up task.
+- `swarm-coordination-registry` and `torrent-repository-benchmarking` no longer
+  depend on `torrust-tracker-configuration` after FU-1 (#1859, PR #1865) moved the
+  domain primitives to `torrust-tracker-primitives`.
 - The "build-your-own tracker" use case remains blocked not by the config package
   boundary but by the structural design of `tracker-core` (always needing `Core` config)
   and the cross-layer coupling in `rest-api-core`. Enabling true service-level
@@ -88,9 +88,12 @@ and separately move the three domain primitives that are misplaced in it to
 
 ### Follow-up tasks
 
-- **FU-1**: Move `TrackerPolicy`, `TORRENT_PEERS_LIMIT`, and `PrivateMode` from
-  `torrust-tracker-configuration` to `torrust-tracker-primitives`. Update all import
-  sites. Track as a new subissue of EPIC #1669.
+- **FU-1** ✅ (#1859, PR #1865): Moved `TrackerPolicy`, `TORRENT_PEERS_LIMIT`, and
+  `PrivateMode` from `torrust-tracker-configuration` to `torrust-tracker-primitives`.
+  All import sites updated; `swarm-coordination-registry` and
+  `torrent-repository-benchmarking` no longer depend on the configuration crate.
+  Follow-up issue #1864 tracks whether `TORRENT_PEERS_LIMIT` should become a
+  runtime config option.
 - **FU-2**: Evaluate moving `TslConfig` into `axum-server` (already flagged in EPIC.md
   as a temporary coupling).
 - **FU-3**: Evaluate whether `EnvContainer::initialize` should accept narrower config

docs/issues/open/1669-overhaul-packages/DECISIONS.md

@@ -207,7 +207,7 @@ These packages will remain in the `torrust-tracker` workspace long-term.
 
 > **Note on `torrust-tracker-axum-server`**: This package is classified as `torrust-tracker-` because `tsl.rs` imports `TslConfig` from `torrust-tracker-configuration` and `LocatedError`/`DynError` from `torrust-located-error` (renamed in SI-10, #1823). `TslConfig` remains the temporary tracker-specific dependency: it is a small two-field struct with no tracker-specific logic and could be moved to a generic package. Once that change lands, the package could move to the `torrust-` group as a generic `torrust-axum-server` reusable across the Torrust organisation. A near-identical module already exists in [torrust-index](https://github.com/torrust/torrust-index/blob/develop/src/web/api/server/custom_axum.rs).
 
-[^fu1]: FU-1 (#1859): `TrackerPolicy`, `TORRENT_PEERS_LIMIT`, and `PrivateMode` will be moved here from `torrust-tracker-configuration`. See [DECISIONS.md](./DECISIONS.md) DEC-07.
+[^fu1]: FU-1 (#1859): `TrackerPolicy`, `TORRENT_PEERS_LIMIT`, and `PrivateMode` were moved here from `torrust-tracker-configuration` (completed in #1859, PR #1865). See [DECISIONS.md](./DECISIONS.md) DEC-07.
 
 ### `torrust/torrust-bittorrent` workspace
 

docs/issues/open/1669-overhaul-packages/EPIC.md

@@ -0,0 +1,98 @@
+---
+doc-type: issue
+issue-type: task
+status: open
+priority: p3
+github-issue: 1864
+spec-path: docs/issues/open/1864-1669-review-torrent-peers-limit/ISSUE.md
+branch: null
+related-pr: null
+last-updated-utc: 2026-06-01 00:00
+semantic-links:
+  skill-links:
+    - create-issue
+  related-artifacts:
+    - packages/primitives/src/policy.rs
+    - packages/tracker-core/src/announce_handler.rs
+    - packages/tracker-core/src/torrent/repository/in_memory.rs
+    - packages/swarm-coordination-registry/src/swarm/registry.rs
+    - packages/axum-http-server/src/lib.rs
+    - docs/issues/open/1669-overhaul-packages/EPIC.md
+    - docs/issues/open/1669-overhaul-packages/DECISIONS.md
+---
+
+<!-- skill-link: create-issue -->
+
+# Issue #1864 — Review and refactor `TORRENT_PEERS_LIMIT`: hardcoded constant vs. config option
+
+## Goal
+
+Decide whether `TORRENT_PEERS_LIMIT` should remain a global compile-time constant,
+be localized to each consuming package, or become a runtime configuration field.
+Record the decision and implement it.
+
+This is a follow-up to issue [#1859](../closed/1859-1669-move-tracker-policy-and-private-mode-to-primitives/ISSUE.md)
+and a sub-task of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md).
+
+## Background
+
+Issue #1859 moved `TORRENT_PEERS_LIMIT` (`74`) and `TrackerPolicy` from
+`torrust-tracker-configuration` into `torrust-tracker-primitives`. That was the
+right first step to break the configuration coupling, but the constant is still a
+global value shared across multiple packages.
+
+### Current usages
+
+`TORRENT_PEERS_LIMIT` is used in three distinct roles:
+
+1. **Parse-time cap in `From<i32/u32> for PeersWanted`** (announce handler):
+
+   ```rust
+   // packages/tracker-core/src/announce_handler.rs
+   impl From<i32> for PeersWanted {
+       fn from(value: i32) -> Self {
+           ...
+           PeersWanted::Only { amount: amount.min(TORRENT_PEERS_LIMIT) }
+       }
+   }
+   ```
+
+   Because this is a `From` impl, runtime injection is not possible — the limit is
+   baked in at the trait boundary.
+
+2. **Default return count in `PeersWanted::limit()`** — returned when the client
+   requested `AsManyAsPossible`.
+
+3. **Query cap in repository methods** — `in_memory.rs` and `swarm/registry.rs`
+   call `get_peers` / `get_swarm_peers` with `TORRENT_PEERS_LIMIT` as the hard
+   ceiling.
+
+## Questions to Resolve
+
+- Should `TORRENT_PEERS_LIMIT` remain a single global constant, or should each
+  package define its own local default?
+- Should the cap become a runtime configuration option (e.g., a field on
+  `TrackerPolicy`) so it can be tuned per deployment without recompilation?
+- For the `From<i32/u32> for PeersWanted` trait impls, which cannot accept injected
+  state, is a package-local constant the right answer, or should the impls be
+  replaced by explicit constructors / free functions that accept the limit?
+- If it becomes a config option, where does it sit in the configuration hierarchy
+  and how is it threaded through to the repository query methods?
+
+## Possible Approaches
+
+| Approach                                              | Pros                               | Cons                                                        |
+| ----------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------- |
+| Keep global constant in `primitives` (current state)  | Simple, no API churn               | Magic number, not tunable, couples packages                 |
+| Move constant into each consuming package             | Removes cross-package coupling     | Duplication, values can drift                               |
+| Add `max_peers_per_announce` field to `TrackerPolicy` | Runtime-tunable, operator-visible  | Requires plumbing through announce handler and repositories |
+| Replace `From` impls with explicit constructors       | Removes implicit global dependency | API change for callers                                      |
+
+## Acceptance Criteria
+
+- [ ] A decision (ADR or `DECISIONS.md` entry under EPIC #1669) recording the chosen
+      approach and the rationale.
+- [ ] If the decision is to change the current design: implementation is complete,
+      all tests pass, and the doc reference in `axum-http-server/src/lib.rs` is updated.
+- [ ] `cargo test --workspace` passes.
+- [ ] `linter all` passes.

docs/issues/open/1864-1669-review-torrent-peers-limit/ISSUE.md

@@ -71,7 +71,7 @@
 //! > is behind a reverse proxy.
 //!
 //! > **NOTICE**: the maximum number of peers that the tracker can return is
-//! > `74`. Defined with a hardcoded const [`TORRENT_PEERS_LIMIT`](torrust_tracker_configuration::TORRENT_PEERS_LIMIT).
+//! > `74`. Defined with a hardcoded const [`TORRENT_PEERS_LIMIT`](torrust_tracker_primitives::TORRENT_PEERS_LIMIT).
 //! > Refer to [issue 262](https://github.com/torrust/torrust-tracker/issues/262)
 //! > for more information about this limitation.
 //!

packages/axum-http-server/src/lib.rs

@@ -13,15 +13,12 @@ use std::env;
 use std::sync::Arc;
 
 use camino::Utf8PathBuf;
-use derive_more::{Constructor, Display};
+use derive_more::Display;
 use serde::{Deserialize, Serialize};
 use serde_with::serde_as;
 use thiserror::Error;
 use torrust_located_error::{DynError, LocatedError};
 
-/// The maximum number of returned peers for a torrent.
-pub const TORRENT_PEERS_LIMIT: usize = 74;
-
 // Environment variables
 
 /// The whole `tracker.toml` file content. It has priority over the config file.
@@ -134,53 +131,6 @@ impl Version {
     }
 }
 
-#[derive(Serialize, Deserialize, PartialEq, Eq, Debug, Clone, Constructor)]
-pub struct TrackerPolicy {
-    // Cleanup job configuration
-    /// Maximum time in seconds that a peer can be inactive before being
-    /// considered an inactive peer. If a peer is inactive for more than this
-    /// time, it will be removed from the torrent peer list.
-    #[serde(default = "TrackerPolicy::default_max_peer_timeout")]
-    pub max_peer_timeout: u32,
-
-    /// If enabled the tracker will persist the number of completed downloads.
-    /// That's how many times a torrent has been downloaded completely.
-    #[serde(default = "TrackerPolicy::default_persistent_torrent_completed_stat")]
-    pub persistent_torrent_completed_stat: bool,
-
-    /// If enabled, the tracker will remove torrents that have no peers.
-    /// The clean up torrent job runs every `inactive_peer_cleanup_interval`
-    /// seconds and it removes inactive peers. Eventually, the peer list of a
-    /// torrent could be empty and the torrent will be removed if this option is
-    /// enabled.
-    #[serde(default = "TrackerPolicy::default_remove_peerless_torrents")]
-    pub remove_peerless_torrents: bool,
-}
-
-impl Default for TrackerPolicy {
-    fn default() -> Self {
-        Self {
-            max_peer_timeout: Self::default_max_peer_timeout(),
-            persistent_torrent_completed_stat: Self::default_persistent_torrent_completed_stat(),
-            remove_peerless_torrents: Self::default_remove_peerless_torrents(),
-        }
-    }
-}
-
-impl TrackerPolicy {
-    fn default_max_peer_timeout() -> u32 {
-        900
-    }
-
-    fn default_persistent_torrent_completed_stat() -> bool {
-        false
-    }
-
-    fn default_remove_peerless_torrents() -> bool {
-        true
-    }
-}
-
 /// Information required for loading config
 #[derive(Debug, Default, Clone)]
 pub struct Info {

packages/configuration/src/lib.rs

@@ -1,9 +1,8 @@
-use derive_more::{Constructor, Display};
 use serde::{Deserialize, Serialize};
-use torrust_tracker_primitives::AnnouncePolicy;
+use torrust_tracker_primitives::announce::AnnouncePolicy;
+use torrust_tracker_primitives::{PrivateMode, TrackerPolicy};
 
 use super::network::Network;
-use crate::TrackerPolicy;
 use crate::v2_0_0::database::Database;
 use crate::validator::{SemanticValidationError, Validator};
 
@@ -110,31 +109,6 @@ impl Core {
     }
 }
 
-/// Configuration specific when the tracker is running in private mode.
-#[derive(Serialize, Deserialize, PartialEq, Eq, Debug, Clone, Copy, Constructor, Display)]
-pub struct PrivateMode {
-    /// A flag to disable expiration date for peer keys.
-    ///
-    /// When true, if the keys is not permanent the expiration date will be
-    /// ignored. The key will be accepted even if it has expired.
-    #[serde(default = "PrivateMode::default_check_keys_expiration")]
-    pub check_keys_expiration: bool,
-}
-
-impl Default for PrivateMode {
-    fn default() -> Self {
-        Self {
-            check_keys_expiration: Self::default_check_keys_expiration(),
-        }
-    }
-}
-
-impl PrivateMode {
-    fn default_check_keys_expiration() -> bool {
-        true
-    }
-}
-
 impl Validator for Core {
     fn validate(&self) -> Result<(), SemanticValidationError> {
         if self.private_mode.is_some() && !self.private {

packages/configuration/src/v2_0_0/core.rs

@@ -5,19 +5,23 @@
 //! by the tracker server crate, but also by other crates in the Torrust
 //! ecosystem.
 pub mod announce;
+pub mod mode;
 pub mod number_of_bytes;
 pub mod pagination;
 pub mod peer;
 pub mod peer_id;
+pub mod policy;
 pub mod scrape;
 pub mod swarm_metadata;
 
 use std::collections::BTreeMap;
 
 pub use announce::{AnnounceData, AnnounceEvent, AnnouncePolicy};
 use bittorrent_primitives::info_hash::InfoHash;
+pub use mode::PrivateMode;
 pub use number_of_bytes::NumberOfBytes;
 pub use peer_id::{PeerClient, PeerId};
+pub use policy::{TORRENT_PEERS_LIMIT, TrackerPolicy};
 pub use scrape::ScrapeData;
 /// Duration since the Unix Epoch.
 ///

packages/primitives/src/lib.rs

@@ -0,0 +1,31 @@
+//! Tracker operation mode types.
+//!
+//! This module contains the [`PrivateMode`] struct, which holds
+//! configuration options that apply when the tracker operates in private mode.
+use derive_more::{Constructor, Display};
+use serde::{Deserialize, Serialize};
+
+/// Configuration that applies when the tracker is operating in private mode.
+#[derive(Serialize, Deserialize, PartialEq, Eq, Debug, Clone, Copy, Constructor, Display)]
+pub struct PrivateMode {
+    /// A flag to disable expiration date for peer keys.
+    ///
+    /// When true, if the keys is not permanent the expiration date will be
+    /// ignored. The key will be accepted even if it has expired.
+    #[serde(default = "PrivateMode::default_check_keys_expiration")]
+    pub check_keys_expiration: bool,
+}
+
+impl Default for PrivateMode {
+    fn default() -> Self {
+        Self {
+            check_keys_expiration: Self::default_check_keys_expiration(),
+        }
+    }
+}
+
+impl PrivateMode {
+    fn default_check_keys_expiration() -> bool {
+        true
+    }
+}