diff --git a/docs/issues/drafts/1669-02-move-duration-since-unix-epoch-to-torrust-clock.md b/docs/issues/drafts/1669-02-move-duration-since-unix-epoch-to-torrust-clock.md new file mode 100644 index 000000000..2eae8838d --- /dev/null +++ b/docs/issues/drafts/1669-02-move-duration-since-unix-epoch-to-torrust-clock.md @@ -0,0 +1,163 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p3 +github-issue: null +spec-path: docs/issues/drafts/1669-02-move-duration-since-unix-epoch-to-torrust-clock.md +branch: null +related-pr: null +last-updated-utc: 2026-05-15 12:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - packages/primitives/src/lib.rs + - packages/clock/Cargo.toml + - packages/clock/src/clock/mod.rs + - packages/clock/src/conv/mod.rs + - docs/issues/open/1669-overhaul-packages/EPIC.md + - docs/issues/drafts/1669-06-rename-torrust-tracker-clock-to-torrust-clock.md +--- + + + +# Issue #[To be assigned] - Move `DurationSinceUnixEpoch` from `torrust-tracker-primitives` to `torrust-clock` + +## Goal + +Move the `DurationSinceUnixEpoch` type alias from `torrust-tracker-primitives` into +`torrust-clock` — where it semantically belongs — and update all workspace consumers to +import it from `torrust-clock`. This removes the only `torrust-tracker-*` dependency from +`torrust-clock`, making the crate fully self-contained and ready for future extraction to a +standalone repository. + +## Background + +`DurationSinceUnixEpoch` is defined in `packages/primitives/src/lib.rs` as: + +```rust +pub type DurationSinceUnixEpoch = Duration; +``` + +It is a trivial alias for `std::time::Duration` with no tracker-specific logic. The +`torrust-clock` package is the primary user of this type: it appears in the `Clock` trait +itself (`fn now() -> DurationSinceUnixEpoch`) and in the conversion helpers +(`packages/clock/src/conv/mod.rs`). Having it live in `torrust-tracker-primitives` is an +accident of history, not a design intent. + +After the clock rename (see +[1669-06-rename-torrust-tracker-clock-to-torrust-clock.md](1669-06-rename-torrust-tracker-clock-to-torrust-clock.md)), +`torrust-clock` still carries a `torrust-tracker-primitives` dependency solely for this +type alias. A generic `torrust-clock` crate depending on a `torrust-tracker-*` package is +semantically inconsistent and would block future extraction to a standalone repository. + +**Key implementation note**: Since `DurationSinceUnixEpoch` is a trivial type alias (both +the old and new definitions are `= std::time::Duration`), there is no type incompatibility +between `torrust_tracker_primitives::DurationSinceUnixEpoch` and +`torrust_clock::DurationSinceUnixEpoch`. All 80+ workspace files that currently import the +type from `torrust-tracker-primitives` need only a trivial import path change. + +**Circular dep constraint**: `torrust-tracker-primitives` must **not** re-export the type +from `torrust-clock`. That would introduce a circular dependency (since `torrust-clock` +previously depended on primitives). Instead, `torrust-tracker-primitives` retains its own +independent `pub type DurationSinceUnixEpoch = Duration` definition. Once all workspace +consumers have been migrated to `torrust_clock::DurationSinceUnixEpoch`, the copy in +`torrust-tracker-primitives` can be deprecated and removed in a future cleanup. + +**Prerequisite**: The clock rename subissue (T12 of +[1669-06-rename-torrust-tracker-clock-to-torrust-clock.md](1669-06-rename-torrust-tracker-clock-to-torrust-clock.md)) +must be complete before this subissue begins. + +This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) +(Overhaul: Packages). + +## Scope + +### In Scope + +- Add `pub type DurationSinceUnixEpoch = std::time::Duration;` to `packages/clock/src/lib.rs` + (or a dedicated `types.rs` module), exported as part of the public API. +- Update `packages/clock/src/clock/mod.rs` and `packages/clock/src/conv/mod.rs` to use the + local definition instead of importing from `torrust-tracker-primitives`. +- Remove the `torrust-tracker-primitives` dependency from `packages/clock/Cargo.toml` + (it was added only for this type alias). +- Update all 80+ workspace files that import `DurationSinceUnixEpoch` from + `torrust_tracker_primitives` to import it from `torrust_clock` instead. +- Verify the workspace builds and all tests pass. + +### Out of Scope + +- Removing `DurationSinceUnixEpoch` from `torrust-tracker-primitives`: that requires a + crates.io version bump to signal the breaking change; deferred to a separate cleanup + subissue once all consumers have migrated. +- Changes to the type itself — it stays `= std::time::Duration`. +- Extracting `torrust-clock` to a standalone repository (a separate, later subissue). + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | +| T1 | BLOCKED | Confirm clock rename is complete (T12 of clock rename spec) | `name = "torrust-clock"` in `packages/clock/Cargo.toml` | +| T2 | TODO | Define `DurationSinceUnixEpoch` in `packages/clock/src/lib.rs` | `pub type DurationSinceUnixEpoch = std::time::Duration;` | +| T3 | TODO | Update `packages/clock/src/clock/mod.rs` and `packages/clock/src/conv/mod.rs` to use the local definition | Replace `use torrust_tracker_primitives::DurationSinceUnixEpoch` with local import | +| T4 | TODO | Remove `torrust-tracker-primitives` dep from `packages/clock/Cargo.toml` | Dep entry removed; workspace build still passes | +| T5 | TODO | Update all 80+ workspace files to import `DurationSinceUnixEpoch` from `torrust_clock` instead of `torrust_tracker_primitives` | Use M1 grep to find the full file list; one-line change per file | +| T6 | TODO | Run `cargo build --workspace` and `cargo test --workspace` | Clean build and all tests pass | +| T7 | TODO | Run `linter all` | Exit code `0` | +| T8 | TODO | Update EPIC #1669 extraction ordering table: note that `torrust-clock` has no `torrust-tracker-*` deps | `torrust-clock` row: unpublished runtime workspace deps column set to `None` | + +## Progress Tracking + +### Workflow Checkpoints + +- [ ] Spec drafted in `docs/issues/drafts/` +- [ ] Spec reviewed and approved by user/maintainer +- [ ] Clock rename subissue complete (prerequisite) +- [ ] GitHub issue created and issue number added to this spec +- [ ] Spec moved to `docs/issues/open/` with issue number prefix +- [ ] Implementation completed +- [ ] Automatic verification completed (`linter all`, `cargo test --workspace`) +- [ ] Manual verification scenarios executed and recorded +- [ ] Acceptance criteria reviewed after implementation and updated with evidence +- [ ] EPIC #1669 Active Subissues table updated to `DONE` +- [ ] Issue closed and spec moved to `docs/issues/closed/` + +### Progress Log + +- 2026-05-15 12:00 UTC - josecelano - Spec drafted as subissue of EPIC #1669 following + Option A decision in clock rename spec. `DurationSinceUnixEpoch` has 80+ workspace + consumers; all import from `torrust-tracker-primitives` today. + +## Acceptance Criteria + +- [ ] `packages/clock/src/lib.rs` (or a submodule) exports `pub type DurationSinceUnixEpoch = std::time::Duration`. +- [ ] `packages/clock/Cargo.toml` does not list `torrust-tracker-primitives` as a dependency. +- [ ] No file in `packages/clock/src/` imports `DurationSinceUnixEpoch` from `torrust_tracker_primitives`. +- [ ] No other workspace file imports `DurationSinceUnixEpoch` from `torrust_tracker_primitives` + (all migrated to `torrust_clock`). +- [ ] `cargo build --workspace` succeeds with zero errors. +- [ ] `cargo test --workspace` passes with zero failures. +- [ ] `linter all` exits with code `0`. + +## Verification Plan + +### Automatic Checks + +- `cargo build --workspace` +- `cargo test --doc --workspace` +- `cargo test --tests --workspace --all-targets --all-features` +- `linter all` +- `cargo machete` (no unused dependencies) + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command / Steps | Expected Result | Status | Evidence | +| --- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------- | ------ | -------- | +| M1 | No workspace import from `torrust_tracker_primitives` for this type | `grep -r "torrust_tracker_primitives::DurationSinceUnixEpoch" . --include="*.rs"` | Zero matches | TODO | | +| M2 | `torrust-clock` dep list is clean | `grep "torrust-tracker-primitives" packages/clock/Cargo.toml` | No output | TODO | | +| M3 | `torrust-clock` exports `DurationSinceUnixEpoch` | `grep "DurationSinceUnixEpoch" packages/clock/src/lib.rs` | `pub type DurationSinceUnixEpoch` found | TODO | | diff --git a/docs/issues/drafts/1669-03-move-default-timeout-from-configuration-to-clock.md b/docs/issues/drafts/1669-03-move-default-timeout-from-configuration-to-clock.md new file mode 100644 index 000000000..af6f604f8 --- /dev/null +++ b/docs/issues/drafts/1669-03-move-default-timeout-from-configuration-to-clock.md @@ -0,0 +1,147 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p2 +github-issue: null +spec-path: docs/issues/drafts/1669-03-move-default-timeout-from-configuration-to-clock.md +branch: null +related-pr: null +last-updated-utc: 2026-05-15 12:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - packages/configuration/src/lib.rs + - packages/clock/src/lib.rs + - packages/tracker-client/Cargo.toml + - docs/issues/open/1669-overhaul-packages/EPIC.md + - docs/issues/drafts/rename-torrust-tracker-clock-to-torrust-clock.md +--- + + + +# Issue #[To be assigned] - Move `DEFAULT_TIMEOUT` from `torrust-tracker-configuration` to `torrust-tracker-clock` + +## Goal + +Move the `DEFAULT_TIMEOUT` constant from `packages/configuration` to `packages/clock`, +so that packages needing only a default timeout value do not have to depend on the full +tracker configuration crate. + +## Background + +`DEFAULT_TIMEOUT` is a `Duration` constant (`Duration::from_secs(5)`), defined in +`packages/configuration/src/lib.rs`. It is a time concept — a default duration used as +a network timeout. It does not belong in `configuration`, which is concerned with +tracker configuration structs and their parsing. + +The immediate motivation is `packages/tracker-client`: its `Cargo.toml` lists +`torrust-tracker-configuration` as a dependency, but the only thing it imports from that +crate is `DEFAULT_TIMEOUT` (one import site: `packages/tracker-client/src/udp/client.rs`). +Moving the constant to `clock` removes an unnecessary heavyweight dependency from a +client library. + +Placing `DEFAULT_TIMEOUT` in `clock` also makes semantic sense: `clock` already owns the +mockable time abstraction; default timeout durations are a natural sibling. + +**This issue is a prerequisite** for renaming `torrust-tracker-clock` to `torrust-clock` +(see linked spec). It must be completed and merged first so that the constant travels with +the `clock` package when it is eventually renamed and extracted. + +This issue is a subissue of EPIC #1669 (Overhaul: Packages). + +## Scope + +### In Scope + +- Add `pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(5);` to `packages/clock` + at an appropriate public location. +- Remove `DEFAULT_TIMEOUT` from `packages/configuration/src/lib.rs`. +- Update all 9 source files that use `use torrust_tracker_configuration::DEFAULT_TIMEOUT` + to use `use torrust_tracker_clock::DEFAULT_TIMEOUT`. +- Drop `torrust-tracker-configuration` from `packages/tracker-client/Cargo.toml` (it was + the only reason that dependency existed). +- Verify the workspace builds and all tests pass. + +### Out of Scope + +- Renaming `torrust-tracker-clock` to `torrust-clock` — that is the next subissue. +- Removing `torrust-tracker-configuration` from other packages that imported `DEFAULT_TIMEOUT` + but also use configuration for other purposes — those packages still need the dep. +- Changes to any other constant or API in either crate. + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| T1 | TODO | Add `pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(5);` to `packages/clock` | Choose an appropriate public module (e.g., top of `lib.rs` or a `timeout` mod) | +| T2 | TODO | Remove `DEFAULT_TIMEOUT` from `packages/configuration/src/lib.rs` | Constant no longer in `configuration` | +| T3 | TODO | Update all 9 import sites to `use torrust_tracker_clock::DEFAULT_TIMEOUT` | See file list below | +| T4 | TODO | Remove `torrust-tracker-configuration` from `packages/tracker-client/Cargo.toml` | No longer a dependency; `cargo build -p bittorrent-tracker-client` succeeds | +| T5 | TODO | Run `cargo build --workspace` and `cargo test --workspace` | Clean build; all tests pass | +| T6 | TODO | Run `linter all` | Exit code `0` | + +**Source files to update in T3** (9 files): + +- `packages/tracker-client/src/udp/client.rs` +- `packages/axum-http-tracker-server/src/v1/routes.rs` +- `packages/udp-tracker-server/tests/server/contract.rs` +- `console/tracker-client/src/console/clients/unified/udp.rs` +- `console/tracker-client/src/console/clients/unified/check.rs` +- `console/tracker-client/src/console/clients/unified/http.rs` +- `console/tracker-client/src/console/clients/http/app.rs` +- `console/tracker-client/src/console/clients/checker/service.rs` +- `console/tracker-client/src/console/clients/udp/app.rs` + +## Progress Tracking + +### Workflow Checkpoints + +- [ ] Spec drafted in `docs/issues/drafts/` +- [ ] Spec reviewed and approved by user/maintainer +- [ ] GitHub issue created and issue number added to this spec +- [ ] Spec moved to `docs/issues/open/` with issue number prefix +- [ ] Implementation completed +- [ ] Automatic verification completed (`linter all`, `cargo test --workspace`) +- [ ] Manual verification scenarios executed and recorded +- [ ] Acceptance criteria reviewed after implementation and updated with evidence +- [ ] EPIC #1669 Active Subissues table updated to `DONE` +- [ ] Issue closed and spec moved to `docs/issues/closed/` + +### Progress Log + +- 2026-05-15 12:00 UTC - josecelano - Spec drafted as subissue of EPIC #1669; identified as + prerequisite for the clock rename subissue. + +## Acceptance Criteria + +- [ ] `packages/clock` exports `DEFAULT_TIMEOUT` as a public constant. +- [ ] `packages/configuration` no longer defines `DEFAULT_TIMEOUT`. +- [ ] No source file in the workspace uses `torrust_tracker_configuration::DEFAULT_TIMEOUT`. +- [ ] `packages/tracker-client/Cargo.toml` no longer lists `torrust-tracker-configuration`. +- [ ] `cargo build --workspace` succeeds with zero errors. +- [ ] `cargo test --workspace` passes with zero failures. +- [ ] `linter all` exits with code `0`. +- [ ] `packages/AGENTS.md`, `AGENTS.md`, and `docs/packages.md` are reviewed; no sections reference `DEFAULT_TIMEOUT` as belonging to `torrust-tracker-configuration`. + +## Verification Plan + +### Automatic Checks + +- `cargo build --workspace` +- `cargo test --doc --workspace` +- `cargo test --tests --workspace --all-targets --all-features` +- `linter all` +- `cargo machete` + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command/Steps | Expected Result | Status | Evidence | +| --- | ------------------------------------------------- | ----------------------------------------------------------------------------- | --------------- | ------ | -------- | +| M1 | No stale imports from configuration for timeout | `grep -r "torrust_tracker_configuration::DEFAULT_TIMEOUT" . --include="*.rs"` | Zero matches | TODO | | +| M2 | tracker-client no longer depends on configuration | `grep "torrust-tracker-configuration" packages/tracker-client/Cargo.toml` | Zero matches | TODO | | diff --git a/docs/issues/drafts/1669-04-align-torrust-prefix-rename-tracker-specific-packages.md b/docs/issues/drafts/1669-04-align-torrust-prefix-rename-tracker-specific-packages.md new file mode 100644 index 000000000..b2d0617ac --- /dev/null +++ b/docs/issues/drafts/1669-04-align-torrust-prefix-rename-tracker-specific-packages.md @@ -0,0 +1,208 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p2 +github-issue: null +spec-path: docs/issues/drafts/1669-04-align-torrust-prefix-rename-tracker-specific-packages.md +branch: null +related-pr: null +last-updated-utc: 2026-05-15 12:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - Cargo.toml + - AGENTS.md + - docs/packages.md + - docs/issues/open/1669-overhaul-packages/EPIC.md +--- + + + +# Issue #[To be assigned] - Align `torrust-` prefix: rename tracker-specific packages to `torrust-tracker-` + +## Goal + +Rename the seven crate names that currently carry the bare `torrust-` prefix but contain +tracker-specific logic or depend on tracker-specific crates, so that the `torrust-tracker-` +prefix accurately marks their scope. Where the old name already contains the word "tracker" +in the middle (redundant once it is in the prefix), remove it to produce cleaner names. + +## Background + +The workspace currently has three crate-name prefixes: + +| Prefix | Intended scope | +| ------------------ | ---------------------------------------------------- | +| `bittorrent-` | Generic BitTorrent protocol / community reusable | +| `torrust-` | Reusable across Torrust projects (tracker, index, …) | +| `torrust-tracker-` | Torrust Tracker only | + +Seven crates carry the `torrust-` prefix but belong in the `torrust-tracker-` group: + +| Current crate name | Why it is tracker-specific | +| -------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| `torrust-axum-health-check-api-server` | Depends on `torrust-tracker-configuration` and `torrust-tracker-primitives` | +| `torrust-axum-http-tracker-server` | Implements the BitTorrent HTTP tracker; depends on all tracker-core packages | +| `torrust-axum-rest-tracker-api-server` | Implements the tracker management REST API; deep tracker dependencies | +| `torrust-axum-server` | Axum wrapper configured via `torrust-tracker-configuration`; not generic | +| `torrust-rest-tracker-api-client` | HTTP client for this tracker's REST API; no torrust deps but implements tracker-specific API contract | +| `torrust-rest-tracker-api-core` | Core logic for tracker REST API; depends on all three tracker-core packages | +| `torrust-udp-tracker-server` | Implements the BitTorrent UDP tracker; deep tracker dependencies | + +**None of these crates are published on crates.io** (verified May 2026). The rename has no +external consumers to migrate and does not require any crates.io handling. + +This issue is a subissue of EPIC #1669 (Overhaul: Packages). + +### Proposed name mapping + +Where the old name contained a redundant middle `tracker` segment (already covered by the +new prefix), that segment is removed to produce a shorter, cleaner name. + +| Current name | Proposed new name | Rust identifier change | +| -------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------- | +| `torrust-axum-health-check-api-server` | `torrust-tracker-axum-health-check-api-server` | `torrust_axum_health_check_api_server` → `torrust_tracker_axum_health_check_api_server` | +| `torrust-axum-http-tracker-server` | `torrust-tracker-axum-http-server` | `torrust_axum_http_tracker_server` → `torrust_tracker_axum_http_server` | +| `torrust-axum-rest-tracker-api-server` | `torrust-tracker-axum-rest-api-server` | `torrust_axum_rest_tracker_api_server` → `torrust_tracker_axum_rest_api_server` | +| `torrust-axum-server` | `torrust-tracker-axum-server` | `torrust_axum_server` → `torrust_tracker_axum_server` | +| `torrust-rest-tracker-api-client` | `torrust-tracker-rest-api-client` | `torrust_rest_tracker_api_client` → `torrust_tracker_rest_api_client` | +| `torrust-rest-tracker-api-core` | `torrust-tracker-rest-api-core` | `torrust_rest_tracker_api_core` → `torrust_tracker_rest_api_core` | +| `torrust-udp-tracker-server` | `torrust-tracker-udp-server` | `torrust_udp_tracker_server` → `torrust_tracker_udp_server` | + +### Note on `torrust-server-lib` + +`torrust-server-lib` is described as "Common functionality used in all Torrust HTTP +servers", implying it was intended to be reusable beyond the tracker (e.g., `torrust-index`). +Its only tracker-specific dependency is `torrust-tracker-primitives`, used solely for the +`ServiceBinding` type in `signals.rs` and `registar.rs`. + +**Decision (see Open Questions)**: `torrust-server-lib` is **excluded from this rename**. +The `torrust-` prefix correctly reflects its intended cross-project reuse scope. The +dependency on `torrust-tracker-primitives` should be resolved separately — either by moving +`ServiceBinding` into `torrust-server-lib` itself or into a more neutral crate. A future +issue will cover that design decision. + +## Scope + +### In Scope + +- Rename the `name` field in each of the 7 package `Cargo.toml` files. +- Update the root `Cargo.toml` workspace dependency keys. +- Update all `Cargo.toml` files in the workspace that reference the old names as + dependencies. +- Update all Rust source files that use the crate identifiers (176 occurrences across + `src/`, `packages/`, and `tests/`). +- Update prose references in `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md`, and each package's + `README.md`. +- Verify the workspace builds and all tests pass. + +### Out of Scope + +- Moving any crate to a separate repository. +- Changes to any crate's API or behaviour. +- Deciding the final scope of `torrust-server-lib` / `ServiceBinding` — that is a + follow-up design discussion. +- Publishing any crate on crates.io. + +## Open Questions + +### Should `torrust-server-lib` stay `torrust-` scoped? + +If `ServiceBinding` is moved out of `torrust-tracker-primitives` into a more neutral location +(or into `server-lib` itself), `torrust-server-lib` would have zero tracker-specific +dependencies and could legitimately serve `torrust-index` and other Torrust servers without +pulling in tracker logic. In that case, renaming it to `torrust-tracker-server-lib` now +would be a mistake. + +| Option | Action | Trade-off | +| ------ | ---------------------------------------------------------------- | ------------------------------------------------------------ | +| A | Rename to `torrust-tracker-server-lib` now | Consistent; can always rename back if dep is removed | +| B | Leave as `torrust-server-lib` until `ServiceBinding` is resolved | Preserves future intent; leaves naming inconsistency for now | + +**Decision**: Option B. `torrust-server-lib` is excluded from this rename. The `torrust-` +prefix correctly reflects its intended cross-project reuse scope. The `ServiceBinding` dep +resolution is deferred to a separate issue. See the Note on `torrust-server-lib` in +Background. + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| T1 | TODO | Rename `name` field in each of the 7 package `Cargo.toml` files | See proposed name mapping above | +| T2 | TODO | Update root `Cargo.toml` workspace dependency keys (7 entries) | Replace old key names with new key names; `path` values stay unchanged | +| T3 | TODO | Update dependency references in consumer `Cargo.toml` files (6 files) | See consumer file list below | +| T4 | TODO | Update Rust source `use` / path references (176 occurrences) | See identifier mapping in proposed name table; affects `src/`, `packages/`, `tests/` | +| T5 | TODO | Update prose in `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md`, and each package `README.md` | Crate names and any inline code snippets referencing old names | +| T6 | TODO | Run `cargo build --workspace` and `cargo test --workspace` | Clean build; all tests pass | +| T7 | TODO | Run `linter all` | Exit code `0` | +| T8 | TODO | Update EPIC #1669 `Package Inventory` and `Desired Package State` tables | Move 7 entries from `torrust-` table to `torrust-tracker-` table; drop `Renamed from` notes | + +**Consumer `Cargo.toml` files to update in T3** (6 files; some also appear in T1): + +- `Cargo.toml` (root — workspace dependencies section) +- `packages/axum-health-check-api-server/Cargo.toml` — references `torrust-axum-server` + (dep); `torrust-axum-health-check-api-server` (self, dev-dep), + `torrust-axum-http-tracker-server`, `torrust-axum-rest-tracker-api-server`, + `torrust-udp-tracker-server` (dev-deps) +- `packages/axum-http-tracker-server/Cargo.toml` — references `torrust-axum-server` +- `packages/axum-rest-tracker-api-server/Cargo.toml` — references `torrust-axum-server`, + `torrust-rest-tracker-api-client`, `torrust-rest-tracker-api-core`, + `torrust-udp-tracker-server` (deps + dev-deps) +- `packages/rest-tracker-api-core/Cargo.toml` — references `torrust-udp-tracker-server` +- `packages/tracker-core/Cargo.toml` — references `torrust-rest-tracker-api-client` + +## Progress Tracking + +### Workflow Checkpoints + +- [ ] Spec drafted in `docs/issues/drafts/` +- [x] Open Question on `torrust-server-lib` resolved; decision recorded in spec +- [ ] Spec reviewed and approved by user/maintainer +- [ ] GitHub issue created and issue number added to this spec +- [ ] Spec moved to `docs/issues/open/` with issue number prefix +- [ ] Implementation completed +- [ ] Automatic verification completed (`linter all`, `cargo test --workspace`) +- [ ] Manual verification scenarios executed and recorded +- [ ] Acceptance criteria reviewed after implementation and updated with evidence +- [ ] EPIC #1669 Active Subissues table updated to `DONE` +- [ ] Issue closed and spec moved to `docs/issues/closed/` + +### Progress Log + +- 2026-05-15 12:00 UTC - josecelano - Spec drafted as subissue of EPIC #1669; all 7 packages + confirmed unpublished on crates.io (no external migration required). `torrust-server-lib` + excluded (Option B decision). + +## Acceptance Criteria + +- [ ] No `Cargo.toml` in the workspace declares any of the 7 old crate names. +- [ ] No Rust source file in the workspace uses any of the 7 old Rust identifiers. +- [ ] `cargo build --workspace` succeeds with zero errors. +- [ ] `cargo test --workspace` passes with zero failures. +- [ ] `linter all` exits with code `0`. +- [ ] `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md`, and each renamed package's `README.md` reflect the + new crate names. +- [ ] EPIC #1669 `Package Inventory` and `Desired Package State` tables are updated. + +## Verification Plan + +### Automatic Checks + +- `cargo build --workspace` +- `cargo test --doc --workspace` +- `cargo test --tests --workspace --all-targets --all-features` +- `linter all` +- `cargo machete` + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command/Steps | Expected Result | Status | Evidence | +| --- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------ | -------- | +| M1 | No stale references to old names in TOML | `grep -r "torrust-axum-health-check\|torrust-axum-http-tracker\|torrust-axum-rest-tracker\|torrust-axum-server\b\|torrust-rest-tracker-api\|torrust-udp-tracker-server" . --include="*.toml"` | Zero matches (except own `name =` fields before rename, which should be gone) | TODO | | +| M2 | No stale identifiers in Rust source | `grep -r "torrust_axum_http_tracker_server\|torrust_axum_rest_tracker_api_server\|torrust_rest_tracker_api\|torrust_udp_tracker_server\b" . --include="*.rs"` | Zero matches | TODO | | diff --git a/docs/issues/drafts/1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md b/docs/issues/drafts/1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md new file mode 100644 index 000000000..26267fa79 --- /dev/null +++ b/docs/issues/drafts/1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md @@ -0,0 +1,144 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p2 +github-issue: null +spec-path: docs/issues/drafts/1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md +branch: null +related-pr: null +last-updated-utc: 2026-05-15 12:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - packages/metrics/Cargo.toml + - Cargo.toml + - AGENTS.md + - docs/packages.md + - docs/issues/open/1669-overhaul-packages/EPIC.md +--- + + + +# Issue #[To be assigned] - Rename `torrust-tracker-metrics` to `torrust-metrics` + +## Goal + +Rename the Cargo crate `torrust-tracker-metrics` to `torrust-metrics` to reflect that it is +a generic Prometheus metrics integration that can be used by any Rust project, not only the +tracker. + +## Background + +The `metrics` package (folder `packages/metrics`) provides Prometheus metrics support. It +contains no tracker-specific domain logic and its usefulness extends beyond this repository +— for example, `torrust-index` could benefit from the same metrics infrastructure rather +than reinventing it. + +The `torrust-tracker-` prefix implies a tracker-only scope that does not reflect the crate's +actual purpose. The rename: + +- Makes the crate identity match its scope. +- Signals to downstream users that it is reusable outside the tracker. +- Prepares it for potential extraction to a standalone repository in a future cycle + (see [1669-10-extract-torrust-metrics-to-standalone-repo.md](1669-10-extract-torrust-metrics-to-standalone-repo.md)). + +The current crate name `torrust-tracker-metrics` is **not published on crates.io** (as of +May 2026), so the rename does not require handling a previously published name. + +This issue is a subissue of EPIC #1669 (Overhaul: Packages). + +## Scope + +### In Scope + +- Rename the crate `name` field in `packages/metrics/Cargo.toml`. +- Update all `Cargo.toml` files in the workspace that reference `torrust-tracker-metrics` + as a dependency (root `Cargo.toml` + all dependent packages). +- Update all Rust source files that use the crate by its underscore-converted identifier + (`torrust_tracker_metrics::`) to use `torrust_metrics::`. +- Update prose references in `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md`, and the `metrics` package + `README.md`. +- Verify the workspace builds and all tests pass. + +### Out of Scope + +- Moving the crate to a separate repository — see + [1669-10-extract-torrust-metrics-to-standalone-repo.md](1669-10-extract-torrust-metrics-to-standalone-repo.md). +- Changes to the crate's API or behaviour. +- Publishing the crate on crates.io — that is a separate concern not required for the rename. +- Updating downstream repositories — that is a separate task per repository. + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------ | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| T1 | TODO | Rename `name` in `packages/metrics/Cargo.toml` | `name = "torrust-metrics"` | +| T2 | TODO | Update root `Cargo.toml` workspace dependency key | `torrust-metrics = { version = ..., path = "packages/metrics" }` | +| T3 | TODO | Update all dependent package `Cargo.toml` files (7 packages) | Replace `torrust-tracker-metrics` key with `torrust-metrics` | +| T4 | TODO | Update Rust source `use` / path references (`torrust_tracker_metrics::` → `torrust_metrics::`) | Affects package sources and integration tests | +| T5 | TODO | Update prose in `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md`, `packages/metrics/README.md` | Crate name and any inline code snippets | +| T6 | TODO | Run `cargo build --workspace` and `cargo test --workspace` | Clean build and all tests pass | +| T7 | TODO | Run `linter all` | Exit code `0` | +| T8 | TODO | Update EPIC #1669 `Package Inventory` and `Desired Package State` tables | Move `torrust-metrics` from `torrust-tracker-` to `torrust-`; drop `Renamed from` note | + +**Dependent packages to update in T3** (7 files): + +- `packages/axum-rest-tracker-api-server/Cargo.toml` +- `packages/http-tracker-core/Cargo.toml` +- `packages/rest-tracker-api-core/Cargo.toml` +- `packages/swarm-coordination-registry/Cargo.toml` +- `packages/tracker-core/Cargo.toml` +- `packages/udp-tracker-core/Cargo.toml` +- `packages/udp-tracker-server/Cargo.toml` + +## Progress Tracking + +### Workflow Checkpoints + +- [ ] Spec drafted in `docs/issues/drafts/` +- [ ] Spec reviewed and approved by user/maintainer +- [ ] GitHub issue created and issue number added to this spec +- [ ] Spec moved to `docs/issues/open/` with issue number prefix +- [ ] Implementation completed +- [ ] Automatic verification completed (`linter all`, `cargo test --workspace`) +- [ ] Manual verification scenarios executed and recorded +- [ ] Acceptance criteria reviewed after implementation and updated with evidence +- [ ] EPIC #1669 Active Subissues table updated to `DONE` +- [ ] Issue closed and spec moved to `docs/issues/closed/` + +### Progress Log + +- 2026-05-15 12:00 UTC - josecelano - Spec drafted as subissue of EPIC #1669 + +## Acceptance Criteria + +- [ ] `packages/metrics/Cargo.toml` declares `name = "torrust-metrics"`. +- [ ] No `Cargo.toml` file in the workspace references `torrust-tracker-metrics`. +- [ ] No Rust source file in the workspace uses `torrust_tracker_metrics::`. +- [ ] `cargo build --workspace` succeeds with zero errors. +- [ ] `cargo test --workspace` passes with zero failures. +- [ ] `linter all` exits with code `0`. +- [ ] `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md`, and `packages/metrics/README.md` reflect the new crate name. +- [ ] EPIC #1669 `Desired Package State` table lists `torrust-metrics` in the `torrust-` section. + +## Verification Plan + +### Automatic Checks + +- `cargo build --workspace` +- `cargo test --doc --workspace` +- `cargo test --tests --workspace --all-targets --all-features` +- `linter all` +- `cargo machete` (no unused dependencies) + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command/Steps | Expected Result | Status | Evidence | +| --- | ------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------- | ------ | -------- | +| M1 | No stale references to old crate name | `grep -r "torrust-tracker-metrics\|torrust_tracker_metrics" . --include="*.toml" --include="*.rs"` | Zero matches | TODO | | diff --git a/docs/issues/drafts/1669-06-rename-torrust-tracker-clock-to-torrust-clock.md b/docs/issues/drafts/1669-06-rename-torrust-tracker-clock-to-torrust-clock.md new file mode 100644 index 000000000..1c2ae81a8 --- /dev/null +++ b/docs/issues/drafts/1669-06-rename-torrust-tracker-clock-to-torrust-clock.md @@ -0,0 +1,190 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p2 +github-issue: null +spec-path: docs/issues/drafts/1669-06-rename-torrust-tracker-clock-to-torrust-clock.md +branch: null +related-pr: null +last-updated-utc: 2026-05-15 12:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - packages/clock/Cargo.toml + - Cargo.toml + - AGENTS.md + - docs/packages.md + - docs/issues/open/1669-overhaul-packages/EPIC.md +--- + + + +# Issue #[To be assigned] - Rename `torrust-tracker-clock` to `torrust-clock` + +## Goal + +Rename the Cargo crate `torrust-tracker-clock` to `torrust-clock` to reflect that it is a +generic, tracker-independent utility that can be used in any Rust project (e.g., +`torrust-index`). + +## Background + +The `clock` package (folder `packages/clock`) provides a mockable time abstraction for +deterministic testing. It contains no tracker-specific logic and its usefulness extends +beyond this repository — for example, `torrust-index` already contains copied clock code +(). + +The `torrust-tracker-` prefix implies a tracker-only scope that does not reflect the +crate's actual purpose. The rename: + +- Makes the crate identity match its scope. +- Signals to downstream users that it is reusable outside the tracker. +- Prepares it for potential extraction to a standalone repository in a future cycle + (see [1669-09-extract-torrust-clock-to-standalone-repo.md](1669-09-extract-torrust-clock-to-standalone-repo.md)). + +The current crate name `torrust-tracker-clock` is **published on crates.io** (as of +May 2026). The rename requires publishing the new name `torrust-clock` and handling the +old published name (yank or deprecation notice). + +**This issue has a prerequisite**: the `DEFAULT_TIMEOUT` constant must be moved from +`torrust-tracker-configuration` to `torrust-tracker-clock` before this rename is started, +so that the constant travels with the `clock` package. See +[1669-03-move-default-timeout-from-configuration-to-clock.md](1669-03-move-default-timeout-from-configuration-to-clock.md). + +**Residual tracker-namespaced dep**: After the rename, `torrust-clock` will still depend on +`torrust-tracker-primitives` for `DurationSinceUnixEpoch`. That type is a plain +`pub type DurationSinceUnixEpoch = Duration` — a trivial alias for `std::time::Duration` +with no tracker-specific logic. A generic `torrust-clock` crate depending on a +`torrust-tracker-*` package is semantically inconsistent. + +**Decision — Option A**: Move `DurationSinceUnixEpoch` from `torrust-tracker-primitives` +into `torrust-clock`. The primitives dep does **not block publishing `torrust-clock`** (the +crate is already published), so this move can happen as a dedicated follow-up after the +rename is complete. A separate draft subissue covers the migration of the 80+ workspace +consumers currently importing the type from `torrust-tracker-primitives`: +see [1669-02-move-duration-since-unix-epoch-to-torrust-clock.md](1669-02-move-duration-since-unix-epoch-to-torrust-clock.md). + +This issue is a subissue of EPIC #1669 (Overhaul: Packages). + +## Scope + +### In Scope + +- Rename the crate `name` field in `packages/clock/Cargo.toml`. +- Update all `Cargo.toml` files in the workspace that reference `torrust-tracker-clock` + as a dependency (root `Cargo.toml` + all dependent packages). +- Update all Rust source files that use the crate by its underscore-converted identifier + (`torrust_tracker_clock::`) to use `torrust_clock::`. +- Update prose references in `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md`, and the `clock` package + `README.md`. +- Verify the workspace builds and all tests pass. +- Publish `torrust-clock` on crates.io. +- Handle the old crates.io name `torrust-tracker-clock`: first add a deprecation notice / + README update pointing to `torrust-clock`; yank all versions only after `torrust-index` + migration is merged (see Companion work). + +### Out of Scope + +- Moving the crate to a separate repository — see + [1669-09-extract-torrust-clock-to-standalone-repo.md](1669-09-extract-torrust-clock-to-standalone-repo.md). +- Changes to the crate's API or behaviour. + +### Companion work (other repositories) + +`torrust-index` currently contains a copy of the clock code rather than a proper dependency +(see Background). After `torrust-clock` is published, `torrust-index` must be updated to +depend on `torrust-clock` and delete its local copy. This work happens in the +`torrust/torrust-index` repository and must be completed **before** the old crates.io name +`torrust-tracker-clock` is yanked. See T10. + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| T1 | TODO | Rename `name` in `packages/clock/Cargo.toml` | `name = "torrust-clock"` | +| T2 | TODO | Update root `Cargo.toml` workspace dependency key | `torrust-clock = { version = ..., path = "packages/clock" }` | +| T3 | TODO | Update all dependent package `Cargo.toml` files (10 packages, excluding root — see T2) | Replace `torrust-tracker-clock` key with `torrust-clock` in each | +| T4 | TODO | Update Rust source `use` / path references (`torrust_tracker_clock::` → `torrust_clock::`) | Affects `src/`, package sources, and integration tests | +| T5 | TODO | Update prose in `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md`, `packages/clock/README.md` | Crate name and any inline code snippets | +| T6 | TODO | Run `cargo build --workspace` and `cargo test --workspace` | Clean build and all tests pass | +| T7 | TODO | Run `linter all` | Exit code `0` | +| T8 | TODO | Publish `torrust-clock` on crates.io | Successful `cargo publish -p torrust-clock` | +| T9 | TODO | Add deprecation notice to `torrust-tracker-clock` on crates.io | README / description points to `torrust-clock`; do **not** yank yet | +| T10 | TODO | Update `torrust-index`: replace copied clock code with `torrust-clock` dep | Companion PR in `torrust/torrust-index`; must be merged before T11 | +| T11 | TODO | Yank all versions of `torrust-tracker-clock` on crates.io | All versions yanked; downstream migration (T10) must be complete first | +| T12 | TODO | Update EPIC #1669 `Package Inventory` and `Desired Package State` tables | Move `torrust-clock` from `torrust-tracker-` to `torrust-`; drop `Renamed from` note | + +**Dependent packages to update in T3** (10 files; root `Cargo.toml` is handled in T2): + +- `packages/axum-health-check-api-server/Cargo.toml` +- `packages/axum-http-tracker-server/Cargo.toml` (appears in both `[dependencies]` and `[dev-dependencies]`) +- `packages/axum-rest-tracker-api-server/Cargo.toml` +- `packages/http-protocol/Cargo.toml` +- `packages/http-tracker-core/Cargo.toml` +- `packages/swarm-coordination-registry/Cargo.toml` +- `packages/tracker-core/Cargo.toml` +- `packages/torrent-repository-benchmarking/Cargo.toml` +- `packages/udp-tracker-core/Cargo.toml` +- `packages/udp-tracker-server/Cargo.toml` + +## Progress Tracking + +### Workflow Checkpoints + +- [ ] Spec drafted in `docs/issues/drafts/` +- [ ] Spec reviewed and approved by user/maintainer +- [ ] GitHub issue created and issue number added to this spec +- [ ] Spec moved to `docs/issues/open/` with issue number prefix +- [ ] Implementation completed +- [ ] Automatic verification completed (`linter all`, `cargo test --workspace`) +- [ ] Manual verification scenarios executed and recorded +- [ ] Acceptance criteria reviewed after implementation and updated with evidence +- [ ] `torrust-clock` published on crates.io; deprecation notice added to old name +- [ ] `torrust-index` migrated to `torrust-clock` (companion PR merged) +- [ ] `torrust-tracker-clock` yanked on crates.io +- [ ] EPIC #1669 Active Subissues table updated to `DONE` +- [ ] Issue closed and spec moved to `docs/issues/closed/` + +### Progress Log + +- 2026-05-15 12:00 UTC - josecelano - Spec drafted as subissue of EPIC #1669 + +## Acceptance Criteria + +- [ ] `packages/clock/Cargo.toml` declares `name = "torrust-clock"`. +- [ ] No `Cargo.toml` file in the workspace references `torrust-tracker-clock`. +- [ ] No Rust source file in the workspace uses `torrust_tracker_clock::`. +- [ ] `cargo build --workspace` succeeds with zero errors. +- [ ] `cargo test --workspace` passes with zero failures. +- [ ] `linter all` exits with code `0`. +- [ ] `torrust-clock` is published and visible on crates.io. +- [ ] `torrust-tracker-clock` has a deprecation notice pointing to `torrust-clock`. +- [ ] `torrust-index` no longer contains a local copy of clock code; it depends on `torrust-clock`. +- [ ] `torrust-tracker-clock` is yanked on crates.io (only after `torrust-index` migration is merged). +- [ ] `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md`, and `packages/clock/README.md` reflect the new crate name. +- [ ] EPIC #1669 `Desired Package State` table lists `torrust-clock` in the `torrust-` section. + +## Verification Plan + +### Automatic Checks + +- `cargo build --workspace` +- `cargo test --doc --workspace` +- `cargo test --tests --workspace --all-targets --all-features` +- `linter all` +- `cargo machete` (no unused dependencies) + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command/Steps | Expected Result | Status | Evidence | +| --- | ------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------ | ------ | -------- | +| M1 | No stale references to old crate name | `grep -r "torrust-tracker-clock\|torrust_tracker_clock" . --include="*.toml" --include="*.rs"` | Zero matches | TODO | | +| M2 | New crate name visible on crates.io | Visit `https://crates.io/crates/torrust-clock` | Crate page exists and shows latest version | TODO | | +| M3 | Old crate name yanked | Visit `https://crates.io/crates/torrust-tracker-clock` | All versions show "yanked" | TODO | | +| M4 | `torrust-index` migration merged | Check `torrust/torrust-index` for `torrust-clock` dep; no local clock copy | PR merged; no copied clock code present | TODO | | diff --git a/docs/issues/drafts/1669-07-rename-torrust-tracker-located-error-to-torrust-located-error.md b/docs/issues/drafts/1669-07-rename-torrust-tracker-located-error-to-torrust-located-error.md new file mode 100644 index 000000000..36c4af1af --- /dev/null +++ b/docs/issues/drafts/1669-07-rename-torrust-tracker-located-error-to-torrust-located-error.md @@ -0,0 +1,169 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p2 +github-issue: null +spec-path: docs/issues/drafts/1669-07-rename-torrust-tracker-located-error-to-torrust-located-error.md +branch: null +related-pr: null +last-updated-utc: 2026-05-15 12:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - packages/located-error/Cargo.toml + - Cargo.toml + - AGENTS.md + - docs/packages.md + - docs/issues/open/1669-overhaul-packages/EPIC.md +--- + + + +# Issue #[To be assigned] - Rename `torrust-tracker-located-error` to `torrust-located-error` + +## Goal + +Rename the Cargo crate `torrust-tracker-located-error` to `torrust-located-error` to reflect +that it is a generic, tracker-independent error decoration utility that can be used in any +Rust project (e.g., `torrust-index`). + +## Background + +The `located-error` package (folder `packages/located-error`) provides an error decorator +that attaches source-location information to errors — a generic debugging utility with no +tracker-specific logic. Its only runtime dependency is `tracing`, a general-purpose +structured logging crate. There is nothing in the implementation that ties it to the +BitTorrent tracker. + +The `torrust-tracker-` prefix implies a tracker-only scope that does not reflect the crate's +actual purpose. The rename: + +- Makes the crate identity match its scope. +- Signals to downstream users that it is reusable outside the tracker. +- Prepares it for potential extraction to a standalone repository in a future cycle. + +The current crate name `torrust-tracker-located-error` is **published on crates.io** (as of +May 2026). The rename requires publishing the new name `torrust-located-error` and handling +the old published name (deprecation notice, then yank after downstream migration). + +This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) +(Overhaul: Packages). + +## Scope + +### In Scope + +- Rename the `name` field in `packages/located-error/Cargo.toml`. +- Update all `Cargo.toml` files in the workspace that reference `torrust-tracker-located-error` + as a dependency (root `Cargo.toml` + all 5 dependent packages — see T3). +- Update all Rust source files that use the crate by its underscore-converted identifier + (`torrust_tracker_located_error::`) to use `torrust_located_error::`. +- Update prose references in `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md`, and the + `located-error` package `README.md`. +- Verify the workspace builds and all tests pass. +- Publish `torrust-located-error` on crates.io. +- Handle the old crates.io name `torrust-tracker-located-error`: first add a deprecation + notice / README update pointing to `torrust-located-error`; yank all versions only after + any known downstream Torrust repositories are migrated (see Companion work). + +### Out of Scope + +- Moving the crate to a separate repository (a future extraction subissue). +- Changes to the crate's API or behaviour. + +### Companion Work (other repositories) + +After `torrust-located-error` is published, check all Torrust repositories (e.g., +`torrust-index`) that may depend on the published `torrust-tracker-located-error`. Companion +PRs must be merged in those repos before yanking the old name. Yanking (T11) must happen +only after T10 is complete. + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------ | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| T1 | TODO | Rename `name` in `packages/located-error/Cargo.toml` | `name = "torrust-located-error"` | +| T2 | TODO | Update root `Cargo.toml` workspace dependency key | `torrust-located-error = { version = ..., path = "packages/located-error" }` | +| T3 | TODO | Update all 5 dependent package `Cargo.toml` files (excluding root — see T2) | Replace `torrust-tracker-located-error` key with `torrust-located-error` | +| T4 | TODO | Update Rust source `use` / path references (`torrust_tracker_located_error::` → `torrust_located_error::`) | Affects package sources and integration tests | +| T5 | TODO | Update prose in `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md`, `packages/located-error/README.md` | Crate name and any inline code snippets | +| T6 | TODO | Run `cargo build --workspace` and `cargo test --workspace` | Clean build and all tests pass | +| T7 | TODO | Run `linter all` | Exit code `0` | +| T8 | TODO | Publish `torrust-located-error` on crates.io | Successful `cargo publish -p torrust-located-error` | +| T9 | TODO | Add deprecation notice to `torrust-tracker-located-error` on crates.io | README / description points to `torrust-located-error`; do **not** yank yet | +| T10 | TODO | Check and migrate any downstream Torrust repositories using `torrust-tracker-located-error` | Companion PRs in downstream repos merged; must be complete before T11 | +| T11 | TODO | Yank all versions of `torrust-tracker-located-error` on crates.io | All versions yanked; T10 must be complete first | +| T12 | TODO | Update EPIC #1669 `Package Inventory` and `Desired Package State` tables | Move `torrust-located-error` from `torrust-tracker-` to `torrust-` prefix | + +**Dependent packages to update in T3** (5 files; root `Cargo.toml` is handled in T2): + +- `packages/configuration/Cargo.toml` +- `packages/axum-server/Cargo.toml` +- `packages/http-protocol/Cargo.toml` +- `packages/tracker-core/Cargo.toml` +- `packages/tracker-client/Cargo.toml` + +## Progress Tracking + +### Workflow Checkpoints + +- [ ] Spec drafted in `docs/issues/drafts/` +- [ ] Spec reviewed and approved by user/maintainer +- [ ] GitHub issue created and issue number added to this spec +- [ ] Spec moved to `docs/issues/open/` with issue number prefix +- [ ] Implementation completed +- [ ] Automatic verification completed (`linter all`, `cargo test --workspace`) +- [ ] Manual verification scenarios executed and recorded +- [ ] Acceptance criteria reviewed after implementation and updated with evidence +- [ ] `torrust-located-error` published on crates.io; deprecation notice added to old name +- [ ] Downstream Torrust repositories migrated to `torrust-located-error` (T10 companion PRs merged) +- [ ] `torrust-tracker-located-error` yanked on crates.io (T11) +- [ ] EPIC #1669 Active Subissues table updated to `DONE` +- [ ] Issue closed and spec moved to `docs/issues/closed/` + +### Progress Log + +- 2026-05-15 12:00 UTC - josecelano - Spec drafted as subissue of EPIC #1669 + +## Acceptance Criteria + +- [ ] `packages/located-error/Cargo.toml` declares `name = "torrust-located-error"`. +- [ ] No `Cargo.toml` file in the workspace references `torrust-tracker-located-error`. +- [ ] No Rust source file in the workspace uses `torrust_tracker_located_error::`. +- [ ] `cargo build --workspace` succeeds with zero errors. +- [ ] `cargo test --workspace` passes with zero failures. +- [ ] `linter all` exits with code `0`. +- [ ] `torrust-located-error` is published and visible on crates.io. +- [ ] `torrust-tracker-located-error` has a deprecation notice pointing to `torrust-located-error`. +- [ ] All known downstream Torrust repositories using `torrust-tracker-located-error` have been + migrated to `torrust-located-error` (T10 complete). +- [ ] `torrust-tracker-located-error` is yanked on crates.io (only after T10 is complete). +- [ ] `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md`, and `packages/located-error/README.md` + reflect the new crate name. +- [ ] EPIC #1669 `Desired Package State` table lists `torrust-located-error` in the `torrust-` + prefix section. + +## Verification Plan + +### Automatic Checks + +- `cargo build --workspace` +- `cargo test --doc --workspace` +- `cargo test --tests --workspace --all-targets --all-features` +- `linter all` +- `cargo machete` (no unused dependencies) + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command / Steps | Expected Result | Status | Evidence | +| --- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------ | -------- | +| M1 | No stale references to old crate name | `grep -r "torrust-tracker-located-error\|torrust_tracker_located_error" . --include="*.toml" --include="*.rs"` | Zero matches | TODO | | +| M2 | New crate name visible on crates.io | Visit `https://crates.io/crates/torrust-located-error` | Crate page exists and shows latest version | TODO | | +| M3 | Old crate name yanked | Visit `https://crates.io/crates/torrust-tracker-located-error` | All versions show "yanked" | TODO | | +| M4 | Downstream Torrust repositories clean | Check `torrust-index` and other Torrust repos for `torrust-tracker-located-error` dependency | No references found after T10 | TODO | | diff --git a/docs/issues/drafts/1669-08-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md b/docs/issues/drafts/1669-08-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md new file mode 100644 index 000000000..4b9fe9013 --- /dev/null +++ b/docs/issues/drafts/1669-08-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md @@ -0,0 +1,192 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p2 +github-issue: null +spec-path: docs/issues/drafts/1669-08-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md +branch: null +related-pr: null +last-updated-utc: 2026-05-15 12:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - contrib/bencode/Cargo.toml + - Cargo.toml + - packages/http-protocol/Cargo.toml + - AGENTS.md + - docs/packages.md + - docs/issues/open/1669-overhaul-packages/EPIC.md +--- + + + +# Issue #[To be assigned] - Extract and rename `torrust-tracker-contrib-bencode` to `torrust-bencode` + +## Goal + +Rename the crate `torrust-tracker-contrib-bencode` to `torrust-bencode`, extract it from +the tracker workspace into its own standalone repository, and publish it independently on +crates.io so that any Rust project can consume it without a dependency on the tracker. + +## Background + +The `contrib/bencode` package is a pure bencode encode/decode library with no +tracker-specific logic. Several facts confirm it is ready for independent life: + +- **No tracker dependencies**: its only runtime dependency is `thiserror`. +- **No crates.io publication blockers**: all runtime dependencies are external crates already + on crates.io. The extraction can proceed without publishing any other workspace package + first. _(Publication blocker analysis reviewed May 2026.)_ +- **Separate license**: Apache-2.0, unlike the tracker's AGPL-3.0-only. Having it in the + same workspace creates a mixed-license surface that confuses downstream users. +- **Already published on crates.io** as `torrust-tracker-contrib-bencode` (verified May 2026). +- **`repository` already points elsewhere**: `contrib/bencode/Cargo.toml` declares + `repository = "https://github.com/torrust/bittorrent-infrastructure-project"`, + signalling the intent to move it out of the tracker repo. +- **Only one internal consumer**: `packages/http-protocol` depends on it. After extraction + that dependency becomes a normal crates.io dependency — no other workspace packages change. +- **`contrib/` is the wrong home**: the `contrib/` prefix signals community-contributed + code living temporarily in the workspace; this crate has been here long enough to graduate. + +The rename drops the `torrust-tracker-contrib-` prefix: + +- `torrust-tracker-` scopes it to the tracker — wrong. +- `-contrib-` marks it as transient community code — no longer accurate. +- `torrust-bencode` is the shortest accurate name: Torrust-namespace, bencode purpose. + +This issue is a subissue of EPIC #1669 (Overhaul: Packages). + +## Scope + +### In Scope + +- Rename the crate `name` in `contrib/bencode/Cargo.toml` to `torrust-bencode`. +- Create (or confirm and use) the target standalone repository. Two options — resolve before + starting implementation (see Open Questions). +- Move the crate source to the new repository, preserving git history. +- Set up CI in the new repository (build, test, lint, publish workflow). +- Publish `torrust-bencode` on crates.io from the new repository. +- Update `packages/http-protocol/Cargo.toml` to depend on the published `torrust-bencode` + crate (remove the local path dependency). +- Remove `contrib/bencode/` from the tracker workspace: + - Remove from `members` in the root `Cargo.toml`. + - Remove the workspace dependency entry for `torrust-tracker-contrib-bencode`. +- Update `packages/AGENTS.md`, `AGENTS.md` Package Catalog, and `docs/packages.md`. +- Handle the old crates.io name `torrust-tracker-contrib-bencode`: yank all versions and + publish a notice pointing to `torrust-bencode`. + +### Out of Scope + +- Changes to the crate's API or behaviour. +- Updating other downstream repositories (e.g., `torrust-index`) — separate task per repo. +- Extracting other `bittorrent-*` or `contrib/` crates — each gets its own subissue. + +## Open Questions + +### Target repository + +Two options: + +| Option | Repository | Rationale | +| ------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| A | `https://github.com/torrust/torrust-bencode` (new) | Matches the crate name; cleanest standalone story | +| B | `https://github.com/torrust/bittorrent-infrastructure-project` (existing) | Already referenced in `Cargo.toml`; may host multiple bittorrent utility crates | + +**Context**: The crate was copied into this repo by @da2ce7 (Cameron Garnham) in commit +`a4ac6829` ("dev: copy bencode into local contrib folder"). The `Cargo.toml` `repository` +field already points to `bittorrent-infrastructure-project`, suggesting that was the intended +canonical home. However, it is unclear whether: + +- the copy in this repo has diverged from whatever lives in `bittorrent-infrastructure-project`, +- `bittorrent-infrastructure-project` already has CI and workspace structure suitable for + multi-crate hosting, or +- the original intent was a new standalone `torrust-bencode` repo. + +**Questions for @da2ce7 before starting T3**: + +1. Why was the crate copied into the tracker workspace rather than depended on as an external + crate at the time? +2. Is there a canonical or newer version of this code in `bittorrent-infrastructure-project`, + or is this tracker copy the authoritative source? +3. What is your preferred extraction target — new `torrust/torrust-bencode` repo (Option A) + or `torrust/bittorrent-infrastructure-project` (Option B)? + +**Recommendation**: Pending @da2ce7's input. Decide before starting T3. + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| T1 | TODO | Rename `name` in `contrib/bencode/Cargo.toml` to `torrust-bencode` | `name = "torrust-bencode"` | +| T2 | TODO | Update `repository` URL in `contrib/bencode/Cargo.toml` to match chosen target repo | Depends on Open Question resolution | +| T3 | TODO | Create or confirm the target standalone repository | Repo exists, README and LICENSE committed | +| T4 | TODO | Move crate source to the new repository, preserving git history | `git filter-repo` or subtree split; history preserved under `contrib/bencode/` | +| T5 | TODO | Set up CI in the new repository (build, test, lint, publish workflow) | CI green on first push | +| T6 | TODO | Publish `torrust-bencode` on crates.io from the new repository | Successful `cargo publish`; crate visible at crates.io/crates/torrust-bencode | +| T7 | TODO | Update `packages/http-protocol/Cargo.toml`: replace path dep with published `torrust-bencode` | `torrust-bencode = "X.Y.Z"` (no path) | +| T8 | TODO | Remove `contrib/bencode/` from tracker workspace (`members` + workspace dep in `Cargo.toml`) | `cargo build --workspace` succeeds without the local crate | +| T9 | TODO | Delete `contrib/bencode/` directory from the tracker repo | Directory gone; workspace still builds | +| T10 | TODO | Update `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md`, and any README references | No stale references to `torrust-tracker-contrib-bencode` | +| T11 | TODO | Run `cargo build --workspace`, `cargo test --workspace`, `linter all` | All green | +| T12 | TODO | Yank old crates.io name `torrust-tracker-contrib-bencode` and add deprecation notice | All versions yanked; description points to `torrust-bencode` | +| T13 | TODO | Update EPIC #1669 `Package Inventory` and `Desired Package State` tables | Remove `torrust-tracker-contrib-bencode` from `torrust-tracker-` table; mark as extracted | + +## Progress Tracking + +### Workflow Checkpoints + +- [ ] Spec drafted in `docs/issues/drafts/` +- [ ] Open Question (target repository) resolved +- [ ] Spec reviewed and approved by user/maintainer +- [ ] GitHub issue created and issue number added to this spec +- [ ] Spec moved to `docs/issues/open/` with issue number prefix +- [ ] Implementation completed +- [ ] Automatic verification completed (`linter all`, `cargo test --workspace`) +- [ ] Manual verification scenarios executed and recorded +- [ ] Acceptance criteria reviewed after implementation and updated with evidence +- [ ] `torrust-bencode` published from the new repository; old name yanked +- [ ] EPIC #1669 Active Subissues table updated to `DONE` +- [ ] Issue closed and spec moved to `docs/issues/closed/` + +### Progress Log + +- 2026-05-15 12:00 UTC - josecelano - Spec drafted as subissue of EPIC #1669 + +## Acceptance Criteria + +- [ ] `contrib/bencode/` directory no longer exists in the tracker workspace. +- [ ] Root `Cargo.toml` does not list `contrib/bencode` as a workspace member. +- [ ] No `Cargo.toml` in the tracker workspace references `torrust-tracker-contrib-bencode`. +- [ ] `packages/http-protocol/Cargo.toml` depends on the published `torrust-bencode`. +- [ ] `cargo build --workspace` succeeds without the local bencode crate. +- [ ] `cargo test --workspace` passes with zero failures. +- [ ] `linter all` exits with code `0`. +- [ ] `torrust-bencode` is published and visible on crates.io. +- [ ] `torrust-tracker-contrib-bencode` is yanked or carries a deprecation notice. +- [ ] The new repository has passing CI and a published release. +- [ ] `packages/AGENTS.md`, `AGENTS.md`, and `docs/packages.md` no longer list `torrust-tracker-contrib-bencode`. + +## Verification Plan + +### Automatic Checks + +- `cargo build --workspace` +- `cargo test --doc --workspace` +- `cargo test --tests --workspace --all-targets --all-features` +- `linter all` +- `cargo machete` + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command/Steps | Expected Result | Status | Evidence | +| --- | ----------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------ | -------- | +| M1 | No stale workspace reference to old crate | `grep -r "torrust-tracker-contrib-bencode\|contrib/bencode" . --include="*.toml" --include="*.rs"` | Zero matches in tracker repo | TODO | | +| M2 | New crate visible on crates.io | Visit `https://crates.io/crates/torrust-bencode` | Crate page exists, latest version shown | TODO | | +| M3 | Old crate yanked | Visit `https://crates.io/crates/torrust-tracker-contrib-bencode` | All versions show "yanked" or deprecation notice | TODO | | +| M4 | New repository CI green | Check CI status on the new repository's default branch | All checks pass | TODO | | diff --git a/docs/issues/drafts/1669-09-extract-torrust-clock-to-standalone-repo.md b/docs/issues/drafts/1669-09-extract-torrust-clock-to-standalone-repo.md new file mode 100644 index 000000000..4ba8f3725 --- /dev/null +++ b/docs/issues/drafts/1669-09-extract-torrust-clock-to-standalone-repo.md @@ -0,0 +1,178 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p3 +github-issue: null +spec-path: docs/issues/drafts/1669-09-extract-torrust-clock-to-standalone-repo.md +branch: null +related-pr: null +last-updated-utc: 2026-05-15 12:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - packages/clock/Cargo.toml + - Cargo.toml + - docs/packages.md + - AGENTS.md + - docs/issues/open/1669-overhaul-packages/EPIC.md + - docs/issues/drafts/1669-06-rename-torrust-tracker-clock-to-torrust-clock.md + - docs/issues/drafts/1669-02-move-duration-since-unix-epoch-to-torrust-clock.md +--- + + + +# Issue #[To be assigned] - Extract `torrust-clock` to a standalone repository + +## Goal + +Move the `torrust-clock` crate out of the `torrust-tracker` workspace into its own +standalone repository so that it can be maintained, versioned, and published independently +of the tracker. + +## Background + +The `torrust-clock` package provides a mockable time abstraction for deterministic testing. +It contains no tracker-specific logic, making it a general-purpose utility reusable by any +Rust project (e.g., `torrust-index` already contains a local copy of equivalent clock +code). Keeping it inside the tracker workspace couples its release cycle to the tracker's +and limits its visibility to potential consumers. + +After the preceding subissues are complete (`torrust-tracker-clock` renamed to +`torrust-clock` and `DurationSinceUnixEpoch` moved from `torrust-tracker-primitives` to +`torrust-clock`), the crate has **zero workspace-path dependencies** — all its runtime +deps (`chrono`, `tracing`) are published crates. Extraction is therefore unblocked. + +**Prerequisites**: + +1. Clock rename subissue + ([1669-06-rename-torrust-tracker-clock-to-torrust-clock.md](1669-06-rename-torrust-tracker-clock-to-torrust-clock.md)) + must be complete — in particular T8 (publish `torrust-clock` on crates.io). +2. `DurationSinceUnixEpoch` move subissue + ([1669-02-move-duration-since-unix-epoch-to-torrust-clock.md](1669-02-move-duration-since-unix-epoch-to-torrust-clock.md)) + must be complete — in particular T4 (`torrust-tracker-primitives` dep removed from + `packages/clock/Cargo.toml`). + +This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) +(Overhaul: Packages). + +## Scope + +### In Scope + +- Create a new standalone repository `torrust/torrust-clock` in the Torrust GitHub + organization. +- Move `packages/clock/` to the new repository, preserving git history (using + `git filter-repo`). +- Verify the standalone repository builds and tests pass independently. +- Set up CI in the new repository (mirror the relevant CI workflows from the tracker repo). +- Update all 11 workspace consumers (root `Cargo.toml` + 10 packages) to reference + `torrust-clock` as a crates.io version dependency instead of a path dependency. +- Remove `packages/clock` from the workspace `members` list in root `Cargo.toml`. +- Delete the `packages/clock/` directory from the tracker repository. +- Update prose references in `packages/AGENTS.md`, `AGENTS.md`, and `docs/packages.md` + (move `torrust-clock` to the "Extracted" section). + +### Out of Scope + +- Changes to the crate's API or behaviour. +- Yanking the old crates.io name `torrust-tracker-clock` (that is handled by the rename + subissue T11, after `torrust-index` migration). + +### Workspace consumers to migrate in T5 + +The following 11 files must have their `torrust-clock` dep changed from a path dep to a +crates.io version dep: + +- `Cargo.toml` (root — workspace dep registration) +- `packages/axum-health-check-api-server/Cargo.toml` +- `packages/axum-http-tracker-server/Cargo.toml` +- `packages/axum-rest-tracker-api-server/Cargo.toml` +- `packages/http-protocol/Cargo.toml` +- `packages/http-tracker-core/Cargo.toml` +- `packages/swarm-coordination-registry/Cargo.toml` +- `packages/tracker-core/Cargo.toml` +- `packages/torrent-repository-benchmarking/Cargo.toml` +- `packages/udp-tracker-core/Cargo.toml` +- `packages/udp-tracker-server/Cargo.toml` + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | +| T1 | BLOCKED | Confirm clock rename is complete (T8 of rename spec: `torrust-clock` published on crates.io) | `packages/clock/Cargo.toml` has `name = "torrust-clock"` | +| T2 | BLOCKED | Confirm `DurationSinceUnixEpoch` move is complete (T4 of move spec: primitives dep removed from clock) | `packages/clock/Cargo.toml` does not list `torrust-tracker-primitives` | +| T3 | TODO | Create standalone repository `torrust/torrust-clock` | Empty repo with license and basic README | +| T4 | TODO | Move `packages/clock/` to the new repository, preserving git history (`git filter-repo`) | New repo contains full history for `packages/clock/` | +| T5 | TODO | Verify standalone repository: `cargo build` and `cargo test` pass with no path deps | Clean build in the new repo; Cargo.toml has only external (non-path) deps | +| T6 | TODO | Set up CI in the new repository | Copy/adapt relevant GitHub Actions workflows; CI passes | +| T7 | TODO | Update all 11 workspace consumers (see list above): path dep → crates.io version dep | `torrust-clock = "X.Y.Z"` (or workspace dep) in each Cargo.toml | +| T8 | TODO | Remove `packages/clock` entry from workspace `members` in root `Cargo.toml` | `packages/clock` absent from `[workspace]` members list | +| T9 | TODO | Delete `packages/clock/` directory from the tracker repository | Directory removed; `git status` shows deletions | +| T10 | TODO | Update `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md` | `torrust-clock` moved to an "Extracted packages" section | +| T11 | TODO | Run `cargo build --workspace` and `cargo test --workspace` | Clean build and all tests pass | +| T12 | TODO | Run `linter all` | Exit code `0` | +| T13 | TODO | Update EPIC #1669 tables | Package inventory and desired state tables updated; subissue row set to `DONE` | + +## Progress Tracking + +### Workflow Checkpoints + +- [ ] Spec drafted in `docs/issues/drafts/` +- [ ] Spec reviewed and approved by user/maintainer +- [ ] Clock rename subissue complete (prerequisite 1) +- [ ] `DurationSinceUnixEpoch` move subissue complete (prerequisite 2) +- [ ] GitHub issue created and issue number added to this spec +- [ ] Spec moved to `docs/issues/open/` with issue number prefix +- [ ] Standalone repository created +- [ ] Source moved with history preserved +- [ ] CI set up and passing in new repository +- [ ] Workspace consumers migrated to crates.io version dep +- [ ] `packages/clock/` removed from tracker workspace +- [ ] Automatic verification completed (`linter all`, `cargo test --workspace`) +- [ ] Manual verification scenarios executed and recorded +- [ ] Acceptance criteria reviewed after implementation and updated with evidence +- [ ] EPIC #1669 Active Subissues table updated to `DONE` +- [ ] Issue closed and spec moved to `docs/issues/closed/` + +### Progress Log + +- 2026-05-15 12:00 UTC - josecelano - Spec drafted as subissue of EPIC #1669; follows + clock rename and DurationSinceUnixEpoch move subissues + +## Acceptance Criteria + +- [ ] A standalone repository `torrust/torrust-clock` exists on GitHub. +- [ ] The repository contains the full git history for `packages/clock/`. +- [ ] CI in the new repository passes. +- [ ] No `Cargo.toml` in the tracker workspace references `torrust-clock` with a path dep. +- [ ] `packages/clock` is absent from the `[workspace]` members list in root `Cargo.toml`. +- [ ] The `packages/clock/` directory no longer exists in the tracker repository. +- [ ] `cargo build --workspace` in the tracker repository succeeds with zero errors. +- [ ] `cargo test --workspace` in the tracker repository passes with zero failures. +- [ ] `linter all` exits with code `0`. +- [ ] `packages/AGENTS.md`, `AGENTS.md`, and `docs/packages.md` reflect the extraction. + +## Verification Plan + +### Automatic Checks + +- `cargo build --workspace` +- `cargo test --doc --workspace` +- `cargo test --tests --workspace --all-targets --all-features` +- `linter all` +- `cargo machete` (no unused dependencies) + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command / Steps | Expected Result | Status | Evidence | +| --- | ------------------------------------------------------- | ----------------------------------------------------- | --------------------------- | ------ | -------- | +| M1 | No path dep on `torrust-clock` remains in the workspace | `grep -r "path.*packages/clock" . --include="*.toml"` | Zero matches | TODO | | +| M2 | `packages/clock/` directory is gone | `ls packages/clock` | `No such file or directory` | TODO | | +| M3 | Standalone repo builds and tests pass independently | In new repo: `cargo build && cargo test --workspace` | Clean build; all tests pass | TODO | | +| M4 | `torrust-clock` CI green in new repository | Check GitHub Actions on `torrust/torrust-clock` | All workflows green | TODO | | diff --git a/docs/issues/drafts/1669-10-extract-torrust-metrics-to-standalone-repo.md b/docs/issues/drafts/1669-10-extract-torrust-metrics-to-standalone-repo.md new file mode 100644 index 000000000..1d4f5f95a --- /dev/null +++ b/docs/issues/drafts/1669-10-extract-torrust-metrics-to-standalone-repo.md @@ -0,0 +1,166 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p3 +github-issue: null +spec-path: docs/issues/drafts/1669-10-extract-torrust-metrics-to-standalone-repo.md +branch: null +related-pr: null +last-updated-utc: 2026-05-15 12:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - packages/metrics/Cargo.toml + - Cargo.toml + - docs/packages.md + - AGENTS.md + - docs/issues/open/1669-overhaul-packages/EPIC.md + - docs/issues/drafts/1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md +--- + + + +# Issue #[To be assigned] - Extract `torrust-metrics` to a standalone repository + +## Goal + +Move the `torrust-metrics` crate out of the `torrust-tracker` workspace into its own +standalone repository so that it can be maintained, versioned, and published independently +of the tracker. + +## Background + +The `torrust-metrics` package provides Prometheus metrics integration types for the +tracker. Its only workspace-path dependency is `torrust-tracker-primitives`, which is +already published on crates.io. After the `torrust-tracker-metrics` → `torrust-metrics` +rename (and the associated first publish of the crate), extraction is unblocked. + +The rename subissue +([1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md](1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md)) +must be complete — including publishing `torrust-metrics` on crates.io — before this +subissue begins. + +**Prerequisite**: Metrics rename subissue +([1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md](1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md)) +complete (all tasks through publishing on crates.io). + +This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) +(Overhaul: Packages). + +## Scope + +### In Scope + +- Create a new standalone repository `torrust/torrust-metrics` in the Torrust GitHub + organization. +- Move `packages/metrics/` to the new repository, preserving git history (using + `git filter-repo`). +- Verify the standalone repository builds and tests pass independently. +- Set up CI in the new repository (mirror the relevant CI workflows from the tracker repo). +- Update all 7 workspace consumers to reference `torrust-metrics` as a crates.io version + dependency instead of a path dependency (see list below). +- Update the root `Cargo.toml` workspace dep registration for `torrust-metrics`. +- Remove `packages/metrics` from the workspace `members` list in root `Cargo.toml`. +- Delete the `packages/metrics/` directory from the tracker repository. +- Update prose references in `packages/AGENTS.md`, `AGENTS.md`, and `docs/packages.md` + (move `torrust-metrics` to the "Extracted" section). + +### Out of Scope + +- Changes to the crate's API or behaviour. +- Updating downstream repositories outside the Torrust organization. + +### Workspace consumers to migrate in T5 + +The following 7 packages must have their `torrust-metrics` dep changed from a path dep to +a crates.io version dep (root `Cargo.toml` is handled in T8): + +- `packages/swarm-coordination-registry/Cargo.toml` +- `packages/rest-tracker-api-core/Cargo.toml` +- `packages/udp-tracker-core/Cargo.toml` +- `packages/axum-rest-tracker-api-server/Cargo.toml` +- `packages/udp-tracker-server/Cargo.toml` +- `packages/tracker-core/Cargo.toml` +- `packages/http-tracker-core/Cargo.toml` + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| T1 | BLOCKED | Confirm metrics rename is complete and `torrust-metrics` is published on crates.io | `packages/metrics/Cargo.toml` has `name = "torrust-metrics"`; crates.io page exists | +| T2 | TODO | Create standalone repository `torrust/torrust-metrics` | Empty repo with license and basic README | +| T3 | TODO | Move `packages/metrics/` to the new repository, preserving git history (`git filter-repo`) | New repo contains full history for `packages/metrics/` | +| T4 | TODO | In the new repo: update `torrust-tracker-primitives` dep to use crates.io version (not path) | `torrust-tracker-primitives = "X.Y.Z"` (published version); no path deps in Cargo.toml | +| T5 | TODO | Verify standalone repository: `cargo build` and `cargo test` pass with no path deps | Clean build in the new repo | +| T6 | TODO | Set up CI in the new repository | Copy/adapt relevant GitHub Actions workflows; CI passes | +| T7 | TODO | Update all 7 workspace consumers (see list above): path dep → crates.io version dep | `torrust-metrics = "X.Y.Z"` (or workspace dep) in each Cargo.toml | +| T8 | TODO | Update root `Cargo.toml` workspace dep registration for `torrust-metrics` to crates.io version | No `path = "packages/metrics"` in root `[workspace.dependencies]` | +| T9 | TODO | Remove `packages/metrics` entry from workspace `members` in root `Cargo.toml` | `packages/metrics` absent from `[workspace]` members list | +| T10 | TODO | Delete `packages/metrics/` directory from the tracker repository | Directory removed; `git status` shows deletions | +| T11 | TODO | Update `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md` | `torrust-metrics` moved to an "Extracted packages" section | +| T12 | TODO | Run `cargo build --workspace` and `cargo test --workspace` | Clean build and all tests pass | +| T13 | TODO | Run `linter all` | Exit code `0` | +| T14 | TODO | Update EPIC #1669 tables | Package inventory and desired state tables updated; subissue row set to `DONE` | + +## Progress Tracking + +### Workflow Checkpoints + +- [ ] Spec drafted in `docs/issues/drafts/` +- [ ] Spec reviewed and approved by user/maintainer +- [ ] Metrics rename subissue complete (prerequisite) +- [ ] GitHub issue created and issue number added to this spec +- [ ] Spec moved to `docs/issues/open/` with issue number prefix +- [ ] Standalone repository created +- [ ] Source moved with history preserved +- [ ] CI set up and passing in new repository +- [ ] Workspace consumers migrated to crates.io version dep +- [ ] `packages/metrics/` removed from tracker workspace +- [ ] Automatic verification completed (`linter all`, `cargo test --workspace`) +- [ ] Manual verification scenarios executed and recorded +- [ ] Acceptance criteria reviewed after implementation and updated with evidence +- [ ] EPIC #1669 Active Subissues table updated to `DONE` +- [ ] Issue closed and spec moved to `docs/issues/closed/` + +### Progress Log + +- 2026-05-15 12:00 UTC - josecelano - Spec drafted as subissue of EPIC #1669; follows + metrics rename subissue + +## Acceptance Criteria + +- [ ] A standalone repository `torrust/torrust-metrics` exists on GitHub. +- [ ] The repository contains the full git history for `packages/metrics/`. +- [ ] CI in the new repository passes. +- [ ] No `Cargo.toml` in the tracker workspace references `torrust-metrics` with a path dep. +- [ ] `packages/metrics` is absent from the `[workspace]` members list in root `Cargo.toml`. +- [ ] The `packages/metrics/` directory no longer exists in the tracker repository. +- [ ] `cargo build --workspace` in the tracker repository succeeds with zero errors. +- [ ] `cargo test --workspace` in the tracker repository passes with zero failures. +- [ ] `linter all` exits with code `0`. +- [ ] `packages/AGENTS.md`, `AGENTS.md`, and `docs/packages.md` reflect the extraction. + +## Verification Plan + +### Automatic Checks + +- `cargo build --workspace` +- `cargo test --doc --workspace` +- `cargo test --tests --workspace --all-targets --all-features` +- `linter all` +- `cargo machete` (no unused dependencies) + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command / Steps | Expected Result | Status | Evidence | +| --- | --------------------------------------------------------- | ------------------------------------------------------- | --------------------------- | ------ | -------- | +| M1 | No path dep on `torrust-metrics` remains in the workspace | `grep -r "path.*packages/metrics" . --include="*.toml"` | Zero matches | TODO | | +| M2 | `packages/metrics/` directory is gone | `ls packages/metrics` | `No such file or directory` | TODO | | +| M3 | Standalone repo builds and tests pass independently | In new repo: `cargo build && cargo test --workspace` | Clean build; all tests pass | TODO | | +| M4 | `torrust-metrics` CI green in new repository | Check GitHub Actions on `torrust/torrust-metrics` | All workflows green | TODO | | diff --git a/docs/issues/drafts/1669-11-extract-torrust-tracker-client-to-standalone-repo.md b/docs/issues/drafts/1669-11-extract-torrust-tracker-client-to-standalone-repo.md new file mode 100644 index 000000000..6fb8c7931 --- /dev/null +++ b/docs/issues/drafts/1669-11-extract-torrust-tracker-client-to-standalone-repo.md @@ -0,0 +1,162 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p2 +github-issue: null +spec-path: docs/issues/drafts/1669-11-extract-torrust-tracker-client-to-standalone-repo.md +branch: null +related-pr: null +last-updated-utc: 2026-05-15 12:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - console/tracker-client/Cargo.toml + - Cargo.toml + - AGENTS.md + - docs/packages.md + - docs/issues/open/1669-overhaul-packages/EPIC.md +--- + + + +# Issue #[To be assigned] - Extract `torrust-tracker-client` to standalone repository + +## Goal + +Extract the `torrust-tracker-client` CLI tool from the tracker workspace into its own +standalone repository so that it can evolve independently, be installed without the full +tracker source tree, and follow its own versioning and release cadence. + +## Background + +The `torrust-tracker-client` package (folder `console/tracker-client`) is a collection of +console clients for making requests to BitTorrent trackers. Key facts: + +- **CLI tool, not a library**: its primary artefact is a binary. It is not consumed as a + library dependency by other crates in the workspace. +- **Separate license**: LGPL-3.0, unlike the tracker's AGPL-3.0-only workspace license. + Having a differently licensed binary in the same workspace creates a mixed-license surface + that is harder to communicate to contributors and downstream users. +- **Independent evolution**: the CLI tool's feature set and release cadence are driven by + user interaction needs, not by tracker server internals. Tying its version to the tracker + workspace version is unnecessary coupling. +- **Extraction was always the intent**: the package README states _"We're currently + extracting and refining common functionality from the Torrust Tracker"_, confirming that + moving it to its own repository is the designed direction. + +The extraction is currently **blocked** by two unpublished workspace dependencies: + +| Dependency | Current status | +| --------------------------------- | -------------------------- | +| `bittorrent-udp-tracker-protocol` | Not published on crates.io | +| `bittorrent-tracker-client` | Not published on crates.io | + +The third workspace dependency (`torrust-tracker-configuration`) is already published ✅. +Do not start T3 or later tasks until T1 is satisfied. + +This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) +(Overhaul: Packages). + +## Scope + +### In Scope + +- Create (or confirm) the target standalone repository for the CLI tool. +- Move the `console/tracker-client/` source to the new repository, preserving git history. +- Update the crate's `Cargo.toml` in the new repo: replace workspace path dependencies with + published crates.io version dependencies once the blocking crates are published. +- Set up CI in the new repository (build, test, lint, publish/release workflow). +- Remove `console/tracker-client/` from the tracker workspace: + - Remove from the `members` list in the root `Cargo.toml`. + - Remove the workspace dependency entry from the root `Cargo.toml`. + - Delete the `console/tracker-client/` directory from the tracker repo. +- Update `packages/AGENTS.md`, `AGENTS.md`, and `docs/packages.md`. + +### Out of Scope + +- Changes to the CLI tool's features or behaviour. +- Publishing `bittorrent-udp-tracker-protocol` or `bittorrent-tracker-client` on crates.io + — those are separate subissues. +- Renaming the crate: `torrust-tracker-client` is an appropriate name and is kept. + +### Prerequisites + +This issue is **blocked** until the following crates are published on crates.io: + +1. `bittorrent-udp-tracker-protocol` +2. `bittorrent-tracker-client` + +Do not begin T3 or later until both are available. + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| T1 | BLOCKED | Confirm `bittorrent-udp-tracker-protocol` and `bittorrent-tracker-client` are published | Prerequisite; unblocks T3 and all later tasks | +| T2 | TODO | Create (or confirm) the target standalone repository | Repo exists with README and LICENSE committed | +| T3 | TODO | Move crate source to the new repository, preserving git history | Use `git filter-repo` or subtree split; history preserved under `console/tracker-client/` | +| T4 | TODO | Update `Cargo.toml` in the new repo: replace path deps with published crates.io version deps | `bittorrent-udp-tracker-protocol = "X.Y.Z"`, `bittorrent-tracker-client = "X.Y.Z"` | +| T5 | TODO | Set up CI in the new repository (build, test, lint, release workflow) | CI green on first push | +| T6 | TODO | Remove `console/tracker-client/` from workspace members and workspace dep in root `Cargo.toml` | `cargo build --workspace` succeeds without the local crate | +| T7 | TODO | Delete `console/tracker-client/` directory from the tracker repo | Directory gone; workspace still builds | +| T8 | TODO | Update `packages/AGENTS.md`, `AGENTS.md`, `docs/packages.md`, and any README references | No stale references to the console client remain in the tracker docs | +| T9 | TODO | Run `cargo build --workspace`, `cargo test --workspace`, `linter all` | All green | +| T10 | TODO | Update EPIC #1669 `Package Inventory` and `Desired Package State` tables | Mark `torrust-tracker-client` as extracted; remove from workspace member list | + +## Progress Tracking + +### Workflow Checkpoints + +- [ ] Spec drafted in `docs/issues/drafts/` +- [ ] Spec reviewed and approved by user/maintainer +- [ ] Blocking dependencies (`bittorrent-udp-tracker-protocol`, `bittorrent-tracker-client`) published on crates.io +- [ ] GitHub issue created and issue number added to this spec +- [ ] Spec moved to `docs/issues/open/` with issue number prefix +- [ ] Implementation completed +- [ ] Automatic verification completed (`linter all`, `cargo test --workspace`) +- [ ] Manual verification scenarios executed and recorded +- [ ] Acceptance criteria reviewed after implementation and updated with evidence +- [ ] EPIC #1669 Active Subissues table updated to `DONE` +- [ ] Issue closed and spec moved to `docs/issues/closed/` + +### Progress Log + +- 2026-05-15 12:00 UTC - josecelano - Spec drafted as subissue of EPIC #1669 + +## Acceptance Criteria + +- [ ] `console/tracker-client/` directory no longer exists in the tracker workspace. +- [ ] Root `Cargo.toml` does not list `console/tracker-client` as a workspace member. +- [ ] No `Cargo.toml` in the tracker workspace references `torrust-tracker-client` as a path dep. +- [ ] `cargo build --workspace` succeeds with zero errors after the removal. +- [ ] `cargo test --workspace` passes with zero failures after the removal. +- [ ] `linter all` exits with code `0`. +- [ ] The new repository has passing CI and a clean `cargo build`. +- [ ] `packages/AGENTS.md`, `AGENTS.md`, and `docs/packages.md` no longer list + `torrust-tracker-client` as a workspace package. +- [ ] EPIC #1669 `Package Inventory` and `Desired Package State` tables are updated to + reflect the extraction. + +## Verification Plan + +### Automatic Checks + +- `cargo build --workspace` +- `cargo test --doc --workspace` +- `cargo test --tests --workspace --all-targets --all-features` +- `linter all` +- `cargo machete` (no unused dependencies) + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command / Steps | Expected Result | Status | Evidence | +| --- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------ | -------- | +| M1 | No stale workspace reference to old crate | `grep -r "torrust-tracker-client\|console/tracker-client" . --include="*.toml" --include="*.rs" --include="*.md"` | Zero matches in tracker repo | TODO | | +| M2 | New repository CI passes | Check CI status on the new repository's default branch | All checks pass | TODO | | +| M3 | Crate builds from new repository | Clone new repo; `cargo build` | Clean build | TODO | | diff --git a/docs/issues/open/1669-overhaul-packages/EPIC.md b/docs/issues/open/1669-overhaul-packages/EPIC.md new file mode 100644 index 000000000..ab9fd31ba --- /dev/null +++ b/docs/issues/open/1669-overhaul-packages/EPIC.md @@ -0,0 +1,421 @@ +--- +doc-type: epic +issue-type: task +status: planned +priority: p1 +github-issue: 1669 +spec-path: docs/issues/open/1669-overhaul-packages/EPIC.md +epic-owner: josecelano +last-updated-utc: 2026-05-15 12:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - docs/packages.md + - docs/media/packages/ + - AGENTS.md +--- + + + +# EPIC #1669 - Overhaul: Packages + +## Goal + +Progressively simplify and clarify the Cargo workspace package structure through a series +of small, focused improvements. The starting point is identifying and extracting packages +that are clearly generic and reusable outside the tracker — doing so reduces complexity for +the remaining packages and makes it easier to see what to do next. This EPIC is intentionally +open-ended: it is re-evaluated whenever packages are added, split, or grown substantially. + +## Why This Is Needed + +The package structure grew organically over multiple refactoring cycles. As a result, several +concerns are mixed together: + +- **Documentation quality is uneven**: package READMEs vary significantly in depth and + accuracy; some are stubs. +- **Boundary clarity is uncertain**: it is not always obvious whether packages are + appropriately cohesive, or whether coupling is intentional. +- **Some packages are clearly generic and reusable**: the `bittorrent-*` protocol crates, + `bencode`, and several utility crates have no tracker-specific logic and would be more + useful to the wider community as standalone crates in their own repositories. Keeping them + here adds noise to the workspace and makes their independent evolution harder. +- **Versioning policy is implicit**: all packages share the workspace version; packages + extracted to separate repos will need their own release cadence. +- **Only 6 of 26 packages are published on crates.io**: all unpublished (confirmed May 2026), + in particular every `bittorrent-*` crate. Publishing them in-workspace conflicts with + giving them independent versions; extraction resolves this tension. + +The approach is not all-or-nothing. Each small extraction or structural improvement is a +self-contained win. Re-evaluation happens naturally after each change, or when the package +landscape shifts (new packages, splits, significant growth). + +## Package Inventory + +The workspace currently contains **26 packages** across three crate-name prefixes. +"Published" means a crate with that name exists on crates.io (verified May 2026). + +### `torrust-` prefix (non-`torrust-tracker-`) + +| Published on crates.io | Crate Name | Folder | +| ---------------------- | -------------------------------------- | ------------------------------ | +| No | `torrust-axum-health-check-api-server` | `axum-health-check-api-server` | +| No | `torrust-axum-http-tracker-server` | `axum-http-tracker-server` | +| No | `torrust-axum-rest-tracker-api-server` | `axum-rest-tracker-api-server` | +| No | `torrust-axum-server` | `axum-server` | +| No | `torrust-rest-tracker-api-client` | `rest-tracker-api-client` | +| No | `torrust-rest-tracker-api-core` | `rest-tracker-api-core` | +| No | `torrust-server-lib` | `server-lib` | +| No | `torrust-udp-tracker-server` | `udp-tracker-server` | + +### `torrust-tracker-` prefix + +| Published on crates.io | Crate Name | Folder | +| ---------------------- | ------------------------------------------------- | --------------------------------- | +| Yes | `torrust-tracker-clock` | `clock` | +| Yes | `torrust-tracker-configuration` | `configuration` | +| No | `torrust-tracker-events` | `events` | +| Yes | `torrust-tracker-located-error` | `located-error` | +| No | `torrust-tracker-metrics` | `metrics` | +| Yes | `torrust-tracker-primitives` | `primitives` | +| No | `torrust-tracker-swarm-coordination-registry` | `swarm-coordination-registry` | +| Yes | `torrust-tracker-test-helpers` | `test-helpers` | +| No | `torrust-tracker-torrent-repository-benchmarking` | `torrent-repository-benchmarking` | +| No | `torrust-tracker-client` | `console/tracker-client` | +| Yes | `torrust-tracker-contrib-bencode` | `contrib/bencode` | + +### `bittorrent-` prefix + +| Published on crates.io | Crate Name | Folder | +| ---------------------- | ---------------------------------- | ------------------- | +| No | `bittorrent-http-tracker-protocol` | `http-protocol` | +| No | `bittorrent-http-tracker-core` | `http-tracker-core` | +| No | `bittorrent-peer-id` | `peer-id` | +| No | `bittorrent-tracker-client` | `tracker-client` | +| No | `bittorrent-tracker-core` | `tracker-core` | +| No | `bittorrent-udp-tracker-protocol` | `udp-protocol` | +| No | `bittorrent-udp-tracker-core` | `udp-tracker-core` | + +**Observation**: only 6 of 26 packages are currently published on crates.io, all of which +carry the `torrust-tracker-` prefix. Every `bittorrent-` and `torrust-axum-` crate is +unpublished. This confirms issue #1659's note that "many new crates have not been published +yet after we refactored the packages." + +## Desired Package State + +This section captures the target package structure as decisions are made. It is updated +progressively — it does **not** represent a complete end-state plan, only the changes that +have been agreed so far. + +Each table shows the **final crate name** in its **correct prefix group** after all planned +changes. Where a package moves from one prefix group to another, it appears only in the +destination group with a "Renamed from …" note. + +### `torrust-` prefix (non-`torrust-tracker-`) + +| Published on crates.io | Crate Name | Folder | Change | +| ---------------------- | ----------------------- | --------------- | -------------------------------------------- | +| Yes | `torrust-clock` | `clock` | Renamed from `torrust-tracker-clock` | +| Yes | `torrust-located-error` | `located-error` | Renamed from `torrust-tracker-located-error` | +| No | `torrust-metrics` | `metrics` | Renamed from `torrust-tracker-metrics` | + +### `torrust-tracker-` prefix + +| Published on crates.io | Crate Name | Folder | Change | +| ---------------------- | ------------------------------------------------- | --------------------------------- | --------------------------------------------------- | +| No | `torrust-tracker-axum-health-check-api-server` | `axum-health-check-api-server` | Renamed from `torrust-axum-health-check-api-server` | +| No | `torrust-tracker-axum-http-server` | `axum-http-tracker-server` | Renamed from `torrust-axum-http-tracker-server` | +| No | `torrust-tracker-axum-rest-api-server` | `axum-rest-tracker-api-server` | Renamed from `torrust-axum-rest-tracker-api-server` | +| No | `torrust-tracker-axum-server` | `axum-server` | Renamed from `torrust-axum-server` | +| Yes | `torrust-tracker-configuration` | `configuration` | — | +| No | `torrust-tracker-events` | `events` | — | +| Yes | `torrust-tracker-primitives` | `primitives` | — | +| No | `torrust-tracker-rest-api-client` | `rest-tracker-api-client` | Renamed from `torrust-rest-tracker-api-client` | +| No | `torrust-tracker-rest-api-core` | `rest-tracker-api-core` | Renamed from `torrust-rest-tracker-api-core` | +| No | `torrust-tracker-swarm-coordination-registry` | `swarm-coordination-registry` | — | +| Yes | `torrust-tracker-test-helpers` | `test-helpers` | — | +| No | `torrust-tracker-torrent-repository-benchmarking` | `torrent-repository-benchmarking` | — | +| No | `torrust-tracker-udp-server` | `udp-tracker-server` | Renamed from `torrust-udp-tracker-server` | + +### `bittorrent-` prefix + +| Published on crates.io | Crate Name | Folder | Change | +| ---------------------- | ---------------------------------- | ------------------- | ------ | +| No | `bittorrent-http-tracker-core` | `http-tracker-core` | — | +| No | `bittorrent-http-tracker-protocol` | `http-protocol` | — | +| No | `bittorrent-peer-id` | `peer-id` | — | +| No | `bittorrent-tracker-client` | `tracker-client` | — | +| No | `bittorrent-tracker-core` | `tracker-core` | — | +| No | `bittorrent-udp-tracker-core` | `udp-tracker-core` | — | +| No | `bittorrent-udp-tracker-protocol` | `udp-protocol` | — | + +### Extracted from workspace + +| Final crate name | Extracted from | Notes | +| ------------------------ | --------------------------------- | -------------------------------------------------------------------- | +| `torrust-bencode` | `torrust-tracker-contrib-bencode` | Standalone repo; Apache-2.0; one remaining consumer in tracker | +| `torrust-tracker-client` | `torrust-tracker-client` | Standalone CLI tool; LGPL-3.0; blocked by `bittorrent-*` publication | + +## Scope + +### In Scope + +- Establish a baseline: review package READMEs, produce a dependency graph, identify coupling + issues. +- Identify packages that are clearly generic and independently reusable outside the tracker. +- For each such candidate, create a dedicated subissue and extract it to its own repository + when the decision is made. +- Decide and document the versioning strategy for packages that remain in this workspace + after extractions. +- Update `docs/packages.md` and `AGENTS.md` Package Catalog after each structural change. +- Re-evaluate the workspace after each extraction to find the next improvement. + +### Out of Scope + +- All-at-once reorganization of all packages. +- Forced extraction of packages whose independence is unclear or disputed. +- Adding new packages or implementing new tracker features. +- Persistence layer redesign (tracked under + [#1525](https://github.com/torrust/torrust-tracker/issues/1525)). +- MSRV changes (tracked under + [#1787](https://github.com/torrust/torrust-tracker/issues/1787)). + +## Active Subissues + +### Subissue priority rules + +When no hard dependency forces a different order, implement subissues according to these +priority levels (lower number = implement first). Hard dependencies always override the +rule priority. + +| Rule | Priority | Description | +| ---- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| M | 1 | **Move things between packages** — no crates.io impact; only workspace consumers must update imports. | +| U | 2 | **Rename unpublished packages** — crate is not on crates.io; only workspace consumers affected; no external migration window needed. | +| P | 3 | **Rename published packages** — crate is on crates.io; old and new names coexist for a migration window; external consumers must eventually migrate. | +| E | 4 | **Extract packages to standalone repositories** — highest effort; requires CI setup, history preservation, and migrating all workspace consumers from path dep to crates.io version dep. | + +### Quick list + +Status: TODO unless noted. `SI-XX` = recommended implementation sequence number. + +- [ ] SI-01 — Establish baseline: dependency graph + README audit _(analysis; no blockers; informs all other subissues)_ +- [ ] SI-02 — Move `DurationSinceUnixEpoch` from `torrust-tracker-primitives` to `torrust-clock` _(Rule M; no hard blockers)_ +- [ ] SI-03 — Move `DEFAULT_TIMEOUT` from `torrust-tracker-configuration` to `torrust-tracker-clock` _(Rule M; no blockers)_ +- [ ] SI-04 — Align `torrust-` prefix: rename 7 tracker-specific packages to `torrust-tracker-` _(Rule U; no blockers)_ +- [ ] SI-05 — Rename `torrust-tracker-metrics` to `torrust-metrics` _(Rule U; no blockers)_ +- [ ] SI-06 — Rename `torrust-tracker-clock` to `torrust-clock` _(Rule P; requires SI-03)_ +- [ ] SI-07 — Rename `torrust-tracker-located-error` to `torrust-located-error` _(Rule P; no blockers)_ +- [ ] SI-08 — Extract and rename `torrust-tracker-contrib-bencode` to `torrust-bencode` _(Rule E; no blockers within this EPIC)_ +- [ ] SI-09 — Extract `torrust-clock` to standalone repository _(Rule E; requires SI-02 + SI-06)_ +- [ ] SI-10 — Extract `torrust-metrics` to standalone repository _(Rule E; requires SI-05)_ +- [ ] SI-11 — Extract `torrust-tracker-client` to standalone repository _(Rule E; blocked by `bittorrent-*` publication — external to this EPIC)_ + +Details: + +| SI | Issue | Local Spec | Status | Notes | +| ----- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------- | +| SI-01 | #TBD — Establish baseline: dependency graph + README audit | `docs/issues/drafts/packages-baseline-analysis.md` (not yet created) | TODO | No blockers; informs extraction decisions | +| SI-02 | #TBD — Move `DurationSinceUnixEpoch` from `torrust-tracker-primitives` to `torrust-clock` | [docs/issues/drafts/1669-02-move-duration-since-unix-epoch-to-torrust-clock.md](../../drafts/1669-02-move-duration-since-unix-epoch-to-torrust-clock.md) | TODO | Rule M; no hard blockers; prerequisite for SI-09 | +| SI-03 | #TBD — Move `DEFAULT_TIMEOUT` from `torrust-tracker-configuration` to `torrust-tracker-clock` | [docs/issues/drafts/1669-03-move-default-timeout-from-configuration-to-clock.md](../../drafts/1669-03-move-default-timeout-from-configuration-to-clock.md) | TODO | Rule M; no blockers; prerequisite for SI-06 (clock rename) | +| SI-04 | #TBD — Align `torrust-` prefix: rename 7 tracker-specific packages to `torrust-tracker-` | [docs/issues/drafts/1669-04-align-torrust-prefix-rename-tracker-specific-packages.md](../../drafts/1669-04-align-torrust-prefix-rename-tracker-specific-packages.md) | TODO | Rule U; none of the 7 are published; pure workspace rename; no blockers | +| SI-05 | #TBD — Rename `torrust-tracker-metrics` to `torrust-metrics` | [docs/issues/drafts/1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md](../../drafts/1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md) | TODO | Rule U; not yet published; no blockers; prerequisite for SI-10 | +| SI-06 | #TBD — Rename `torrust-tracker-clock` to `torrust-clock` | [docs/issues/drafts/1669-06-rename-torrust-tracker-clock-to-torrust-clock.md](../../drafts/1669-06-rename-torrust-tracker-clock-to-torrust-clock.md) | TODO | Rule P; published on crates.io; requires SI-03; prerequisite for SI-09 | +| SI-07 | #TBD — Rename `torrust-tracker-located-error` to `torrust-located-error` | [docs/issues/drafts/1669-07-rename-torrust-tracker-located-error-to-torrust-located-error.md](../../drafts/1669-07-rename-torrust-tracker-located-error-to-torrust-located-error.md) | TODO | Rule P; published on crates.io; no blockers | +| SI-08 | #TBD — Extract and rename `torrust-tracker-contrib-bencode` to `torrust-bencode` | [docs/issues/drafts/1669-08-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md](../../drafts/1669-08-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md) | TODO | Rule E; no workspace-dep blockers; Apache-2.0; one internal consumer | +| SI-09 | #TBD — Extract `torrust-clock` to standalone repository | [docs/issues/drafts/1669-09-extract-torrust-clock-to-standalone-repo.md](../../drafts/1669-09-extract-torrust-clock-to-standalone-repo.md) | TODO | Rule E; requires SI-02 + SI-06; 11 workspace consumers to migrate | +| SI-10 | #TBD — Extract `torrust-metrics` to standalone repository | [docs/issues/drafts/1669-10-extract-torrust-metrics-to-standalone-repo.md](../../drafts/1669-10-extract-torrust-metrics-to-standalone-repo.md) | TODO | Rule E; requires SI-05; 7 workspace consumers to migrate | +| SI-11 | #TBD — Extract `torrust-tracker-client` to standalone repository | [docs/issues/drafts/1669-11-extract-torrust-tracker-client-to-standalone-repo.md](../../drafts/1669-11-extract-torrust-tracker-client-to-standalone-repo.md) | TODO | Rule E; blocked by `bittorrent-udp-tracker-protocol` publication (external to this EPIC) | + +> New subissues are created as analysis reveals the next improvement. The EPIC is never +> fully planned up front. + +## Delivery Strategy + +This EPIC uses iterative cycles rather than fixed phases. Each cycle is: + +1. **Analyse** — look at the current workspace state (coupling, READMEs, usage patterns). +2. **Identify** — find the smallest, clearest improvement (typically: one package that is + obviously independent and reusable, or one documentation gap). +3. **Act** — open a focused subissue, implement it, merge it. +4. **Re-evaluate** — with the change landed, repeat from step 1. + +The EPIC is re-triggered (a new analysis round starts) whenever: + +- A new package is added to the workspace. +- An existing package is split into two. +- A package grows substantially in scope or dependency count. +- A downstream project asks to consume a workspace package independently. + +### First cycle (current) + +- Outcome: Baseline established — dependency graph committed, READMEs audited, initial + extraction candidates identified and documented. +- Exit criteria: Baseline analysis subissue merged; at least one extraction candidate has + a scoped subissue ready. + +### Subsequent cycles + +Each subsequent cycle produces one or more of: + +- An extraction subissue for a clearly independent package. +- A documentation update to `docs/packages.md`. +- An ADR or spec decision (e.g. versioning strategy, naming convention). + +There is no predetermined end date or total subissue count. + +## Open Questions + +These questions do not block starting work, but need answers before specific subissues can +be fully scoped. + +### Which packages are the first extraction candidates? + +Early intuitions (to be confirmed by the baseline analysis): + +- **`bittorrent-*` protocol crates** (`bittorrent-http-tracker-protocol`, + `bittorrent-udp-tracker-protocol`, `bittorrent-peer-id`) — implement BEP specs with no + tracker-specific logic; obvious candidates for standalone crates. +- **`contrib/bencode`** (`torrust-tracker-contrib-bencode`) — already published on crates.io; + lives in `contrib/` as a community contribution; arguably should live in its own repo. +- **Utility crates** (`torrust-tracker-clock`, `torrust-tracker-located-error`) — generic + enough to be reused outside the tracker; already published. + +Decision criteria to apply per candidate: + +- Does it have any tracker-specific logic or dependency? +- Would it benefit a downstream user outside this repository? +- Is its API stable enough for independent semver? +- What CI/release overhead does a separate repository introduce? + +### Versioning strategy for remaining packages + +The proposed policy — to be confirmed in an ADR — is: + +- **Extracted packages** (own repository): independent versioning from the day of extraction. + Each extracted package gets its own semver starting point. +- **`torrust-tracker-*` workspace packages**: remain on the shared workspace version. + These packages are tightly coupled to the tracker's server releases and should bump + together. Known exceptions that will version independently once extracted: + - `torrust-tracker-client` — CLI tool being extracted to its own repository. + - `torrust-tracker-located-error` — generic utility being renamed to `torrust-located-error` + and eventually extracted. +- **`torrust-` workspace packages** (e.g., `torrust-server-lib`): currently follow the + workspace version but are not tightly bound to the tracker release cadence. Versioning + strategy for these should be reviewed when they are extracted or decoupled. +- **`bittorrent-*` packages**: independent versions once extracted. + +This policy needs a formal ADR before it is enforced. The key open question is: should any +`torrust-tracker-*` package be broken out of the shared workspace version before being +extracted to its own repository? + +### Extraction ordering: crates.io publication constraints + +When a package is extracted to a standalone repository, all its **runtime** workspace +dependencies must already be published on crates.io (path deps become version deps after +extraction). The table below analyses every current or near-term extraction candidate +against this constraint (verified May 2026). + +| Package | Crates.io status | Unpublished runtime workspace deps | Can be published independently? | Ordering constraint | +| ----------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `torrust-tracker-contrib-bencode` | Yes | None | ✅ Now | Extraction subissue exists; no blockers | +| `bittorrent-peer-id` | No | None | ✅ Now | No spec yet; can be extracted first in the `bittorrent-*` sequence | +| `torrust-tracker-located-error` | Yes | None | ✅ Already published | No extraction spec yet | +| `torrust-tracker-clock` (→ `torrust-clock`) | Yes | `torrust-tracker-primitives` (published ✅); `DurationSinceUnixEpoch` will be removed by follow-up subissue | ✅ After rename + move | See [extract clock subissue](../../drafts/1669-09-extract-torrust-clock-to-standalone-repo.md) | +| `torrust-tracker-metrics` (→ `torrust-metrics`) | No | `torrust-tracker-primitives` (published ✅) | ✅ After rename | See [extract metrics subissue](../../drafts/1669-10-extract-torrust-metrics-to-standalone-repo.md) | +| `bittorrent-udp-tracker-protocol` | No | `bittorrent-peer-id` (not published) | ❌ | After `bittorrent-peer-id` | +| `bittorrent-tracker-core` | No | `torrust-tracker-events`, `torrust-tracker-metrics`, `torrust-tracker-swarm-coordination-registry`, `torrust-rest-tracker-api-client` (all unpublished) | ❌ Very deep chain | After all four above; also has `torrust-rest-tracker-api-client` as a runtime dep — a layer violation worth resolving before extraction | +| `bittorrent-http-tracker-protocol` | No | `bittorrent-udp-tracker-protocol`, `bittorrent-tracker-core` (both unpublished) | ❌ | After `bittorrent-udp-tracker-protocol` and `bittorrent-tracker-core` | + +**Practical extraction order for `bittorrent-*` crates** (once decided): + +1. `bittorrent-peer-id` — no workspace deps; extract first. +2. `bittorrent-udp-tracker-protocol` — only blocked by #1. +3. `bittorrent-tracker-core` — needs the four unpublished deps above + clock rename; complex + chain; the layer violation (`torrust-rest-tracker-api-client` runtime dep) should be + resolved before or during this step. +4. `bittorrent-http-tracker-protocol` — needs #2 and #3 done. + +> Workspace renames (this EPIC's current subissues) are independent of extraction ordering — +> a crate can be renamed in-workspace before it is published or extracted. + +### Analysis tooling + +The issue references several tools (screenshots from CodeScene already in the issue comment): + +- [`cargo-depgraph`](https://sr.ht/~jplatte/cargo-depgraph/) — Rust dependency graphs +- [GitNexus](https://github.com/abhigyanpatwari/GitNexus) — Git relationship visualizer +- [CodeScene](https://codescene.io/) — Code quality and hotspot analysis + +The baseline analysis subissue should pick the tool(s) and commit their output. + +## Progress Tracking + +### Workflow Checkpoints + +- [x] Epic spec drafted in `docs/issues/open/` +- [ ] Epic spec reviewed and approved by user/maintainer +- [ ] GitHub epic issue already exists (#1669); issue number added to this spec +- [ ] Baseline analysis subissue created and linked +- [ ] Subissue statuses kept up to date in the `Active Subissues` table +- [ ] For each implemented subissue: automatic checks completed and recorded +- [ ] For each implemented subissue: manual verification completed and recorded +- [ ] For each implemented subissue: acceptance criteria reviewed post-implementation +- [ ] Epic periodically re-evaluated after structural changes (ongoing) + +### Progress Log + +- 2026-05-15 12:00 UTC - GitHub Copilot - Initial epic spec drafted from issue #1669 body and + comments. +- 2026-05-15 13:00 UTC - GitHub Copilot - Revised strategy: progressive/iterative approach, + extraction as first-class action from the start, no fixed phase plan. + +## Acceptance Criteria + +Because this EPIC is ongoing, acceptance criteria are defined per cycle, not for the +entire EPIC at once. The EPIC is considered healthy (not stale) when: + +- [ ] The baseline analysis is merged and the dependency graph is up to date. +- [ ] Every clearly independent package either has an open extraction subissue or a recorded + decision explaining why extraction was deferred. +- [ ] `docs/packages.md` and `AGENTS.md` Package Catalog are accurate after each change. +- [ ] Every completed subissue includes automated and manual verification evidence. +- [ ] The EPIC spec is reviewed and updated after each significant structural change. + +### Acceptance Verification + +| AC ID | Status | Evidence | +| ----- | ------ | ---------------------------------------- | +| AC1 | TODO | {baseline analysis PR link} | +| AC2 | TODO | {per-candidate issue or decision record} | +| AC3 | TODO | {PR link per structural change} | +| AC4 | TODO | {per-subissue links} | +| AC5 | TODO | {spec PR link per re-evaluation} | + +## Risks and Trade-offs + +- **Extraction execution cost**: Deciding to extract a package is easy; the actual work + (new repo, CI, publish pipeline, downstream dependency updates) is non-trivial. Scope each + extraction subissue carefully and do not start one without a clear owner. +- **Documentation drift**: READMEs and `docs/packages.md` updated early may drift if + structural changes follow. Accept this; a quick second-pass update is cheaper than waiting + for all decisions to be made before writing any docs. +- **Extraction paralysis**: The progressive approach works only if extractions actually + happen. Avoid endless analysis — if a package is obviously independent, open the subissue. +- **Tooling lock-in**: CodeScene is a third-party SaaS. Prefer capturing its insights in + committed documents rather than creating a workflow dependency on external tooling. +- **EPIC staleness**: An open-ended EPIC can quietly go stale. The re-evaluation triggers + (new package added, package split, etc.) defined in the Delivery Strategy are the + safeguard against this. + +## References + +- EPIC issue: +- Relates to: (Release v4.0.0-rc.1) +- Package architecture: [`docs/packages.md`](../../../packages.md) +- Package diagrams: [`docs/media/packages/`](../../../media/packages/) +- CodeScene screenshots: +- `cargo-depgraph`: +- GitNexus: +- CodeScene: diff --git a/project-words.txt b/project-words.txt index 5a234b4e7..769d83b62 100644 --- a/project-words.txt +++ b/project-words.txt @@ -70,6 +70,7 @@ datetime dbip dbname debuginfo +depgraph Deque Dihc Dijke @@ -100,6 +101,7 @@ Freebox frontmatter Frostegård gecos +Garnham Gibibytes Glrg Grcov