From 49cef6cf6bc21f0db9f6372d3ebcf71a9952b2c2 Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Fri, 15 May 2026 19:29:39 +0100 Subject: [PATCH 01/11] docs(packages): add epic spec and subissue drafts for packages overhaul #1669 --- ...ation-since-unix-epoch-to-torrust-clock.md | 163 +++++++ ...ult-timeout-from-configuration-to-clock.md | 147 ++++++ ...prefix-rename-tracker-specific-packages.md | 208 +++++++++ ...rust-tracker-metrics-to-torrust-metrics.md | 144 ++++++ ...-torrust-tracker-clock-to-torrust-clock.md | 190 ++++++++ ...-located-error-to-torrust-located-error.md | 169 +++++++ ...cker-contrib-bencode-to-torrust-bencode.md | 192 ++++++++ ...xtract-torrust-clock-to-standalone-repo.md | 178 ++++++++ ...ract-torrust-metrics-to-standalone-repo.md | 166 +++++++ ...rrust-tracker-client-to-standalone-repo.md | 162 +++++++ .../open/1669-overhaul-packages/EPIC.md | 421 ++++++++++++++++++ project-words.txt | 2 + 12 files changed, 2142 insertions(+) create mode 100644 docs/issues/drafts/1669-02-move-duration-since-unix-epoch-to-torrust-clock.md create mode 100644 docs/issues/drafts/1669-03-move-default-timeout-from-configuration-to-clock.md create mode 100644 docs/issues/drafts/1669-04-align-torrust-prefix-rename-tracker-specific-packages.md create mode 100644 docs/issues/drafts/1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md create mode 100644 docs/issues/drafts/1669-06-rename-torrust-tracker-clock-to-torrust-clock.md create mode 100644 docs/issues/drafts/1669-07-rename-torrust-tracker-located-error-to-torrust-located-error.md create mode 100644 docs/issues/drafts/1669-08-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md create mode 100644 docs/issues/drafts/1669-09-extract-torrust-clock-to-standalone-repo.md create mode 100644 docs/issues/drafts/1669-10-extract-torrust-metrics-to-standalone-repo.md create mode 100644 docs/issues/drafts/1669-11-extract-torrust-tracker-client-to-standalone-repo.md create mode 100644 docs/issues/open/1669-overhaul-packages/EPIC.md 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 From ab4d8285c2bff60681b33d78b70f9ddf0c0c6022 Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Mon, 18 May 2026 12:49:28 +0100 Subject: [PATCH 02/11] feat(analysis): add workspace-coupling analysis tool and SI-01 baseline artifacts Add a Rust binary at contrib/dev-tools/analysis/workspace-coupling/ that analyses inter-package coupling in the Cargo workspace. The tool produces: - A dependency graph (Graphviz DOT) - A coupling hotspots report (JSON / text) Also add the SI-01 output artifacts: - docs/issues/open/1669-overhaul-packages/readme-audit.md - docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md And the SI-01 subissue spec: - docs/issues/drafts/1669-01-establish-baseline-analysis.md Add new technical words to project-words.txt (argjson, Graphviz, hotspots, organisation, prioritise, rustdoc, walkdir). --- Cargo.lock | 10 + Cargo.toml | 1 + .../dev-tools/analysis/workspace-coupling.sh | 227 ++++ .../analysis/workspace-coupling/Cargo.toml | 15 + .../analysis/workspace-coupling/src/main.rs | 351 ++++++ .../1669-01-establish-baseline-analysis.md | 173 +++ .../1669-overhaul-packages/readme-audit.md | 73 ++ .../workspace-coupling-report.md | 1123 +++++++++++++++++ project-words.txt | 13 +- 9 files changed, 1983 insertions(+), 3 deletions(-) create mode 100755 contrib/dev-tools/analysis/workspace-coupling.sh create mode 100644 contrib/dev-tools/analysis/workspace-coupling/Cargo.toml create mode 100644 contrib/dev-tools/analysis/workspace-coupling/src/main.rs create mode 100644 docs/issues/drafts/1669-01-establish-baseline-analysis.md create mode 100644 docs/issues/open/1669-overhaul-packages/readme-audit.md create mode 100644 docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md diff --git a/Cargo.lock b/Cargo.lock index a200082bc..6735518cf 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -6685,6 +6685,16 @@ dependencies = [ "wasmparser", ] +[[package]] +name = "workspace-coupling" +version = "3.0.0-develop" +dependencies = [ + "regex", + "serde", + "serde_json", + "walkdir", +] + [[package]] name = "writeable" version = "0.6.3" diff --git a/Cargo.toml b/Cargo.toml index 73b11bcce..556134e49 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -78,6 +78,7 @@ torrust-tracker-test-helpers = { version = "3.0.0-develop", path = "packages/tes [workspace] members = [ "console/tracker-client", + "contrib/dev-tools/analysis/workspace-coupling", "packages/torrent-repository-benchmarking", ] diff --git a/contrib/dev-tools/analysis/workspace-coupling.sh b/contrib/dev-tools/analysis/workspace-coupling.sh new file mode 100755 index 000000000..21b6bcd37 --- /dev/null +++ b/contrib/dev-tools/analysis/workspace-coupling.sh @@ -0,0 +1,227 @@ +#!/usr/bin/env bash +# +# workspace-coupling.sh +# +# Generates a workspace coupling report for the Torrust Tracker repository. +# +# For every workspace package that has workspace-level dependencies the script: +# 1. Lists the declared workspace dependencies (normal / dev / build). +# 2. Scans the package's src/ directory for `use DEP_MODULE::` statements and +# fully-qualified `DEP_MODULE::` path references, then lists the distinct +# top-level import paths found. +# +# A short import list (1-3 items) is a signal that the dependency may be weak +# and worth reviewing (e.g. moving a single constant to eliminate the edge). +# +# Requirements: cargo, jq, ripgrep (rg) +# +# Usage: +# ./contrib/dev-tools/analysis/workspace-coupling.sh [OUTPUT_FILE] +# +# If OUTPUT_FILE is omitted the report is written to: +# docs/media/packages/workspace-coupling-report.md +# +# Exit codes: 0 on success, non-zero on error. + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +WORKSPACE_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)" +OUTPUT_FILE="${1:-$WORKSPACE_ROOT/docs/media/packages/workspace-coupling-report.md}" + +echo "Workspace root : $WORKSPACE_ROOT" >&2 +echo "Output file : $OUTPUT_FILE" >&2 +echo "" >&2 + +# --------------------------------------------------------------------------- +# 1. Load workspace metadata +# --------------------------------------------------------------------------- +cd "$WORKSPACE_ROOT" +METADATA=$(cargo metadata --format-version 1 2>/dev/null) + +# Build a JSON array of workspace member names (used as a lookup set later). +WORKSPACE_NAME_SET=$(echo "$METADATA" | jq -c ' + .workspace_members as $members | + [.packages[] | select(.id as $id | $members | index($id) != null) | .name] +') + +# Sorted list of workspace member names, one per line. +WORKSPACE_MEMBER_NAMES=$(echo "$WORKSPACE_NAME_SET" | jq -r 'sort | .[]') + +# Count total workspace members for the header. +TOTAL=$(echo "$WORKSPACE_NAME_SET" | jq 'length') + +# --------------------------------------------------------------------------- +# 2. Helper: convert a crate name to its Rust module identifier +# (hyphens → underscores). +# --------------------------------------------------------------------------- +crate_to_module() { echo "$1" | tr '-' '_'; } + +# --------------------------------------------------------------------------- +# 3. Render the report +# --------------------------------------------------------------------------- +{ + echo "# Workspace Coupling Report" + echo "" + echo "Generated: $(date -u '+%Y-%m-%d %H:%M UTC')" + echo "" + echo "Workspace packages: $TOTAL" + echo "" + echo "---" + echo "" + echo "## How to read this report" + echo "" + echo "Each section covers one workspace package that has at least one workspace-level" + echo "dependency. For every dependency the items actually imported from it are listed:" + echo "" + echo "- **Normal dep** — required for compilation of the library/binary." + echo "- **Dev dep** — required only in tests and benchmarks." + echo "- **Build dep** — required only in \`build.rs\`." + echo "" + echo "Items are extracted by scanning the package's \`src/\` directory for" + echo "\`use MODULE::\` statements and \`MODULE::\` fully-qualified path references." + echo "The scan is text-based; it may miss items imported through re-exports or macros," + echo "but it is accurate enough to identify thin-dependency patterns." + echo "" + echo "**Signal**: a dependency with only 1–3 distinct import paths may be a candidate" + echo "for elimination (move the item, break the edge)." + echo "" + echo "---" + echo "" + echo "## Packages with no workspace dependencies" + echo "" + echo "These packages are leaves (no workspace dep) and are prime extraction candidates." + echo "" + + # List leaf packages. + LEAF_LIST="" + while IFS= read -r PKG_NAME; do + DEP_COUNT=$(echo "$METADATA" | jq --arg name "$PKG_NAME" \ + --argjson ws_names "$WORKSPACE_NAME_SET" ' + .packages[] | select(.name == $name) | + [.dependencies[] | select(.name as $n | $ws_names | index($n) != null)] | length + ') + if [ "$DEP_COUNT" -eq 0 ]; then + echo "- \`$PKG_NAME\`" + LEAF_LIST="${LEAF_LIST}${PKG_NAME}\n" + fi + done <<< "$WORKSPACE_MEMBER_NAMES" + + echo "" + echo "---" + echo "" + echo "## Package coupling details" + echo "" +} > "$OUTPUT_FILE" + +# --------------------------------------------------------------------------- +# 4. Per-package sections (only packages that have workspace deps) +# --------------------------------------------------------------------------- +while IFS= read -r PKG_NAME; do + # Extract this package's workspace dependencies (all kinds). + PKG_MANIFEST=$(echo "$METADATA" | jq -r --arg name "$PKG_NAME" ' + .packages[] | select(.name == $name) | .manifest_path + ') + PKG_DIR="$(dirname "$PKG_MANIFEST")" + PKG_SRC_DIR="$PKG_DIR/src" + + # Build a sorted list of workspace deps as JSON objects {name, kind}. + WORKSPACE_DEPS=$(echo "$METADATA" | jq -c --arg name "$PKG_NAME" \ + --argjson ws_names "$WORKSPACE_NAME_SET" ' + .packages[] | select(.name == $name) | + [ + .dependencies[] | + select(.name as $n | $ws_names | index($n) != null) | + {name: .name, kind: (.kind // "normal")} + ] | sort_by(.kind, .name) + ') + + DEP_COUNT=$(echo "$WORKSPACE_DEPS" | jq 'length') + if [ "$DEP_COUNT" -eq 0 ]; then + continue + fi + + { + echo "### \`$PKG_NAME\`" + echo "" + echo "Workspace deps: $DEP_COUNT" + echo "" + } >> "$OUTPUT_FILE" + + # For each workspace dependency, scan the source for imports. + while IFS= read -r DEP_JSON; do + DEP_NAME=$(echo "$DEP_JSON" | jq -r '.name') + DEP_KIND=$(echo "$DEP_JSON" | jq -r '.kind') + DEP_MODULE=$(crate_to_module "$DEP_NAME") + + { + echo "#### \`$DEP_NAME\` [$DEP_KIND]" + echo "" + } >> "$OUTPUT_FILE" + + if [ -d "$PKG_SRC_DIR" ]; then + # Search for: `use DEP_MODULE::` and bare `DEP_MODULE::Foo` references. + # Extract the path up to the next space, semicolon, brace, or comma. + IMPORTS=$( + rg --no-filename --no-line-number \ + "${DEP_MODULE}::[A-Za-z_]" \ + "$PKG_SRC_DIR" 2>/dev/null \ + | grep -oP "${DEP_MODULE}::[A-Za-z_][A-Za-z0-9_]*(?:::[A-Za-z_][A-Za-z0-9_]*)?" \ + | sort -u \ + || true + ) + + if [ -n "$IMPORTS" ]; then + echo "$IMPORTS" | while IFS= read -r IMPORT; do + echo "- \`$IMPORT\`" + done >> "$OUTPUT_FILE" + else + # Check if there are any references at all (maybe macro-only usage) + ANY=$( + rg --no-filename --no-line-number \ + "${DEP_MODULE}" \ + "$PKG_SRC_DIR" 2>/dev/null | head -1 \ + || true + ) + if [ -n "$ANY" ]; then + echo "_Items not extracted — dependency used without a direct \`use\` path (macro, re-export, or glob import)._" >> "$OUTPUT_FILE" + else + echo "_No \`${DEP_MODULE}::\` references found in \`src/\` — may be used only in \`Cargo.toml\` feature flags or \`build.rs\`._" >> "$OUTPUT_FILE" + fi + fi + else + echo "_Source directory \`src/\` not found at \`$PKG_SRC_DIR\`._" >> "$OUTPUT_FILE" + fi + + echo "" >> "$OUTPUT_FILE" + + done < <(echo "$WORKSPACE_DEPS" | jq -c '.[]') + +done <<< "$WORKSPACE_MEMBER_NAMES" + +# --------------------------------------------------------------------------- +# 5. Observations placeholder +# --------------------------------------------------------------------------- +{ + echo "---" + echo "" + echo "## Observations" + echo "" + echo "_(To be filled in after reviewing the report above.)_" + echo "" + echo "### Known thin dependencies (pre-existing)" + echo "" + echo "- \`torrust-tracker-clock\` → \`torrust-tracker-primitives\`: only" + echo " \`DurationSinceUnixEpoch\` imported. Addressed by SI-02." + echo "- \`torrust-tracker-configuration\` → \`torrust-tracker-clock\`: only" + echo " \`DEFAULT_TIMEOUT\` imported. Addressed by SI-03." + echo "" + echo "### New findings" + echo "" + echo "_(Record any new thin-dependency or cluster-dependency findings here, with a" + echo "reference to the subissue opened for each.)_" + echo "" +} >> "$OUTPUT_FILE" + +echo "Done." >&2 +echo "Report: $OUTPUT_FILE" >&2 diff --git a/contrib/dev-tools/analysis/workspace-coupling/Cargo.toml b/contrib/dev-tools/analysis/workspace-coupling/Cargo.toml new file mode 100644 index 000000000..bc8f47c8c --- /dev/null +++ b/contrib/dev-tools/analysis/workspace-coupling/Cargo.toml @@ -0,0 +1,15 @@ +[package] +description = "Generates a workspace coupling report for the Torrust Tracker workspace." +name = "workspace-coupling" +publish = false + +authors.workspace = true +edition.workspace = true +rust-version.workspace = true +version.workspace = true + +[dependencies] +regex = "1" +serde = { version = "1", features = [ "derive" ] } +serde_json = "1" +walkdir = "2" diff --git a/contrib/dev-tools/analysis/workspace-coupling/src/main.rs b/contrib/dev-tools/analysis/workspace-coupling/src/main.rs new file mode 100644 index 000000000..8f667a7df --- /dev/null +++ b/contrib/dev-tools/analysis/workspace-coupling/src/main.rs @@ -0,0 +1,351 @@ +//! Generates a workspace coupling report for the Torrust Tracker workspace. +//! +//! For every workspace package that has workspace-level dependencies the tool: +//! 1. Lists the declared workspace dependencies (normal / dev / build). +//! 2. Scans the package's `src/` directory for `use DEP_MODULE::` statements and +//! fully-qualified `DEP_MODULE::` path references, then lists the distinct +//! top-level import paths found. +//! +//! # Usage +//! +//! ```text +//! workspace-coupling [OUTPUT_FILE] +//! ``` +//! +//! If `OUTPUT_FILE` is omitted the report is written to +//! `docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md` +//! relative to the workspace root. + +use std::collections::{BTreeSet, HashSet}; +use std::fmt::Write; +use std::fs; +use std::path::{Path, PathBuf}; +use std::process::Command; + +use regex::Regex; +use serde::Deserialize; +use walkdir::WalkDir; + +#[derive(Deserialize)] +struct Metadata { + workspace_root: String, + workspace_members: Vec, + packages: Vec, +} + +#[derive(Deserialize)] +struct Package { + id: String, + name: String, + manifest_path: String, + dependencies: Vec, +} + +#[derive(Deserialize)] +struct Dep { + name: String, + kind: Option, +} + +fn crate_to_module(name: &str) -> String { + name.replace('-', "_") +} + +fn dep_kind_label(kind: Option<&str>) -> &'static str { + match kind { + Some("dev") => "dev", + Some("build") => "build", + _ => "normal", + } +} + +fn dep_kind_order(kind: Option<&str>) -> u8 { + match kind { + Some("dev") => 1, + Some("build") => 2, + _ => 0, + } +} + +struct ScanResult { + imports: BTreeSet, + has_any_reference: bool, +} + +fn scan_imports(src_dir: &Path, module_name: &str) -> ScanResult { + let import_pattern = format!(r"{module_name}::[A-Za-z_][A-Za-z0-9_]*(?:::[A-Za-z_][A-Za-z0-9_]*)?"); + let import_re = Regex::new(&import_pattern).expect("import regex is valid"); + let any_pattern = format!(r"\b{module_name}\b"); + let any_re = Regex::new(&any_pattern).expect("any-reference regex is valid"); + + let mut result = ScanResult { + imports: BTreeSet::new(), + has_any_reference: false, + }; + + if !src_dir.is_dir() { + return result; + } + + for entry in WalkDir::new(src_dir) + .into_iter() + .filter_map(Result::ok) + .filter(|e| e.path().extension().is_some_and(|ext| ext == "rs")) + { + let Ok(content) = fs::read_to_string(entry.path()) else { + continue; + }; + + for m in import_re.find_iter(&content) { + result.imports.insert(m.as_str().to_owned()); + } + + if !result.has_any_reference && any_re.is_match(&content) { + result.has_any_reference = true; + } + } + + result +} + +fn utc_timestamp() -> String { + let output = Command::new("date").args(["-u", "+%Y-%m-%d %H:%M UTC"]).output(); + match output { + Ok(o) if o.status.success() => String::from_utf8_lossy(&o.stdout).trim().to_owned(), + _ => String::from("(timestamp unavailable)"), + } +} + +fn write_header(out: &mut String, total: usize, timestamp: &str) { + writeln!(out, "# Workspace Coupling Report").unwrap(); + writeln!(out).unwrap(); + writeln!(out, "Generated: {timestamp}").unwrap(); + writeln!(out).unwrap(); + writeln!(out, "Workspace packages: {total}").unwrap(); + writeln!(out).unwrap(); + writeln!(out, "---").unwrap(); + writeln!(out).unwrap(); + writeln!(out, "## How to read this report").unwrap(); + writeln!(out).unwrap(); + writeln!( + out, + "Each section covers one workspace package that has at least one workspace-level" + ) + .unwrap(); + writeln!( + out, + "dependency. For every dependency the items actually imported from it are listed:" + ) + .unwrap(); + writeln!(out).unwrap(); + writeln!(out, "- **Normal dep** — required for compilation of the library/binary.").unwrap(); + writeln!(out, "- **Dev dep** — required only in tests and benchmarks.").unwrap(); + writeln!(out, "- **Build dep** — required only in `build.rs`.").unwrap(); + writeln!(out).unwrap(); + writeln!(out, "Items are extracted by scanning the package's `src/` directory for").unwrap(); + writeln!( + out, + "`use MODULE::` statements and `MODULE::` fully-qualified path references." + ) + .unwrap(); + writeln!( + out, + "The scan is text-based; it may miss items imported through re-exports or macros," + ) + .unwrap(); + writeln!(out, "but it is accurate enough to identify thin-dependency patterns.").unwrap(); + writeln!(out).unwrap(); + writeln!( + out, + "**Signal**: a dependency with only 1–3 distinct import paths may be a candidate" + ) + .unwrap(); + writeln!(out, "for elimination (move the item, break the edge).").unwrap(); + writeln!(out).unwrap(); + writeln!(out, "---").unwrap(); + writeln!(out).unwrap(); +} + +fn write_leaves(out: &mut String, meta: &Metadata, ws_ids: &HashSet<&str>, ws_names: &HashSet<&str>) { + writeln!(out, "## Packages with no workspace dependencies").unwrap(); + writeln!(out).unwrap(); + writeln!( + out, + "These packages are leaves (no workspace dep) and are prime extraction candidates." + ) + .unwrap(); + writeln!(out).unwrap(); + + let mut leaf_names: BTreeSet<&str> = BTreeSet::new(); + for pkg in &meta.packages { + if !ws_ids.contains(pkg.id.as_str()) { + continue; + } + let ws_dep_count = pkg.dependencies.iter().filter(|d| ws_names.contains(d.name.as_str())).count(); + if ws_dep_count == 0 { + leaf_names.insert(&pkg.name); + } + } + + if leaf_names.is_empty() { + writeln!(out, "_None._").unwrap(); + } else { + for name in &leaf_names { + writeln!(out, "- `{name}`").unwrap(); + } + } + + writeln!(out).unwrap(); + writeln!(out, "---").unwrap(); + writeln!(out).unwrap(); +} + +fn write_dep_section(out: &mut String, dep: &Dep, src_dir: &Path) { + let kind = dep_kind_label(dep.kind.as_deref()); + writeln!(out, "#### `{}` [{kind}]", dep.name).unwrap(); + writeln!(out).unwrap(); + + let module = crate_to_module(&dep.name); + let scan = scan_imports(src_dir, &module); + + if !scan.imports.is_empty() { + for import in &scan.imports { + writeln!(out, "- `{import}`").unwrap(); + } + } else if scan.has_any_reference { + writeln!( + out, + "_Items not extracted — dependency used without a direct `use` path (macro, re-export, or glob import)._" + ) + .unwrap(); + } else if src_dir.is_dir() { + writeln!( + out, + "_No `{module}::` references found in `src/` — may be used only in `Cargo.toml` feature flags or `build.rs`._" + ) + .unwrap(); + } else { + writeln!(out, "_Source directory `src/` not found._").unwrap(); + } + + writeln!(out).unwrap(); +} + +fn write_coupling_details(out: &mut String, meta: &Metadata, ws_ids: &HashSet<&str>, ws_names: &HashSet<&str>) { + writeln!(out, "## Package coupling details").unwrap(); + writeln!(out).unwrap(); + + let mut sorted_packages: Vec<&Package> = meta.packages.iter().filter(|p| ws_ids.contains(p.id.as_str())).collect(); + sorted_packages.sort_by(|a, b| a.name.cmp(&b.name)); + + for pkg in sorted_packages { + let manifest_dir = Path::new(&pkg.manifest_path) + .parent() + .expect("manifest path has a parent directory"); + let src_dir = manifest_dir.join("src"); + + let mut ws_deps: Vec<&Dep> = pkg + .dependencies + .iter() + .filter(|d| ws_names.contains(d.name.as_str())) + .collect(); + + if ws_deps.is_empty() { + continue; + } + + ws_deps.sort_by(|a, b| { + dep_kind_order(a.kind.as_deref()) + .cmp(&dep_kind_order(b.kind.as_deref())) + .then(a.name.cmp(&b.name)) + }); + + writeln!(out, "### `{}`", pkg.name).unwrap(); + writeln!(out).unwrap(); + writeln!(out, "Workspace deps: {}", ws_deps.len()).unwrap(); + writeln!(out).unwrap(); + + for dep in ws_deps { + write_dep_section(out, dep, &src_dir); + } + } +} + +fn write_observations(out: &mut String) { + writeln!(out, "---").unwrap(); + writeln!(out).unwrap(); + writeln!(out, "## Observations").unwrap(); + writeln!(out).unwrap(); + writeln!(out, "_(To be filled in after reviewing the report above.)_").unwrap(); + writeln!(out).unwrap(); + writeln!(out, "### Known thin dependencies (pre-existing)").unwrap(); + writeln!(out).unwrap(); + writeln!(out, "- `torrust-tracker-clock` → `torrust-tracker-primitives`: only").unwrap(); + writeln!(out, " `DurationSinceUnixEpoch` imported. Addressed by SI-02.").unwrap(); + writeln!(out, "- `torrust-tracker-configuration` → `torrust-tracker-clock`: only").unwrap(); + writeln!(out, " `DEFAULT_TIMEOUT` imported. Addressed by SI-03.").unwrap(); + writeln!(out).unwrap(); + writeln!(out, "### New findings").unwrap(); + writeln!(out).unwrap(); + writeln!( + out, + "_(Record any new thin-dependency or cluster-dependency findings here, with a" + ) + .unwrap(); + writeln!(out, "reference to the subissue opened for each.)_").unwrap(); + writeln!(out).unwrap(); +} + +fn generate_report(meta: &Metadata) -> String { + let ws_ids: HashSet<&str> = meta.workspace_members.iter().map(String::as_str).collect(); + let ws_names: HashSet<&str> = meta + .packages + .iter() + .filter(|p| ws_ids.contains(p.id.as_str())) + .map(|p| p.name.as_str()) + .collect(); + let total = ws_names.len(); + let timestamp = utc_timestamp(); + + let mut report = String::new(); + write_header(&mut report, total, ×tamp); + write_leaves(&mut report, meta, &ws_ids, &ws_names); + write_coupling_details(&mut report, meta, &ws_ids, &ws_names); + write_observations(&mut report); + report +} + +fn main() { + let args: Vec = std::env::args().collect(); + + eprintln!("Running cargo metadata..."); + let output = Command::new("cargo") + .args(["metadata", "--format-version", "1"]) + .output() + .expect("failed to run cargo metadata"); + + if !output.status.success() { + eprintln!("cargo metadata failed:\n{}", String::from_utf8_lossy(&output.stderr)); + std::process::exit(1); + } + + let meta: Metadata = serde_json::from_slice(&output.stdout).expect("failed to parse cargo metadata JSON"); + + let workspace_root = PathBuf::from(&meta.workspace_root); + let default_output = workspace_root.join("docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md"); + let output_path: PathBuf = args.get(1).map_or(default_output, PathBuf::from); + + eprintln!("Workspace root: {}", workspace_root.display()); + eprintln!("Output file: {}", output_path.display()); + + let report = generate_report(&meta); + + if let Some(parent) = output_path.parent() { + fs::create_dir_all(parent).expect("failed to create output directories"); + } + + fs::write(&output_path, report).expect("failed to write report file"); + + eprintln!("Done."); + eprintln!("Report: {}", output_path.display()); +} diff --git a/docs/issues/drafts/1669-01-establish-baseline-analysis.md b/docs/issues/drafts/1669-01-establish-baseline-analysis.md new file mode 100644 index 000000000..e890483db --- /dev/null +++ b/docs/issues/drafts/1669-01-establish-baseline-analysis.md @@ -0,0 +1,173 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p1 +github-issue: null +spec-path: docs/issues/drafts/1669-01-establish-baseline-analysis.md +branch: null +related-pr: null +last-updated-utc: 2026-05-18 00:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - contrib/dev-tools/analysis/workspace-coupling/src/main.rs + - docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md + - docs/issues/open/1669-overhaul-packages/readme-audit.md + - docs/issues/open/1669-overhaul-packages/EPIC.md +--- + + + +# Issue #[To be assigned] - Establish baseline: workspace coupling analysis and README audit + +## Goal + +Produce two committed artifacts that characterize the current workspace: + +1. **Coupling report** — for every workspace package, list its workspace-level dependencies + and, for each dependency, the specific items (types, constants, traits, functions) actually + imported from it. The report reveals weak dependencies (a package that imports only one + constant from another) and tight clusters, and informs every subsequent extraction + subissue. +2. **README audit table** — a single table rating each package's README on a three-point + scale (good / minimal / stub), to identify documentation gaps. + +Both artifacts are generated by a reproducible Rust binary (`contrib/dev-tools/analysis/workspace-coupling/`) +so they can be refreshed after each structural change without manual effort. + +This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) +(Overhaul: Packages). + +## Background + +The workspace contains 26 packages that grew organically over multiple refactoring cycles. +Two coupling problems have already been identified manually: + +- `torrust-tracker-clock` depends on `torrust-tracker-primitives` only to import + `DurationSinceUnixEpoch` (SI-02). +- `torrust-tracker-configuration` depends on `torrust-tracker-clock` only to import + `DEFAULT_TIMEOUT` (SI-03). + +These were discovered through code inspection. A systematic analysis would surface similar +findings across all 26 packages without relying on luck or familiarity with the codebase. + +### Why the item-level view matters + +Knowing that "package A declares a Cargo dependency on package B" is not enough to assess +whether the coupling is appropriate. The item-level view answers: + +- **Thin dependency**: A imports only one constant or one type alias from B → move that item, + break the dependency edge. +- **Cluster dependency**: A imports a cohesive subset of B's API → consider extracting that + subset into a new package. +- **Deep dependency**: A uses many items across B's API → coupling is substantial and + intentional; extraction would require significant refactoring. + +### What the tool does + +The Rust binary performs two passes using `cargo metadata` and a text scan: + +1. **Pass 1 (Cargo.toml graph)** — runs `cargo metadata` to enumerate all workspace members + and their declared workspace-level dependencies (normal, dev, and build), grouped by + dependency kind. +2. **Pass 2 (source scan)** — for each declared dependency edge `A → B`, scans `A`'s `src/` + directory for `use B_module::` import statements and fully-qualified `B_module::` path + references. Extracts distinct top-level import paths. + +The output is a markdown report saved to +`docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md`. + +## Scope + +### In Scope + +- Create Rust binary `contrib/dev-tools/analysis/workspace-coupling/` — the report generator. +- Run the binary and commit the resulting report to + `docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md`. +- Write a brief README audit table (manually, based on inspection) in + `docs/issues/open/1669-overhaul-packages/readme-audit.md`. +- Review the coupling report for thin-dependency findings and record them as observations + in the coupling report itself or a linked notes section. + +### Out of Scope + +- Fixing any of the coupling issues found (each fix becomes its own subissue). +- Semantic domain graph, git co-change graph, or bounded-context analysis (deferred; revisit + if the coupling report leaves open questions). +- Generating visual graphs (e.g. DOT/SVG) — the markdown table is sufficient for the first + cycle; visualizations can be added if a graph helps communicate a specific finding. + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| T1 | TODO | Create Rust binary `contrib/dev-tools/analysis/workspace-coupling/` and add it to workspace members | Binary compiles cleanly (`cargo build -p workspace-coupling`) | +| T2 | TODO | Run binary; review output for obvious errors (missing packages, wrong module names) | Report covers all 26 workspace packages | +| T3 | TODO | Save report to `docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md` and commit | File committed in the analysis branch | +| T4 | TODO | Manually audit each package README; fill in `docs/issues/open/1669-overhaul-packages/readme-audit.md` table | Table covers all 26 packages; rating = good / minimal / stub | +| T5 | TODO | Review coupling report; annotate thin-dependency findings (SI-02/SI-03 patterns and any new ones found) | Findings recorded in a "Observations" section at the bottom of the report | +| T6 | TODO | For each new thin-dependency finding: open (or update) a corresponding subissue in EPIC #1669 Active Subissues | New subissues added to EPIC quick list if applicable | +| T7 | TODO | Run `linter all` | Exit code `0` | + +## 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 +- [ ] Script written and reviewed +- [ ] Coupling report generated and committed +- [ ] README audit table committed +- [ ] Observations section written +- [ ] EPIC #1669 Active Subissues table updated to `DONE` +- [ ] Issue closed and spec moved to `docs/issues/closed/` + +### Progress Log + +- 2026-05-18 00:00 UTC - GitHub Copilot - Spec drafted as subissue SI-01 of EPIC #1669. + Scope refined during discussion: item-level import scan is central (not optional) because + without it thin-dependency patterns like SI-02/SI-03 cannot be found systematically. + +## Acceptance Criteria + +- [ ] `contrib/dev-tools/analysis/workspace-coupling/` exists, compiles cleanly + (`cargo build -p workspace-coupling`), and produces valid markdown output. +- [ ] `docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md` is committed + and covers all 26 workspace packages. +- [ ] Every workspace package that has workspace-level dependencies appears in the report with + at least one import path listed per dependency (or a documented reason why none was found). +- [ ] `docs/issues/open/1669-overhaul-packages/readme-audit.md` is committed with a rating + for each of the 26 packages. +- [ ] Any thin-dependency findings not already covered by existing subissues are recorded as + observations in the coupling report. +- [ ] `linter all` exits with code `0`. + +## Verification Plan + +### Automatic Checks + +- `linter all` (markdownlint, taplo, cspell, rustfmt, clippy) +- `cargo build -p workspace-coupling` + +### Manual Verification + +| ID | Scenario | Expected Result | +| --- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | +| MV1 | Open `docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md` and count package sections | 26 sections minus leaf packages (those with no workspace deps) should appear | +| MV2 | Find `torrust-tracker-configuration` in the report; check the `torrust-tracker-clock` dep section | Should list `torrust_tracker_clock::DEFAULT_TIMEOUT` (confirms SI-03 detection) | +| MV3 | Find `torrust-tracker-clock` in the report; check the `torrust-tracker-primitives` dep section | Should list `torrust_tracker_primitives::DurationSinceUnixEpoch` (SI-02) | +| MV4 | Run `cargo run -p workspace-coupling -- /tmp/test-report.md` on a clean checkout | Binary exits `0`; output file matches committed report structurally | + +## References + +- EPIC: [`docs/issues/open/1669-overhaul-packages/EPIC.md`](../open/1669-overhaul-packages/EPIC.md) +- Coupling report (generated): [`docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md`](../open/1669-overhaul-packages/workspace-coupling-report.md) +- README audit (generated): [`docs/issues/open/1669-overhaul-packages/readme-audit.md`](../open/1669-overhaul-packages/readme-audit.md) +- Report generator: [`contrib/dev-tools/analysis/workspace-coupling/`](../../../contrib/dev-tools/analysis/workspace-coupling/) +- Existing thin-dependency subissues: SI-02, SI-03 diff --git a/docs/issues/open/1669-overhaul-packages/readme-audit.md b/docs/issues/open/1669-overhaul-packages/readme-audit.md new file mode 100644 index 000000000..c31e03f84 --- /dev/null +++ b/docs/issues/open/1669-overhaul-packages/readme-audit.md @@ -0,0 +1,73 @@ +# README Audit + +Point-in-time audit of README quality across all workspace packages and console +tools. Generated manually on 2026-05-18 as part of SI-01 (baseline analysis). + +## Quality scale + +| Rating | Criteria | +| ----------- | ---------------------------------------------------------------------------------------------- | +| **good** | Meaningful sections (purpose, usage, badges, examples); gives a reader enough to get started. | +| **minimal** | Title, one-sentence description, and at most a `## Documentation` link; mostly placeholder. | +| **stub** | Only heading + one-liner + a `## Documentation` link (~11 lines); essentially a template copy. | + +## Workspace packages (`packages/`) + +| Package directory | Crate name | Lines | Rating | Notes | +| --------------------------------- | ------------------------------------------------- | ----- | ------- | ------------------------------------------------------------ | +| `axum-health-check-api-server` | `torrust-axum-health-check-api-server` | 49 | minimal | Has purpose and port info; no usage examples | +| `axum-http-tracker-server` | `torrust-axum-http-tracker-server` | 11 | stub | Template only | +| `axum-rest-tracker-api-server` | `torrust-axum-rest-tracker-api-server` | 11 | stub | Template only | +| `axum-server` | `torrust-axum-server` | 11 | stub | Template only | +| `clock` | `torrust-tracker-clock` | 11 | stub | Template only | +| `configuration` | `torrust-tracker-configuration` | 11 | stub | Template only | +| `events` | `torrust-tracker-events` | 11 | stub | Template only | +| `http-protocol` | `bittorrent-http-tracker-protocol` | 11 | stub | Template only | +| `http-tracker-core` | `bittorrent-http-tracker-core` | 15 | minimal | Explains when to use vs. when not to; minimal depth | +| `located-error` | `torrust-tracker-located-error` | 11 | stub | Template only | +| `metrics` | `torrust-tracker-metrics` | 210 | good | Comprehensive — overview, types, usage, examples | +| `peer-id` | `bittorrent-peer-id` | 38 | minimal | Origin story + maintenance note; no usage examples | +| `primitives` | `torrust-tracker-primitives` | 11 | stub | Template only | +| `rest-tracker-api-client` | `torrust-rest-tracker-api-client` | 23 | minimal | Has license section; no usage examples | +| `rest-tracker-api-core` | `torrust-rest-tracker-api-core` | 11 | stub | **Wrong title** — says "BitTorrent UDP Tracker Core library" | +| `server-lib` | `torrust-server-lib` | 11 | stub | Template only | +| `swarm-coordination-registry` | `torrust-tracker-swarm-coordination-registry` | 22 | minimal | **Wrong title** — says "Torrust Tracker Torrent Repository" | +| `test-helpers` | `torrust-tracker-test-helpers` | 11 | stub | **Wrong title** — says "Torrust Tracker Configuration" | +| `torrent-repository-benchmarking` | `torrust-tracker-torrent-repository-benchmarking` | 32 | minimal | Has benchmarking section; no run instructions beyond basic | +| `tracker-client` | `bittorrent-tracker-client` | 25 | minimal | Has WIP disclaimer; no usage examples | +| `tracker-core` | `bittorrent-tracker-core` | 39 | minimal | Has purpose and context; no usage examples | +| `udp-protocol` | `bittorrent-udp-tracker-protocol` | 38 | minimal | Has purpose section; no usage examples | +| `udp-tracker-core` | `bittorrent-udp-tracker-core` | 15 | minimal | Explains when to use; minimal depth | +| `udp-tracker-server` | `torrust-udp-tracker-server` | 11 | stub | Template only | + +## Console tools (`console/`) + +| Directory | Crate name | Lines | Rating | Notes | +| ---------------- | --------------------------- | ----- | ------ | ------------------------------------------- | +| `tracker-client` | `bittorrent-tracker-client` | 204 | good | Comprehensive — purpose, commands, examples | + +## Community contributions (`contrib/`) + +| Directory | Crate name | Lines | Rating | Notes | +| --------- | --------------------------------- | ----- | ------ | ----------------------------------------- | +| `bencode` | `torrust-tracker-contrib-bencode` | 5 | stub | Title + one-liner only; no usage examples | + +## Summary + +| Rating | Count | +| ----------- | ----- | +| **good** | 2 | +| **minimal** | 9 | +| **stub** | 16 | + +Most workspace packages have stub or minimal READMEs — they were likely cloned from a +template without being updated. The three packages with wrong titles need to be corrected: + +| Package directory | Current (wrong) title | Expected title | +| ----------------------------- | ----------------------------------- | --------------------------------------------- | +| `rest-tracker-api-core` | BitTorrent UDP Tracker Core library | Torrust REST Tracker API Core (or equivalent) | +| `swarm-coordination-registry` | Torrust Tracker Torrent Repository | Torrust Tracker Swarm Coordination Registry | +| `test-helpers` | Torrust Tracker Configuration | Torrust Tracker Test Helpers (or equivalent) | + +Improving READMEs to at least **minimal** status across all workspace packages is a +low-effort, high-value documentation task that could be bundled into a dedicated subissue. diff --git a/docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md b/docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md new file mode 100644 index 000000000..19a718aca --- /dev/null +++ b/docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md @@ -0,0 +1,1123 @@ +contrib/dev-tools/analysis/workspace-coupling.sh# Workspace Coupling Report + +Generated: 2026-05-18 08:00 UTC + +Workspace packages: 27 + +--- + +## How to read this report + +Each section covers one workspace package that has at least one workspace-level +dependency. For every dependency the items actually imported from it are listed: + +- **Normal dep** — required for compilation of the library/binary. +- **Dev dep** — required only in tests and benchmarks. +- **Build dep** — required only in `build.rs`. + +Items are extracted by scanning the package's `src/` directory for +`use MODULE::` statements and `MODULE::` fully-qualified path references. +The scan is text-based; it may miss items imported through re-exports or macros, +but it is accurate enough to identify thin-dependency patterns. + +**Signal**: a dependency with only 1–3 distinct import paths may be a candidate +for elimination (move the item, break the edge). + +--- + +## Packages with no workspace dependencies + +These packages are leaves (no workspace dep) and are prime extraction candidates. + +- `bittorrent-peer-id` +- `torrust-rest-tracker-api-client` +- `torrust-tracker-contrib-bencode` +- `torrust-tracker-events` +- `torrust-tracker-located-error` + +--- + +## Package coupling details + +### `bittorrent-http-tracker-core` + +Workspace deps: 9 + +#### `torrust-tracker-test-helpers` [dev] + +- `torrust_tracker_test_helpers::configuration` + +#### `bittorrent-http-tracker-protocol` [normal] + +- `bittorrent_http_tracker_protocol::v1::requests` +- `bittorrent_http_tracker_protocol::v1::services` + +#### `bittorrent-tracker-core` [normal] + +- `bittorrent_tracker_core::announce_handler` +- `bittorrent_tracker_core::announce_handler::AnnounceHandler` +- `bittorrent_tracker_core::announce_handler::PeersWanted` +- `bittorrent_tracker_core::authentication` +- `bittorrent_tracker_core::authentication::key` +- `bittorrent_tracker_core::authentication::service` +- `bittorrent_tracker_core::container::TrackerCoreContainer` +- `bittorrent_tracker_core::databases::setup` +- `bittorrent_tracker_core::error` +- `bittorrent_tracker_core::scrape_handler::ScrapeHandler` +- `bittorrent_tracker_core::statistics::persisted` +- `bittorrent_tracker_core::torrent::repository` +- `bittorrent_tracker_core::whitelist` +- `bittorrent_tracker_core::whitelist::authorization` +- `bittorrent_tracker_core::whitelist::repository` + +#### `torrust-tracker-clock` [normal] + +- `torrust_tracker_clock::clock` +- `torrust_tracker_clock::clock::Time` + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::Configuration` +- `torrust_tracker_configuration::Core` + +#### `torrust-tracker-events` [normal] + +- `torrust_tracker_events::broadcaster::Broadcaster` +- `torrust_tracker_events::bus::EventBus` +- `torrust_tracker_events::bus::SenderStatus` +- `torrust_tracker_events::receiver::Receiver` +- `torrust_tracker_events::receiver::RecvError` +- `torrust_tracker_events::sender::SendError` +- `torrust_tracker_events::sender::Sender` + +#### `torrust-tracker-metrics` [normal] + +- `torrust_tracker_metrics::label` +- `torrust_tracker_metrics::label::LabelSet` +- `torrust_tracker_metrics::label_name` +- `torrust_tracker_metrics::metric::MetricName` +- `torrust_tracker_metrics::metric::description` +- `torrust_tracker_metrics::metric_collection` +- `torrust_tracker_metrics::metric_collection::Error` +- `torrust_tracker_metrics::metric_collection::aggregate` +- `torrust_tracker_metrics::metric_name` +- `torrust_tracker_metrics::unit::Unit` + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::AnnounceData` +- `torrust_tracker_primitives::DurationSinceUnixEpoch` +- `torrust_tracker_primitives::ScrapeData` +- `torrust_tracker_primitives::peer::Peer` +- `torrust_tracker_primitives::peer::PeerAnnouncement` +- `torrust_tracker_primitives::service_binding` +- `torrust_tracker_primitives::service_binding::Protocol` +- `torrust_tracker_primitives::service_binding::ServiceBinding` +- `torrust_tracker_primitives::swarm_metadata::SwarmMetadata` + +#### `torrust-tracker-swarm-coordination-registry` [normal] + +- `torrust_tracker_swarm_coordination_registry::container::SwarmCoordinationRegistryContainer` + +### `bittorrent-http-tracker-protocol` + +Workspace deps: 7 + +#### `bittorrent-tracker-core` [normal] + +- `bittorrent_tracker_core::authentication::Error` +- `bittorrent_tracker_core::error::AnnounceError` +- `bittorrent_tracker_core::error::ScrapeError` +- `bittorrent_tracker_core::error::WhitelistError` + +#### `bittorrent-udp-tracker-protocol` [normal] + +- `bittorrent_udp_tracker_protocol::AnnounceEvent` +- `bittorrent_udp_tracker_protocol::AnnounceEvent::Completed` +- `bittorrent_udp_tracker_protocol::AnnounceEvent::None` +- `bittorrent_udp_tracker_protocol::AnnounceEvent::Started` +- `bittorrent_udp_tracker_protocol::AnnounceEvent::Stopped` + +#### `torrust-tracker-clock` [normal] + +- `torrust_tracker_clock::clock` +- `torrust_tracker_clock::clock::Time` + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::AnnouncePolicy` + +#### `torrust-tracker-contrib-bencode` [normal] + +_Items not extracted — dependency used without a direct `use` path (macro, re-export, or glob import)._ + +#### `torrust-tracker-located-error` [normal] + +_Items not extracted — dependency used without a direct `use` path (macro, re-export, or glob import)._ + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::PeerId` +- `torrust_tracker_primitives::ScrapeData` +- `torrust_tracker_primitives::peer` +- `torrust_tracker_primitives::peer::fixture` +- `torrust_tracker_primitives::swarm_metadata::SwarmMetadata` + +### `bittorrent-tracker-client` + +Workspace deps: 4 + +#### `bittorrent-udp-tracker-protocol` [normal] + +- `bittorrent_udp_tracker_protocol::PeerId` +- `bittorrent_udp_tracker_protocol::Request` + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::DEFAULT_TIMEOUT` + +#### `torrust-tracker-located-error` [normal] + +- `torrust_tracker_located_error::DynError` + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::peer` +- `torrust_tracker_primitives::service_binding::ServiceBinding` + +### `bittorrent-tracker-core` + +Workspace deps: 9 + +#### `torrust-rest-tracker-api-client` [dev] + +_No `torrust_rest_tracker_api_client::` references found in `src/` — may be used only in `Cargo.toml` feature flags or `build.rs`._ + +#### `torrust-tracker-test-helpers` [dev] + +- `torrust_tracker_test_helpers::configuration` +- `torrust_tracker_test_helpers::configuration::ephemeral_sqlite_database` + +#### `torrust-tracker-clock` [normal] + +- `torrust_tracker_clock::clock` +- `torrust_tracker_clock::clock::Time` +- `torrust_tracker_clock::clock::stopped` +- `torrust_tracker_clock::conv::convert_from_timestamp_to_datetime_utc` + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::AnnouncePolicy` +- `torrust_tracker_configuration::Configuration` +- `torrust_tracker_configuration::Core` +- `torrust_tracker_configuration::Driver::MySQL` +- `torrust_tracker_configuration::Driver::PostgreSQL` +- `torrust_tracker_configuration::Driver::Sqlite3` +- `torrust_tracker_configuration::TORRENT_PEERS_LIMIT` +- `torrust_tracker_configuration::v2_0_0::core` + +#### `torrust-tracker-events` [normal] + +- `torrust_tracker_events::receiver::RecvError` + +#### `torrust-tracker-located-error` [normal] + +- `torrust_tracker_located_error::Located` +- `torrust_tracker_located_error::LocatedError` + +#### `torrust-tracker-metrics` [normal] + +- `torrust_tracker_metrics::label::LabelSet` +- `torrust_tracker_metrics::metric::MetricName` +- `torrust_tracker_metrics::metric::description` +- `torrust_tracker_metrics::metric_collection` +- `torrust_tracker_metrics::metric_collection::Error` +- `torrust_tracker_metrics::metric_name` +- `torrust_tracker_metrics::unit::Unit` + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::AnnounceEvent` +- `torrust_tracker_primitives::DurationSinceUnixEpoch` +- `torrust_tracker_primitives::NumberOfBytes` +- `torrust_tracker_primitives::NumberOfDownloads` +- `torrust_tracker_primitives::NumberOfDownloadsBTreeMap` +- `torrust_tracker_primitives::PeerId` +- `torrust_tracker_primitives::ScrapeData` +- `torrust_tracker_primitives::pagination::Pagination` +- `torrust_tracker_primitives::peer` +- `torrust_tracker_primitives::peer::Peer` +- `torrust_tracker_primitives::swarm_metadata` +- `torrust_tracker_primitives::swarm_metadata::SwarmMetadata` + +#### `torrust-tracker-swarm-coordination-registry` [normal] + +- `torrust_tracker_swarm_coordination_registry::Registry` +- `torrust_tracker_swarm_coordination_registry::container::SwarmCoordinationRegistryContainer` +- `torrust_tracker_swarm_coordination_registry::event::Event` +- `torrust_tracker_swarm_coordination_registry::event::receiver` + +### `bittorrent-udp-tracker-core` + +Workspace deps: 9 + +#### `torrust-tracker-test-helpers` [dev] + +_No `torrust_tracker_test_helpers::` references found in `src/` — may be used only in `Cargo.toml` feature flags or `build.rs`._ + +#### `bittorrent-tracker-core` [normal] + +- `bittorrent_tracker_core::announce_handler` +- `bittorrent_tracker_core::container::TrackerCoreContainer` +- `bittorrent_tracker_core::error` +- `bittorrent_tracker_core::scrape_handler::ScrapeHandler` +- `bittorrent_tracker_core::torrent::repository` +- `bittorrent_tracker_core::whitelist` + +#### `bittorrent-udp-tracker-protocol` [normal] + +- `bittorrent_udp_tracker_protocol::AnnounceEvent::Completed` +- `bittorrent_udp_tracker_protocol::AnnounceEvent::None` +- `bittorrent_udp_tracker_protocol::AnnounceEvent::Started` +- `bittorrent_udp_tracker_protocol::AnnounceEvent::Stopped` +- `bittorrent_udp_tracker_protocol::AnnounceEvent::from` +- `bittorrent_udp_tracker_protocol::AnnounceRequest` +- `bittorrent_udp_tracker_protocol::ConnectionId` +- `bittorrent_udp_tracker_protocol::ScrapeRequest` +- `bittorrent_udp_tracker_protocol::common::InfoHash` + +#### `torrust-tracker-clock` [normal] + +- `torrust_tracker_clock::clock` +- `torrust_tracker_clock::clock::Time` + +#### `torrust-tracker-configuration` [normal] + +_Items not extracted — dependency used without a direct `use` path (macro, re-export, or glob import)._ + +#### `torrust-tracker-events` [normal] + +- `torrust_tracker_events::broadcaster::Broadcaster` +- `torrust_tracker_events::bus::EventBus` +- `torrust_tracker_events::bus::SenderStatus` +- `torrust_tracker_events::receiver::Receiver` +- `torrust_tracker_events::receiver::RecvError` +- `torrust_tracker_events::sender::SendError` +- `torrust_tracker_events::sender::Sender` + +#### `torrust-tracker-metrics` [normal] + +- `torrust_tracker_metrics::label` +- `torrust_tracker_metrics::label::LabelSet` +- `torrust_tracker_metrics::label_name` +- `torrust_tracker_metrics::metric::MetricName` +- `torrust_tracker_metrics::metric::description` +- `torrust_tracker_metrics::metric_collection` +- `torrust_tracker_metrics::metric_collection::Error` +- `torrust_tracker_metrics::metric_collection::aggregate` +- `torrust_tracker_metrics::metric_name` +- `torrust_tracker_metrics::unit::Unit` + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::AnnounceData` +- `torrust_tracker_primitives::AnnounceEvent::Completed` +- `torrust_tracker_primitives::AnnounceEvent::None` +- `torrust_tracker_primitives::AnnounceEvent::Started` +- `torrust_tracker_primitives::AnnounceEvent::Stopped` +- `torrust_tracker_primitives::DurationSinceUnixEpoch` +- `torrust_tracker_primitives::NumberOfBytes::new` +- `torrust_tracker_primitives::PeerId` +- `torrust_tracker_primitives::ScrapeData` +- `torrust_tracker_primitives::peer` +- `torrust_tracker_primitives::peer::PeerAnnouncement` +- `torrust_tracker_primitives::service_binding` +- `torrust_tracker_primitives::service_binding::ServiceBinding` +- `torrust_tracker_primitives::swarm_metadata::AggregateActiveSwarmMetadata` + +#### `torrust-tracker-swarm-coordination-registry` [normal] + +- `torrust_tracker_swarm_coordination_registry::container::SwarmCoordinationRegistryContainer` + +### `bittorrent-udp-tracker-protocol` + +Workspace deps: 1 + +#### `bittorrent-peer-id` [normal] + +_Items not extracted — dependency used without a direct `use` path (macro, re-export, or glob import)._ + +### `torrust-axum-health-check-api-server` + +Workspace deps: 10 + +#### `torrust-axum-health-check-api-server` [dev] + +_No `torrust_axum_health_check_api_server::` references found in `src/` — may be used only in `Cargo.toml` feature flags or `build.rs`._ + +#### `torrust-axum-http-tracker-server` [dev] + +_No `torrust_axum_http_tracker_server::` references found in `src/` — may be used only in `Cargo.toml` feature flags or `build.rs`._ + +#### `torrust-axum-rest-tracker-api-server` [dev] + +_No `torrust_axum_rest_tracker_api_server::` references found in `src/` — may be used only in `Cargo.toml` feature flags or `build.rs`._ + +#### `torrust-tracker-clock` [dev] + +_No `torrust_tracker_clock::` references found in `src/` — may be used only in `Cargo.toml` feature flags or `build.rs`._ + +#### `torrust-tracker-test-helpers` [dev] + +_No `torrust_tracker_test_helpers::` references found in `src/` — may be used only in `Cargo.toml` feature flags or `build.rs`._ + +#### `torrust-udp-tracker-server` [dev] + +_No `torrust_udp_tracker_server::` references found in `src/` — may be used only in `Cargo.toml` feature flags or `build.rs`._ + +#### `torrust-axum-server` [normal] + +- `torrust_axum_server::signals::graceful_shutdown` + +#### `torrust-server-lib` [normal] + +- `torrust_server_lib::logging::Latency` +- `torrust_server_lib::registar` +- `torrust_server_lib::registar::Registar` +- `torrust_server_lib::registar::ServiceRegistry` +- `torrust_server_lib::signals` + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::HealthCheckApi` + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::service_binding` + +### `torrust-axum-http-tracker-server` + +Workspace deps: 13 + +#### `torrust-tracker-clock` [dev] + +- `torrust_tracker_clock::initialize_static` + +#### `torrust-tracker-events` [dev] + +_No `torrust_tracker_events::` references found in `src/` — may be used only in `Cargo.toml` feature flags or `build.rs`._ + +#### `torrust-tracker-test-helpers` [dev] + +- `torrust_tracker_test_helpers::configuration` +- `torrust_tracker_test_helpers::configuration::ephemeral_public` + +#### `bittorrent-http-tracker-core` [normal] + +- `bittorrent_http_tracker_core::container::HttpTrackerCoreContainer` +- `bittorrent_http_tracker_core::event::bus` +- `bittorrent_http_tracker_core::event::sender` +- `bittorrent_http_tracker_core::services::announce` +- `bittorrent_http_tracker_core::services::scrape` +- `bittorrent_http_tracker_core::statistics::event` +- `bittorrent_http_tracker_core::statistics::repository` + +#### `bittorrent-http-tracker-protocol` [normal] + +- `bittorrent_http_tracker_protocol::v1` +- `bittorrent_http_tracker_protocol::v1::query` +- `bittorrent_http_tracker_protocol::v1::requests` +- `bittorrent_http_tracker_protocol::v1::responses` +- `bittorrent_http_tracker_protocol::v1::services` + +#### `bittorrent-tracker-core` [normal] + +- `bittorrent_tracker_core::announce_handler::AnnounceHandler` +- `bittorrent_tracker_core::authentication` +- `bittorrent_tracker_core::authentication::Key` +- `bittorrent_tracker_core::authentication::key` +- `bittorrent_tracker_core::authentication::service` +- `bittorrent_tracker_core::container::TrackerCoreContainer` +- `bittorrent_tracker_core::databases::setup` +- `bittorrent_tracker_core::scrape_handler::ScrapeHandler` +- `bittorrent_tracker_core::statistics::persisted` +- `bittorrent_tracker_core::torrent::repository` +- `bittorrent_tracker_core::whitelist::authorization` +- `bittorrent_tracker_core::whitelist::repository` + +#### `bittorrent-udp-tracker-protocol` [normal] + +_No `bittorrent_udp_tracker_protocol::` references found in `src/` — may be used only in `Cargo.toml` feature flags or `build.rs`._ + +#### `torrust-axum-server` [normal] + +- `torrust_axum_server::custom_axum_server` +- `torrust_axum_server::signals::graceful_shutdown` +- `torrust_axum_server::tsl::make_rust_tls` + +#### `torrust-server-lib` [normal] + +- `torrust_server_lib::logging::Latency` +- `torrust_server_lib::logging::STARTED_ON` +- `torrust_server_lib::registar` +- `torrust_server_lib::registar::Registar` +- `torrust_server_lib::signals` + +#### `torrust-tracker-clock` [normal] + +- `torrust_tracker_clock::initialize_static` + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::Configuration` +- `torrust_tracker_configuration::Configuration::core` +- `torrust_tracker_configuration::DEFAULT_TIMEOUT` +- `torrust_tracker_configuration::TORRENT_PEERS_LIMIT` + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::AnnounceData` +- `torrust_tracker_primitives::PeerId` +- `torrust_tracker_primitives::ScrapeData` +- `torrust_tracker_primitives::peer` +- `torrust_tracker_primitives::service_binding` +- `torrust_tracker_primitives::service_binding::ServiceBinding` +- `torrust_tracker_primitives::swarm_metadata::SwarmMetadata` + +#### `torrust-tracker-swarm-coordination-registry` [normal] + +- `torrust_tracker_swarm_coordination_registry::container::SwarmCoordinationRegistryContainer` + +### `torrust-axum-rest-tracker-api-server` + +Workspace deps: 15 + +#### `torrust-rest-tracker-api-client` [dev] + +- `torrust_rest_tracker_api_client::connection_info` + +#### `torrust-tracker-test-helpers` [dev] + +- `torrust_tracker_test_helpers::configuration::ephemeral_public` + +#### `bittorrent-http-tracker-core` [normal] + +- `bittorrent_http_tracker_core::container::HttpTrackerCoreContainer` +- `bittorrent_http_tracker_core::statistics::repository` + +#### `bittorrent-tracker-core` [normal] + +- `bittorrent_tracker_core::authentication` +- `bittorrent_tracker_core::authentication::Key` +- `bittorrent_tracker_core::authentication::handler` +- `bittorrent_tracker_core::container::TrackerCoreContainer` +- `bittorrent_tracker_core::error::PeerKeyError` +- `bittorrent_tracker_core::statistics::repository` +- `bittorrent_tracker_core::torrent::repository` +- `bittorrent_tracker_core::torrent::services` +- `bittorrent_tracker_core::whitelist::manager` + +#### `bittorrent-udp-tracker-core` [normal] + +- `bittorrent_udp_tracker_core::container::UdpTrackerCoreContainer` +- `bittorrent_udp_tracker_core::initialize_static` +- `bittorrent_udp_tracker_core::services::banning` +- `bittorrent_udp_tracker_core::statistics::repository` + +#### `torrust-axum-server` [normal] + +- `torrust_axum_server::custom_axum_server` +- `torrust_axum_server::signals::graceful_shutdown` +- `torrust_axum_server::tsl::make_rust_tls` + +#### `torrust-rest-tracker-api-client` [normal] + +- `torrust_rest_tracker_api_client::connection_info` + +#### `torrust-rest-tracker-api-core` [normal] + +- `torrust_rest_tracker_api_core::container::TrackerHttpApiCoreContainer` +- `torrust_rest_tracker_api_core::statistics::metrics` +- `torrust_rest_tracker_api_core::statistics::services` + +#### `torrust-server-lib` [normal] + +- `torrust_server_lib::logging::Latency` +- `torrust_server_lib::logging::STARTED_ON` +- `torrust_server_lib::registar` +- `torrust_server_lib::registar::Registar` +- `torrust_server_lib::signals` + +#### `torrust-tracker-clock` [normal] + +- `torrust_tracker_clock::clock` +- `torrust_tracker_clock::clock::stopped` +- `torrust_tracker_clock::conv::convert_from_iso_8601_to_timestamp` +- `torrust_tracker_clock::initialize_static` + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::AccessTokens` +- `torrust_tracker_configuration::HttpApi` +- `torrust_tracker_configuration::HttpApi::tsl_config` + +#### `torrust-tracker-metrics` [normal] + +- `torrust_tracker_metrics::metric_collection::MetricCollection` +- `torrust_tracker_metrics::prometheus::PrometheusSerializable` + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::AnnounceEvent` +- `torrust_tracker_primitives::pagination::Pagination` +- `torrust_tracker_primitives::peer` +- `torrust_tracker_primitives::service_binding` + +#### `torrust-tracker-swarm-coordination-registry` [normal] + +- `torrust_tracker_swarm_coordination_registry::container::SwarmCoordinationRegistryContainer` +- `torrust_tracker_swarm_coordination_registry::statistics::repository` + +#### `torrust-udp-tracker-server` [normal] + +- `torrust_udp_tracker_server::container::UdpTrackerServerContainer` +- `torrust_udp_tracker_server::statistics::repository` + +### `torrust-axum-server` + +Workspace deps: 3 + +#### `torrust-server-lib` [normal] + +- `torrust_server_lib::signals` + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::TslConfig` + +#### `torrust-tracker-located-error` [normal] + +_Items not extracted — dependency used without a direct `use` path (macro, re-export, or glob import)._ + +### `torrust-rest-tracker-api-core` + +Workspace deps: 10 + +#### `torrust-tracker-events` [dev] + +- `torrust_tracker_events::bus::SenderStatus` + +#### `torrust-tracker-test-helpers` [dev] + +- `torrust_tracker_test_helpers::configuration` + +#### `bittorrent-http-tracker-core` [normal] + +- `bittorrent_http_tracker_core::container::HttpTrackerCoreContainer` +- `bittorrent_http_tracker_core::event::bus` +- `bittorrent_http_tracker_core::event::sender` +- `bittorrent_http_tracker_core::statistics::event` +- `bittorrent_http_tracker_core::statistics::repository` + +#### `bittorrent-tracker-core` [normal] + +- `bittorrent_tracker_core::container::TrackerCoreContainer` +- `bittorrent_tracker_core::statistics::repository` +- `bittorrent_tracker_core::torrent::repository` + +#### `bittorrent-udp-tracker-core` [normal] + +- `bittorrent_udp_tracker_core::MAX_CONNECTION_ID_ERRORS_PER_IP` +- `bittorrent_udp_tracker_core::container::UdpTrackerCoreContainer` +- `bittorrent_udp_tracker_core::services::banning` +- `bittorrent_udp_tracker_core::statistics::repository` + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::Configuration` + +#### `torrust-tracker-metrics` [normal] + +- `torrust_tracker_metrics::metric_collection::MetricCollection` + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::swarm_metadata::AggregateActiveSwarmMetadata` + +#### `torrust-tracker-swarm-coordination-registry` [normal] + +- `torrust_tracker_swarm_coordination_registry::container::SwarmCoordinationRegistryContainer` +- `torrust_tracker_swarm_coordination_registry::statistics::repository` + +#### `torrust-udp-tracker-server` [normal] + +- `torrust_udp_tracker_server::container::UdpTrackerServerContainer` +- `torrust_udp_tracker_server::statistics` +- `torrust_udp_tracker_server::statistics::repository` + +### `torrust-server-lib` + +Workspace deps: 1 + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::service_binding::ServiceBinding` + +### `torrust-tracker` + +Workspace deps: 16 + +#### `bittorrent-tracker-client` [dev] + +_No `bittorrent_tracker_client::` references found in `src/` — may be used only in `Cargo.toml` feature flags or `build.rs`._ + +#### `torrust-tracker-test-helpers` [dev] + +- `torrust_tracker_test_helpers::configuration::ephemeral_public` + +#### `bittorrent-http-tracker-core` [normal] + +- `bittorrent_http_tracker_core::container` +- `bittorrent_http_tracker_core::container::HttpTrackerCoreContainer` +- `bittorrent_http_tracker_core::statistics::event` + +#### `bittorrent-tracker-core` [normal] + +- `bittorrent_tracker_core::container::TrackerCoreContainer` +- `bittorrent_tracker_core::statistics::event` +- `bittorrent_tracker_core::statistics::persisted` +- `bittorrent_tracker_core::torrent::manager` + +#### `bittorrent-udp-tracker-core` [normal] + +- `bittorrent_udp_tracker_core::UDP_TRACKER_LOG_TARGET` +- `bittorrent_udp_tracker_core::container` +- `bittorrent_udp_tracker_core::container::UdpTrackerCoreContainer` +- `bittorrent_udp_tracker_core::crypto::keys` +- `bittorrent_udp_tracker_core::initialize_static` +- `bittorrent_udp_tracker_core::statistics::event` + +#### `torrust-axum-health-check-api-server` [normal] + +- `torrust_axum_health_check_api_server::HEALTH_CHECK_API_LOG_TARGET` + +#### `torrust-axum-http-tracker-server` [normal] + +- `torrust_axum_http_tracker_server::HTTP_TRACKER_LOG_TARGET` +- `torrust_axum_http_tracker_server::Version` +- `torrust_axum_http_tracker_server::Version::V1` +- `torrust_axum_http_tracker_server::server` + +#### `torrust-axum-rest-tracker-api-server` [normal] + +- `torrust_axum_rest_tracker_api_server::Version` +- `torrust_axum_rest_tracker_api_server::Version::V1` +- `torrust_axum_rest_tracker_api_server::server` +- `torrust_axum_rest_tracker_api_server::v1::context` + +#### `torrust-axum-server` [normal] + +- `torrust_axum_server::tsl::make_rust_tls` + +#### `torrust-rest-tracker-api-client` [normal] + +- `torrust_rest_tracker_api_client::connection_info` +- `torrust_rest_tracker_api_client::v1::Client` +- `torrust_rest_tracker_api_client::v1::client` + +#### `torrust-rest-tracker-api-core` [normal] + +- `torrust_rest_tracker_api_core::container::TrackerHttpApiCoreContainer` + +#### `torrust-server-lib` [normal] + +- `torrust_server_lib::logging::STARTED_ON` +- `torrust_server_lib::registar::Registar` +- `torrust_server_lib::registar::ServiceRegistrationForm` +- `torrust_server_lib::registar::ServiceRegistry` +- `torrust_server_lib::signals` + +#### `torrust-tracker-clock` [normal] + +- `torrust_tracker_clock::clock` +- `torrust_tracker_clock::clock::Time` +- `torrust_tracker_clock::initialize_static` + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::AccessTokens` +- `torrust_tracker_configuration::Configuration` +- `torrust_tracker_configuration::Core` +- `torrust_tracker_configuration::HealthCheckApi` +- `torrust_tracker_configuration::validator::Validator` + +#### `torrust-tracker-swarm-coordination-registry` [normal] + +- `torrust_tracker_swarm_coordination_registry::container::SwarmCoordinationRegistryContainer` +- `torrust_tracker_swarm_coordination_registry::statistics::activity_metrics_updater` +- `torrust_tracker_swarm_coordination_registry::statistics::event` + +#### `torrust-udp-tracker-server` [normal] + +- `torrust_udp_tracker_server::banning::event` +- `torrust_udp_tracker_server::container::UdpTrackerServerContainer` +- `torrust_udp_tracker_server::server::Server` +- `torrust_udp_tracker_server::server::spawner` +- `torrust_udp_tracker_server::statistics::event` + +### `torrust-tracker-client` + +Workspace deps: 3 + +#### `bittorrent-tracker-client` [normal] + +- `bittorrent_tracker_client::http::client` +- `bittorrent_tracker_client::peer_id::default_production_peer_id` +- `bittorrent_tracker_client::udp` +- `bittorrent_tracker_client::udp::client` + +#### `bittorrent-udp-tracker-protocol` [normal] + +- `bittorrent_udp_tracker_protocol::PeerId` +- `bittorrent_udp_tracker_protocol::Response` +- `bittorrent_udp_tracker_protocol::TransactionId` +- `bittorrent_udp_tracker_protocol::common::InfoHash` + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::DEFAULT_TIMEOUT` + +### `torrust-tracker-clock` + +Workspace deps: 1 + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::DurationSinceUnixEpoch` + +### `torrust-tracker-configuration` + +Workspace deps: 1 + +#### `torrust-tracker-located-error` [normal] + +_Items not extracted — dependency used without a direct `use` path (macro, re-export, or glob import)._ + +### `torrust-tracker-metrics` + +Workspace deps: 1 + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::DurationSinceUnixEpoch` + +### `torrust-tracker-primitives` + +Workspace deps: 2 + +#### `bittorrent-peer-id` [normal] + +_Items not extracted — dependency used without a direct `use` path (macro, re-export, or glob import)._ + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::AnnouncePolicy` + +### `torrust-tracker-swarm-coordination-registry` + +Workspace deps: 6 + +#### `torrust-tracker-test-helpers` [dev] + +_No `torrust_tracker_test_helpers::` references found in `src/` — may be used only in `Cargo.toml` feature flags or `build.rs`._ + +#### `torrust-tracker-clock` [normal] + +- `torrust_tracker_clock::clock` +- `torrust_tracker_clock::clock::Time` +- `torrust_tracker_clock::clock::stopped` +- `torrust_tracker_clock::conv::convert_from_timestamp_to_datetime_utc` + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::TORRENT_PEERS_LIMIT` +- `torrust_tracker_configuration::TrackerPolicy` + +#### `torrust-tracker-events` [normal] + +- `torrust_tracker_events::broadcaster::Broadcaster` +- `torrust_tracker_events::bus::EventBus` +- `torrust_tracker_events::bus::SenderStatus` +- `torrust_tracker_events::receiver::Receiver` +- `torrust_tracker_events::receiver::RecvError` +- `torrust_tracker_events::sender` +- `torrust_tracker_events::sender::Sender` + +#### `torrust-tracker-metrics` [normal] + +- `torrust_tracker_metrics::label` +- `torrust_tracker_metrics::label::LabelSet` +- `torrust_tracker_metrics::label::LabelValue` +- `torrust_tracker_metrics::metric::MetricName` +- `torrust_tracker_metrics::metric::description` +- `torrust_tracker_metrics::metric_collection` +- `torrust_tracker_metrics::metric_collection::Error` +- `torrust_tracker_metrics::metric_name` +- `torrust_tracker_metrics::unit::Unit` + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::AnnounceEvent::Completed` +- `torrust_tracker_primitives::AnnounceEvent::Started` +- `torrust_tracker_primitives::DurationSinceUnixEpoch` +- `torrust_tracker_primitives::NumberOfBytes` +- `torrust_tracker_primitives::NumberOfDownloadsBTreeMap` +- `torrust_tracker_primitives::PeerId` +- `torrust_tracker_primitives::pagination::Pagination` +- `torrust_tracker_primitives::peer` +- `torrust_tracker_primitives::peer::Peer` +- `torrust_tracker_primitives::peer::PeerRole` +- `torrust_tracker_primitives::peer::fixture` +- `torrust_tracker_primitives::swarm_metadata` +- `torrust_tracker_primitives::swarm_metadata::AggregateActiveSwarmMetadata` +- `torrust_tracker_primitives::swarm_metadata::SwarmMetadata` + +### `torrust-tracker-test-helpers` + +Workspace deps: 1 + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::logging::TraceStyle` + +### `torrust-tracker-torrent-repository-benchmarking` + +Workspace deps: 3 + +#### `torrust-tracker-clock` [normal] + +- `torrust_tracker_clock::clock` + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::TrackerPolicy` + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::pagination::Pagination` +- `torrust_tracker_primitives::peer` +- `torrust_tracker_primitives::peer::fixture` +- `torrust_tracker_primitives::swarm_metadata` +- `torrust_tracker_primitives::swarm_metadata::SwarmMetadata` + +### `torrust-udp-tracker-server` + +Workspace deps: 12 + +#### `torrust-tracker-test-helpers` [dev] + +- `torrust_tracker_test_helpers::configuration` +- `torrust_tracker_test_helpers::configuration::ephemeral_public` + +#### `bittorrent-tracker-client` [normal] + +- `bittorrent_tracker_client::udp::client` + +#### `bittorrent-tracker-core` [normal] + +- `bittorrent_tracker_core::MAX_SCRAPE_TORRENTS` +- `bittorrent_tracker_core::announce_handler::AnnounceHandler` +- `bittorrent_tracker_core::container::TrackerCoreContainer` +- `bittorrent_tracker_core::databases::setup` +- `bittorrent_tracker_core::error` +- `bittorrent_tracker_core::scrape_handler::ScrapeHandler` +- `bittorrent_tracker_core::statistics::persisted` +- `bittorrent_tracker_core::torrent::repository` +- `bittorrent_tracker_core::whitelist` +- `bittorrent_tracker_core::whitelist::authorization` +- `bittorrent_tracker_core::whitelist::repository` + +#### `bittorrent-udp-tracker-core` [normal] + +- `bittorrent_udp_tracker_core::UDP_TRACKER_LOG_TARGET` +- `bittorrent_udp_tracker_core::connection_cookie` +- `bittorrent_udp_tracker_core::connection_cookie::gen_remote_fingerprint` +- `bittorrent_udp_tracker_core::connection_cookie::make` +- `bittorrent_udp_tracker_core::container::UdpTrackerCoreContainer` +- `bittorrent_udp_tracker_core::event` +- `bittorrent_udp_tracker_core::event::Event` +- `bittorrent_udp_tracker_core::event::bus` +- `bittorrent_udp_tracker_core::event::sender` +- `bittorrent_udp_tracker_core::initialize_static` +- `bittorrent_udp_tracker_core::services::announce` +- `bittorrent_udp_tracker_core::services::banning` +- `bittorrent_udp_tracker_core::services::connect` +- `bittorrent_udp_tracker_core::services::scrape` +- `bittorrent_udp_tracker_core::statistics::event` + +#### `bittorrent-udp-tracker-protocol` [normal] + +- `bittorrent_udp_tracker_protocol::AnnounceEvent` +- `bittorrent_udp_tracker_protocol::AnnounceInterval` +- `bittorrent_udp_tracker_protocol::AnnounceRequest` +- `bittorrent_udp_tracker_protocol::InfoHash` +- `bittorrent_udp_tracker_protocol::PeerClient` +- `bittorrent_udp_tracker_protocol::Response` +- `bittorrent_udp_tracker_protocol::common::ConnectionId` +- `bittorrent_udp_tracker_protocol::common::InfoHash` +- `bittorrent_udp_tracker_protocol::common::NumberOfBytes` +- `bittorrent_udp_tracker_protocol::common::NumberOfPeers` +- `bittorrent_udp_tracker_protocol::common::PeerId` +- `bittorrent_udp_tracker_protocol::common::Port` +- `bittorrent_udp_tracker_protocol::common::ResponsePeer` +- `bittorrent_udp_tracker_protocol::common::TransactionId` +- `bittorrent_udp_tracker_protocol::request::ConnectRequest` +- `bittorrent_udp_tracker_protocol::request::ScrapeRequest` +- `bittorrent_udp_tracker_protocol::response::AnnounceResponse` +- `bittorrent_udp_tracker_protocol::response::ConnectResponse` +- `bittorrent_udp_tracker_protocol::response::ScrapeResponse` +- `bittorrent_udp_tracker_protocol::response::TorrentScrapeStatistics` + +#### `torrust-server-lib` [normal] + +- `torrust_server_lib::logging::STARTED_ON` +- `torrust_server_lib::registar` +- `torrust_server_lib::registar::Registar` +- `torrust_server_lib::registar::ServiceHealthCheckJob` +- `torrust_server_lib::signals` + +#### `torrust-tracker-clock` [normal] + +- `torrust_tracker_clock::clock` +- `torrust_tracker_clock::clock::Time` +- `torrust_tracker_clock::initialize_static` + +#### `torrust-tracker-configuration` [normal] + +- `torrust_tracker_configuration::Core` + +#### `torrust-tracker-events` [normal] + +- `torrust_tracker_events::broadcaster::Broadcaster` +- `torrust_tracker_events::bus::EventBus` +- `torrust_tracker_events::bus::SenderStatus` +- `torrust_tracker_events::receiver::Receiver` +- `torrust_tracker_events::receiver::RecvError` +- `torrust_tracker_events::sender::SendError` +- `torrust_tracker_events::sender::Sender` + +#### `torrust-tracker-metrics` [normal] + +- `torrust_tracker_metrics::label` +- `torrust_tracker_metrics::label::LabelSet` +- `torrust_tracker_metrics::label_name` +- `torrust_tracker_metrics::metric::MetricName` +- `torrust_tracker_metrics::metric::description` +- `torrust_tracker_metrics::metric_collection` +- `torrust_tracker_metrics::metric_collection::Error` +- `torrust_tracker_metrics::metric_collection::aggregate` +- `torrust_tracker_metrics::metric_name` +- `torrust_tracker_metrics::unit::Unit` + +#### `torrust-tracker-primitives` [normal] + +- `torrust_tracker_primitives::AnnounceData` +- `torrust_tracker_primitives::DurationSinceUnixEpoch` +- `torrust_tracker_primitives::PeerId` +- `torrust_tracker_primitives::ScrapeData` +- `torrust_tracker_primitives::peer::fixture` +- `torrust_tracker_primitives::service_binding` +- `torrust_tracker_primitives::service_binding::ServiceBinding` +- `torrust_tracker_primitives::swarm_metadata::AggregateActiveSwarmMetadata` +- `torrust_tracker_primitives::swarm_metadata::SwarmMetadata` + +#### `torrust-tracker-swarm-coordination-registry` [normal] + +- `torrust_tracker_swarm_coordination_registry::container::SwarmCoordinationRegistryContainer` + +--- + +## Observations + +### Known thin dependencies (confirmed by scan) + +- **`torrust-tracker-clock` → `torrust-tracker-primitives`**: only `DurationSinceUnixEpoch` + imported. This is the thin dep addressed by SI-02. After SI-02 the import will move to a + local definition and the dependency edge will be removed. + +- **`torrust-tracker-configuration` → `torrust-tracker-clock`**: no direct `use` statement + found — likely `DEFAULT_TIMEOUT` is imported via a fully-qualified path or the scan missed + it. SI-03 moves `DEFAULT_TIMEOUT` from `configuration` to `clock`; once done all + consumers listed below switch to `torrust_clock::DEFAULT_TIMEOUT`. + +### New findings + +#### F-01 · Multiple packages depend on `torrust-tracker-configuration` only for `DEFAULT_TIMEOUT` + +After SI-03 moves `DEFAULT_TIMEOUT` into `torrust-tracker-clock`, these packages will need +to update their import path. More importantly, two of them are tracker-client packages that +should not need to know about tracker configuration at all: + +| Package | Dep kind | Import found | Notes | +| ---------------------------------- | -------- | ------------------------------------------------ | --------------------------------------------------------------------------------- | +| `torrust-axum-http-tracker-server` | normal | `torrust_tracker_configuration::DEFAULT_TIMEOUT` | Will migrate to `torrust_clock::` post SI-03 | +| `bittorrent-tracker-client` | normal | `torrust_tracker_configuration::DEFAULT_TIMEOUT` | Layer violation: client pkg depends on tracker config only for a timeout constant | +| `torrust-tracker-client` | normal | `torrust_tracker_configuration::DEFAULT_TIMEOUT` | Same layer violation | + +SI-03 resolves the coupling for the server packages. For the client packages, the move to +`torrust-clock` eliminates the dependency on `torrust-tracker-configuration` entirely. + +#### F-02 · `torrust-tracker-metrics` → `torrust-tracker-primitives`: only `DurationSinceUnixEpoch` + +`torrust-tracker-metrics` imports only `torrust_tracker_primitives::DurationSinceUnixEpoch`. +After SI-02 moves that type to `torrust-tracker-clock`, this dependency edge could also +be removed — `torrust-tracker-metrics` would instead depend on `torrust-clock` (or have no +dep at all if the type alias is defined locally). Worth tracking when SI-02 is implemented. + +#### F-03 · `torrust-tracker-primitives` → `torrust-tracker-configuration`: only `AnnouncePolicy` + +`torrust-tracker-primitives` imports `torrust_tracker_configuration::AnnouncePolicy`. A +"primitives" package depending on a "configuration" package is a layer-order concern: +`AnnouncePolicy` is a domain concept (the announce interval / min-interval policy) that +arguably belongs in `primitives` (or a protocol layer), not in configuration. If +`AnnouncePolicy` were defined in `primitives`, the dependency direction would be reversed +and `configuration` would depend on `primitives` (as expected). Warrants a dedicated +subissue. + +#### F-04 · `torrust-server-lib` → `torrust-tracker-primitives`: only `ServiceBinding` + +`torrust-server-lib` (a generic server library) imports only +`torrust_tracker_primitives::service_binding::ServiceBinding`. A generic library depending +on a tracker-specific `primitives` crate for a network binding type is a layer violation. +`ServiceBinding` is likely general enough to live in `torrust-server-lib` itself or in a +separate generic networking crate. Warrants a dedicated subissue. + +#### F-05 · `bittorrent-tracker-core` → `torrust-rest-tracker-api-client` [dev]: no uses found in `src/` + +The declared dev dependency on `torrust-rest-tracker-api-client` has no `use` statements +in `src/`. The usage is almost certainly in integration tests outside `src/` (e.g. in +`tests/`). This is a known layer violation flagged in the EPIC's extraction ordering table +("a layer violation worth resolving before extraction"). The script's scan is limited to +`src/`; the actual import in `tests/` was not captured. + +#### F-06 · Several packages have dev deps with no `src/` references + +The following dev dependency edges had no import paths found in `src/`. In all cases the +usage is likely in integration tests under a `tests/` directory, which the script does not +scan. This is a known limitation of the current scan. + +- `bittorrent-udp-tracker-core` → `torrust-tracker-test-helpers` [dev] +- `torrust-tracker-swarm-coordination-registry` → `torrust-tracker-test-helpers` [dev] +- `torrust-axum-health-check-api-server` → all dev deps (6 packages) + +### Findings resolution + +All findings have been triaged and integrated into the EPIC subissue plan. + +| Finding | Resolution | +| ------- | --------------------------------------------------------------------------------------------------------------------------- | +| F-01 | Side effect of SI-03; documented in SI-03 spec. Both client packages drop dep on `torrust-tracker-configuration`. | +| F-02 | Added to SI-02 scope (T9 and updated AC). `torrust-tracker-metrics` dep on `torrust-tracker-primitives` removed after move. | +| F-03 | → **SI-04**: Move `AnnouncePolicy` from `torrust-tracker-configuration` to `torrust-tracker-primitives`. | +| F-04 | → **SI-05**: Create `torrust-net-primitives` package and move `ServiceBinding` from `torrust-tracker-primitives`. | +| F-05 | → **SI-06**: Resolve `bittorrent-tracker-core` ↔ `torrust-rest-tracker-api-client` layer violation. | diff --git a/project-words.txt b/project-words.txt index 769d83b62..4ec5da415 100644 --- a/project-words.txt +++ b/project-words.txt @@ -10,6 +10,7 @@ Aideq alekitto analyse appuser +argjson Arvid asdh ASMS @@ -100,10 +101,11 @@ fract Freebox frontmatter Frostegård -gecos Garnham +gecos Gibibytes Glrg +Graphviz Grcov hasher healthcheck @@ -113,6 +115,7 @@ hexlify hlocalhost hmac hotspot +hotspots httpclientpeerid Hydranode hyperium @@ -162,8 +165,8 @@ Mebibytes metainfo middlewares millis -mktemp misresolved +mktemp mmap mmdb mockall @@ -174,7 +177,6 @@ multimap myacicontext mysqladmin mysqld -ñaca Naim nanos newkey @@ -196,6 +198,7 @@ obra oneline oneshot openmetrics +organisation ostr Pando parallelise @@ -211,6 +214,7 @@ pkey porti prealloc println +prioritise programatik proot proto @@ -250,6 +254,7 @@ rsplit rstest rusqlite rustc +rustdoc RUSTDOCFLAGS RUSTFLAGS rustfmt @@ -341,6 +346,7 @@ vtable Vuze wakelist wakeup +walkdir webtorrent WEBUI Weidendorfer @@ -356,3 +362,4 @@ xxxxxxxxxxxxxxxxxxxxd yyyyyyyyyyyyyyyyyyyyd zerocopy zstd +ñaca From 48bc320dd76f0fb19930978d9a3979dfcd1eb438 Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Mon, 18 May 2026 12:51:43 +0100 Subject: [PATCH 03/11] docs(issues): add move subissues and renumber EPIC #1669 subissues to sequential order MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add three new subissue specs identified from coupling analysis findings: - SI-04: Move AnnouncePolicy from torrust-tracker-configuration to torrust-tracker-primitives (F-03) - SI-05: Create torrust-net-primitives and move ServiceBinding (F-04) - SI-06: Resolve bittorrent-tracker-core stale dev dep on torrust-rest-tracker-api-client (F-05 — audit found dep unused, fix is a one-line Cargo.toml deletion) Also add SI-11: Update all package READMEs (docs gate before extraction). Renumber SI-04–SI-15 to follow declared priority rules (M → U → P → E) with no gaps: - SI-04–SI-06: move subissues (new, from F-03/F-04/F-05) - SI-07–SI-10: rename subissues (align prefix, metrics, clock, located-error) - SI-11: README update - SI-12–SI-15: extraction subissues (bencode, clock, metrics, tracker-client) Extend SI-02 and SI-03 scope with findings from coupling report (F-01/F-02). Update EPIC.md quick list, details table, notes, and Desired Package State. Update workspace-coupling-report.md findings resolution table (F-03→SI-04, F-04→SI-05, F-05→SI-06). --- ...ation-since-unix-epoch-to-torrust-clock.md | 33 ++-- ...ult-timeout-from-configuration-to-clock.md | 28 ++-- ...ce-policy-to-torrust-tracker-primitives.md | 141 +++++++++++++++++ ...net-primitives-and-move-service-binding.md | 148 ++++++++++++++++++ ...t-tracker-core-rest-api-layer-violation.md | 125 +++++++++++++++ ...refix-rename-tracker-specific-packages.md} | 2 +- ...ust-tracker-metrics-to-torrust-metrics.md} | 6 +- ...torrust-tracker-clock-to-torrust-clock.md} | 6 +- ...located-error-to-torrust-located-error.md} | 2 +- .../1669-11-update-all-package-readmes.md | 127 +++++++++++++++ ...ker-contrib-bencode-to-torrust-bencode.md} | 2 +- ...tract-torrust-clock-to-standalone-repo.md} | 6 +- ...act-torrust-metrics-to-standalone-repo.md} | 8 +- ...rust-tracker-client-to-standalone-repo.md} | 2 +- .../open/1669-overhaul-packages/EPIC.md | 101 ++++++++---- 15 files changed, 664 insertions(+), 73 deletions(-) create mode 100644 docs/issues/drafts/1669-04-move-announce-policy-to-torrust-tracker-primitives.md create mode 100644 docs/issues/drafts/1669-05-create-torrust-net-primitives-and-move-service-binding.md create mode 100644 docs/issues/drafts/1669-06-resolve-bittorrent-tracker-core-rest-api-layer-violation.md rename docs/issues/drafts/{1669-04-align-torrust-prefix-rename-tracker-specific-packages.md => 1669-07-align-torrust-prefix-rename-tracker-specific-packages.md} (99%) rename docs/issues/drafts/{1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md => 1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md} (96%) rename docs/issues/drafts/{1669-06-rename-torrust-tracker-clock-to-torrust-clock.md => 1669-09-rename-torrust-tracker-clock-to-torrust-clock.md} (97%) rename docs/issues/drafts/{1669-07-rename-torrust-tracker-located-error-to-torrust-located-error.md => 1669-10-rename-torrust-tracker-located-error-to-torrust-located-error.md} (99%) create mode 100644 docs/issues/drafts/1669-11-update-all-package-readmes.md rename docs/issues/drafts/{1669-08-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md => 1669-12-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md} (99%) rename docs/issues/drafts/{1669-09-extract-torrust-clock-to-standalone-repo.md => 1669-13-extract-torrust-clock-to-standalone-repo.md} (97%) rename docs/issues/drafts/{1669-10-extract-torrust-metrics-to-standalone-repo.md => 1669-14-extract-torrust-metrics-to-standalone-repo.md} (96%) rename docs/issues/drafts/{1669-11-extract-torrust-tracker-client-to-standalone-repo.md => 1669-15-extract-torrust-tracker-client-to-standalone-repo.md} (99%) 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 index 2eae8838d..424d5be41 100644 --- 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 @@ -7,7 +7,7 @@ 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 +last-updated-utc: 2026-05-18 00:00 semantic-links: skill-links: - create-issue @@ -17,7 +17,7 @@ semantic-links: - 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 + - docs/issues/drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md --- @@ -47,7 +47,7 @@ itself (`fn now() -> DurationSinceUnixEpoch`) and in the conversion helpers 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)), +[1669-09-rename-torrust-tracker-clock-to-torrust-clock.md](1669-09-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. @@ -66,7 +66,7 @@ consumers have been migrated to `torrust_clock::DurationSinceUnixEpoch`, the cop `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)) +[1669-09-rename-torrust-tracker-clock-to-torrust-clock.md](1669-09-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) @@ -85,6 +85,8 @@ This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) - 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. +- Update `torrust-tracker-metrics` to import `DurationSinceUnixEpoch` from `torrust-clock` + instead of `torrust-tracker-primitives`, eliminating that dependency edge entirely (see F-02). ### Out of Scope @@ -98,16 +100,17 @@ This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) 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` | +| 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` | +| T9 | TODO | Update `torrust-tracker-metrics`: replace import of `DurationSinceUnixEpoch` from `torrust_tracker_primitives` with `torrust_clock`; remove `torrust-tracker-primitives` dep from its `Cargo.toml` if no longer needed | `cargo build -p torrust-tracker-metrics` succeeds; `cargo machete -p torrust-tracker-metrics` reports no unused deps | ## Progress Tracking @@ -138,6 +141,8 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. - [ ] 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`). +- [ ] `torrust-tracker-metrics` no longer lists `torrust-tracker-primitives` as a dependency + (or only lists it for non-`DurationSinceUnixEpoch` reasons). - [ ] `cargo build --workspace` succeeds with zero errors. - [ ] `cargo test --workspace` passes with zero failures. - [ ] `linter all` exits with code `0`. 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 index af6f604f8..28f88538e 100644 --- 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 @@ -7,7 +7,7 @@ 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 +last-updated-utc: 2026-05-18 00:00 semantic-links: skill-links: - create-issue @@ -45,6 +45,11 @@ 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. +**Side effect (F-01)**: two client packages (`bittorrent-tracker-client` and +`torrust-tracker-client` in `console/tracker-client`) depend on `torrust-tracker-configuration` +solely for `DEFAULT_TIMEOUT`. After this move both clients can drop that dependency entirely, +eliminating a layer violation where client packages depend on the tracker configuration crate. + **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. @@ -62,6 +67,8 @@ This issue is a subissue of EPIC #1669 (Overhaul: Packages). 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 that `console/tracker-client/Cargo.toml` also no longer needs `torrust-tracker-configuration` + after the import update; drop it if confirmed. - Verify the workspace builds and all tests pass. ### Out of Scope @@ -75,14 +82,15 @@ This issue is a subissue of EPIC #1669 (Overhaul: Packages). 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` | +| 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 | Verify `console/tracker-client/Cargo.toml` no longer needs `torrust-tracker-configuration`; drop it | `cargo build -p torrust-tracker-client` succeeds; `cargo machete` reports no unused dep | +| T6 | TODO | Run `cargo build --workspace` and `cargo test --workspace` | Clean build; all tests pass | +| T7 | TODO | Run `linter all` | Exit code `0` | **Source files to update in T3** (9 files): @@ -122,6 +130,8 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. - [ ] `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`. +- [ ] `console/tracker-client/Cargo.toml` no longer lists `torrust-tracker-configuration` + (confirmed: `DEFAULT_TIMEOUT` was its only use). - [ ] `cargo build --workspace` succeeds with zero errors. - [ ] `cargo test --workspace` passes with zero failures. - [ ] `linter all` exits with code `0`. diff --git a/docs/issues/drafts/1669-04-move-announce-policy-to-torrust-tracker-primitives.md b/docs/issues/drafts/1669-04-move-announce-policy-to-torrust-tracker-primitives.md new file mode 100644 index 000000000..ae36c2e47 --- /dev/null +++ b/docs/issues/drafts/1669-04-move-announce-policy-to-torrust-tracker-primitives.md @@ -0,0 +1,141 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p2 +github-issue: null +spec-path: docs/issues/drafts/1669-04-move-announce-policy-to-torrust-tracker-primitives.md +branch: null +related-pr: null +last-updated-utc: 2026-05-18 00:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - packages/configuration/src/lib.rs + - packages/primitives/src/lib.rs + - packages/primitives/Cargo.toml + - docs/issues/open/1669-overhaul-packages/EPIC.md + - docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md +--- + + + +# Issue #[To be assigned] - Move `AnnouncePolicy` from `torrust-tracker-configuration` to `torrust-tracker-primitives` + +## Goal + +Move the `AnnouncePolicy` struct from `torrust-tracker-configuration` into +`torrust-tracker-primitives`, reversing an inverted dependency where a `primitives` package +depends on a `configuration` package. After the move, `torrust-tracker-configuration` depends +on `torrust-tracker-primitives` for `AnnouncePolicy`, which is the natural direction. + +## Background + +`AnnouncePolicy` (min/max announce intervals) is a domain concept — it describes the peer +communication policy for the BitTorrent announce cycle. Domain concepts belong in `primitives`, +not in `configuration`, which should be concerned only with config-file parsing and environment +variable wiring. + +The coupling analysis (F-03) found that `torrust-tracker-primitives` imports +`torrust_tracker_configuration::AnnouncePolicy` — meaning a `primitives` package depends on a +`configuration` package. This is an inverted dependency: `primitives` should sit at the bottom +of the dependency graph, with `configuration` depending on it, not the reverse. + +Moving `AnnouncePolicy` to `primitives` fixes the inversion: + +- Before: `primitives` → `configuration` (for `AnnouncePolicy`) +- After: `configuration` → `primitives` (for `AnnouncePolicy`, among other types) + +Both packages (`torrust-tracker-primitives` and `torrust-tracker-configuration`) are published +to crates.io. Removing `AnnouncePolicy` from `torrust-tracker-configuration` is a semver +breaking change for that crate; it will require a major version bump when published. Within +this workspace, at version `3.0.0-develop`, the change is expected and planned. + +This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) +(Overhaul: Packages). + +## Scope + +### In Scope + +- Move the `AnnouncePolicy` struct (and any directly associated types or impl blocks) from + `packages/configuration/src/` to `packages/primitives/src/`. +- Add `torrust-tracker-configuration` as a dependency of `torrust-tracker-primitives` + is removed; `torrust-tracker-primitives` must not depend on `torrust-tracker-configuration`. +- Update `packages/configuration` to import `AnnouncePolicy` from `torrust-tracker-primitives`. +- Update all other workspace files that import `AnnouncePolicy` from + `torrust_tracker_configuration` to import it from `torrust_tracker_primitives`. +- Verify the workspace builds and all tests pass. + +### Out of Scope + +- Any rename of `AnnouncePolicy` or changes to its fields. +- Publishing a new crates.io version; the semver bump is handled in the release cycle. +- Extracting `torrust-tracker-primitives` to a standalone repository (a later subissue). + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| T1 | TODO | Locate all definition and usage sites of `AnnouncePolicy` across the workspace | `grep -r "AnnouncePolicy" . --include="*.rs"` — build a full consumer list | +| T2 | TODO | Move `AnnouncePolicy` definition to `packages/primitives/src/` (e.g. `primitives/src/announce_policy.rs`) | Public module exported from `packages/primitives/src/lib.rs` | +| T3 | TODO | Remove `AnnouncePolicy` from `packages/configuration/src/` | Definition gone; re-export or direct dep on `torrust-tracker-primitives` added to configuration | +| T4 | TODO | Add `torrust-tracker-primitives` as a dep of `packages/configuration/Cargo.toml` if not already present | `torrust-tracker-primitives` in `[dependencies]` | +| T5 | TODO | Remove `torrust-tracker-configuration` dep from `packages/primitives/Cargo.toml` if `AnnouncePolicy` was its sole reason | `cargo machete` reports no unused dep | +| T6 | TODO | Update all workspace files that import `AnnouncePolicy` from `torrust_tracker_configuration` to use `torrust_tracker_primitives` | One-line change per file | +| T7 | TODO | Run `cargo build --workspace` and `cargo test --workspace` | Clean build; all tests pass | +| T8 | TODO | Run `linter all` | Exit code `0` | + +## 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-18 00:00 UTC - josecelano - Spec drafted as subissue of EPIC #1669, addressing F-03 + from the coupling analysis report. + +## Acceptance Criteria + +- [ ] `packages/primitives/src/` defines `AnnouncePolicy` and exports it publicly. +- [ ] `packages/primitives/Cargo.toml` does not list `torrust-tracker-configuration` as a dependency. +- [ ] `packages/configuration/src/` no longer defines `AnnouncePolicy`; it imports from `torrust-tracker-primitives`. +- [ ] No workspace file imports `AnnouncePolicy` from `torrust_tracker_configuration` + (all migrated to `torrust_tracker_primitives` or re-exported through it). +- [ ] `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` + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command / Steps | Expected Result | Status | Evidence | +| --- | ------------------------------------------------------------ | ---------------------------------------------------------------------------- | ----------------------- | ------ | -------- | +| M1 | No workspace import of `AnnouncePolicy` from `configuration` | `grep -r "torrust_tracker_configuration::AnnouncePolicy" . --include="*.rs"` | Zero matches | TODO | | +| M2 | `primitives` exports `AnnouncePolicy` | `grep "AnnouncePolicy" packages/primitives/src/lib.rs` | `pub` declaration found | TODO | | +| M3 | `primitives` dep list does not include `configuration` | `grep "torrust-tracker-configuration" packages/primitives/Cargo.toml` | Zero matches | TODO | | diff --git a/docs/issues/drafts/1669-05-create-torrust-net-primitives-and-move-service-binding.md b/docs/issues/drafts/1669-05-create-torrust-net-primitives-and-move-service-binding.md new file mode 100644 index 000000000..3dcf93221 --- /dev/null +++ b/docs/issues/drafts/1669-05-create-torrust-net-primitives-and-move-service-binding.md @@ -0,0 +1,148 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p2 +github-issue: null +spec-path: docs/issues/drafts/1669-05-create-torrust-net-primitives-and-move-service-binding.md +branch: null +related-pr: null +last-updated-utc: 2026-05-18 00:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - packages/primitives/src/service_binding.rs + - packages/primitives/Cargo.toml + - packages/server-lib/Cargo.toml + - docs/issues/open/1669-overhaul-packages/EPIC.md + - docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md +--- + + + +# Issue #[To be assigned] - Create `torrust-net-primitives` and move `ServiceBinding` from `torrust-tracker-primitives` + +## Goal + +Create a new `torrust-net-primitives` package containing generic networking primitives (starting +with `ServiceBinding`) and move `ServiceBinding` out of `torrust-tracker-primitives` into this +new crate. `torrust-server-lib` then depends on `torrust-net-primitives` instead of +`torrust-tracker-primitives`, breaking an unnecessary coupling. + +## Background + +The coupling analysis (F-04) found that `torrust-server-lib` depends on +`torrust-tracker-primitives` solely to import `ServiceBinding` — a struct representing a +network address binding (socket address at which a service listens). `torrust-server-lib` is a +generic server utility library with no tracker-specific concerns; pulling in the entire +`torrust-tracker-*` primitives crate for one generic networking type is wasteful and semantically +misleading. + +`ServiceBinding` is a very generic concept that can be reused across the Torrust organisation, +not just in the tracker. Creating a dedicated `torrust-net-primitives` crate makes the type +available to any Torrust project without a `torrust-tracker-*` dependency. + +Both `torrust-tracker-primitives` (source) and the new `torrust-net-primitives` (destination) +are intended to be published to crates.io. Removing `ServiceBinding` from +`torrust-tracker-primitives` is a semver breaking change; a major version bump will be needed +when the published crate is updated. Within this workspace at version `3.0.0-develop`, the +change is expected and planned. + +This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) +(Overhaul: Packages). + +## Scope + +### In Scope + +- Create `packages/net-primitives/` with a minimal `Cargo.toml` (`name = "torrust-net-primitives"`, + `publish = true`) and `src/lib.rs`. +- Move `ServiceBinding` (and its module `service_binding`) from `packages/primitives/` to + `packages/net-primitives/`. +- Add `torrust-net-primitives` to the workspace `[members]` in `Cargo.toml`. +- Update `packages/server-lib/Cargo.toml` to depend on `torrust-net-primitives` instead of + `torrust-tracker-primitives`. +- Remove `torrust-tracker-primitives` dep from `packages/server-lib/Cargo.toml` if + `ServiceBinding` was its only reason. +- Update all workspace files that import `ServiceBinding` from `torrust_tracker_primitives` to + import from `torrust_net_primitives`. +- Verify the workspace builds and all tests pass. + +### Out of Scope + +- Moving other types from `torrust-tracker-primitives` into `torrust-net-primitives`; this + subissue focuses only on `ServiceBinding`. +- Publishing `torrust-net-primitives` to crates.io; that is handled in the release cycle. +- Removing `ServiceBinding` from `torrust-tracker-primitives` for external consumers; the + crates.io semver bump is deferred. + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------ | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| T1 | TODO | Locate all usage sites of `ServiceBinding` in the workspace | `grep -r "ServiceBinding" . --include="*.rs"` — build full consumer list | +| T2 | TODO | Create `packages/net-primitives/Cargo.toml` and `src/lib.rs` | `name = "torrust-net-primitives"`, `publish = true`; inherits workspace `edition`/`rust-version` | +| T3 | TODO | Add `packages/net-primitives` to workspace `[members]` in root `Cargo.toml` | `cargo build -p torrust-net-primitives` succeeds | +| T4 | TODO | Move `service_binding` module to `packages/net-primitives/src/` | Module exported from `packages/net-primitives/src/lib.rs` | +| T5 | TODO | Remove `service_binding` module from `packages/primitives/src/` | Module and re-export gone; `packages/primitives` no longer exposes `ServiceBinding` | +| T6 | TODO | Update `packages/server-lib/Cargo.toml`: replace `torrust-tracker-primitives` dep with `torrust-net-primitives` | `cargo build -p torrust-server-lib` succeeds; `cargo machete` clean | +| T7 | TODO | Update all other workspace files importing `ServiceBinding` from `torrust_tracker_primitives` to `torrust_net_primitives` | One-line change per file | +| T8 | TODO | Run `cargo build --workspace` and `cargo test --workspace` | Clean build; all tests pass | +| T9 | TODO | Run `linter all` | Exit code `0` | + +## Progress Tracking + +### Workflow Checkpoints + +- [ ] Spec drafted in `docs/issues/drafts/` +- [ ] Spec reviewed and approved by user/maintainer +- [x] Package name confirmed: `torrust-net-primitives` +- [ ] 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-18 00:00 UTC - josecelano - Spec drafted as subissue of EPIC #1669, addressing F-04 + from the coupling analysis report. Package name `torrust-net-primitives` is a proposal pending + confirmation. + +## Acceptance Criteria + +- [ ] `packages/net-primitives/` exists and is a member of the workspace. +- [ ] `torrust-net-primitives` exports `ServiceBinding` publicly. +- [ ] `packages/primitives/src/` no longer defines `ServiceBinding`. +- [ ] `packages/server-lib/Cargo.toml` does not list `torrust-tracker-primitives` as a dependency + (replaced by `torrust-net-primitives`). +- [ ] No workspace file imports `ServiceBinding` from `torrust_tracker_primitives`. +- [ ] `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` + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command / Steps | Expected Result | Status | Evidence | +| --- | ----------------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------- | ------ | -------- | +| M1 | No workspace import of `ServiceBinding` from `tracker_primitives` | `grep -r "torrust_tracker_primitives::.*ServiceBinding" . --include="*.rs"` | Zero matches | TODO | | +| M2 | `torrust-net-primitives` exports `ServiceBinding` | `grep "ServiceBinding" packages/net-primitives/src/lib.rs` | `pub` declaration found | TODO | | +| M3 | `server-lib` no longer depends on `tracker-primitives` | `grep "torrust-tracker-primitives" packages/server-lib/Cargo.toml` | Zero matches | TODO | | diff --git a/docs/issues/drafts/1669-06-resolve-bittorrent-tracker-core-rest-api-layer-violation.md b/docs/issues/drafts/1669-06-resolve-bittorrent-tracker-core-rest-api-layer-violation.md new file mode 100644 index 000000000..12133ed32 --- /dev/null +++ b/docs/issues/drafts/1669-06-resolve-bittorrent-tracker-core-rest-api-layer-violation.md @@ -0,0 +1,125 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p2 +github-issue: null +spec-path: docs/issues/drafts/1669-06-resolve-bittorrent-tracker-core-rest-api-layer-violation.md +branch: null +related-pr: null +last-updated-utc: 2026-05-18 12:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - packages/tracker-core/Cargo.toml + - docs/issues/open/1669-overhaul-packages/EPIC.md + - docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md +--- + + + +# Issue #[To be assigned] - Resolve `bittorrent-tracker-core` ↔ `torrust-rest-tracker-api-client` layer violation + +## Goal + +Remove the stale dev dependency from `bittorrent-tracker-core` on +`torrust-rest-tracker-api-client`. A pre-implementation audit revealed that the dependency is +declared in `packages/tracker-core/Cargo.toml` but is never imported or used anywhere in +`src/` or `tests/`. The fix is a one-line `Cargo.toml` deletion. + +## Background + +The coupling analysis (F-05) found: + +> `bittorrent-tracker-core` → `torrust-rest-tracker-api-client` [dev] + +The entry was listed in `[dev-dependencies]` of `packages/tracker-core/Cargo.toml` (line 48), +which caused the coupling tool to report it as a layer violation. However, auditing +`packages/tracker-core/tests/` and `packages/tracker-core/src/` shows **zero uses** of +`torrust_rest_tracker_api_client` anywhere in the crate. The dependency is dead — left over +from a previous refactor. + +No code movement or extraction is needed. `cargo machete` would also flag this as an unused +dependency. + +This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) +(Overhaul: Packages). + +## Scope + +### In Scope + +- Remove `torrust-rest-tracker-api-client` from `packages/tracker-core/Cargo.toml` + `[dev-dependencies]`. +- Verify the workspace builds and all tests pass. + +### Out of Scope + +- Extracting `bittorrent-tracker-core` to a standalone repository (a separate, later subissue). +- Any code movement or refactoring — the dependency is unused, so no consumers need updating. + +## Open Questions + +None. Pre-implementation audit confirmed the dependency is unused. + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------ | ----------------------------------------------------------------------------------------------------- | --------------------------- | +| T1 | TODO | Remove `torrust-rest-tracker-api-client` from `packages/tracker-core/Cargo.toml` `[dev-dependencies]` | One-line deletion | +| T2 | TODO | Run `cargo build --workspace` and `cargo test --workspace` | Clean build; all tests pass | +| T3 | TODO | Run `linter all` | Exit code `0` | + +## 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-18 00:00 UTC - josecelano - Spec drafted as subissue of EPIC #1669, addressing F-05 + from the coupling analysis report. Initially assumed code extraction was needed. +- 2026-05-18 12:00 UTC - josecelano - Audit confirmed the dependency is unused (zero imports + in `src/` and `tests/`). Spec revised: no extraction required; fix is a one-line `Cargo.toml` + deletion. + +## Acceptance Criteria + +- [ ] `packages/tracker-core/Cargo.toml` does not list `torrust-rest-tracker-api-client` in + `[dev-dependencies]`. +- [ ] All `bittorrent-tracker-core` integration tests still compile and pass. +- [ ] `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` + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command / Steps | Expected Result | Status | Evidence | +| --- | --------------------------------------------------------- | ------------------------------------------------------------------------- | --------------- | ------ | -------- | +| M1 | No dev dep on `rest-tracker-api-client` in `tracker-core` | `grep "torrust-rest-tracker-api-client" packages/tracker-core/Cargo.toml` | Zero matches | TODO | | +| M2 | `bittorrent-tracker-core` integration tests pass | `cargo test -p bittorrent-tracker-core --tests` | All pass | TODO | | diff --git a/docs/issues/drafts/1669-04-align-torrust-prefix-rename-tracker-specific-packages.md b/docs/issues/drafts/1669-07-align-torrust-prefix-rename-tracker-specific-packages.md similarity index 99% rename from docs/issues/drafts/1669-04-align-torrust-prefix-rename-tracker-specific-packages.md rename to docs/issues/drafts/1669-07-align-torrust-prefix-rename-tracker-specific-packages.md index b2d0617ac..2cda587dd 100644 --- a/docs/issues/drafts/1669-04-align-torrust-prefix-rename-tracker-specific-packages.md +++ b/docs/issues/drafts/1669-07-align-torrust-prefix-rename-tracker-specific-packages.md @@ -4,7 +4,7 @@ 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 +spec-path: docs/issues/drafts/1669-07-align-torrust-prefix-rename-tracker-specific-packages.md branch: null related-pr: null last-updated-utc: 2026-05-15 12:00 diff --git a/docs/issues/drafts/1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md b/docs/issues/drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md similarity index 96% rename from docs/issues/drafts/1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md rename to docs/issues/drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md index 26267fa79..0a2660e2b 100644 --- a/docs/issues/drafts/1669-05-rename-torrust-tracker-metrics-to-torrust-metrics.md +++ b/docs/issues/drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md @@ -4,7 +4,7 @@ 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 +spec-path: docs/issues/drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md branch: null related-pr: null last-updated-utc: 2026-05-15 12:00 @@ -42,7 +42,7 @@ 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)). + (see [1669-14-extract-torrust-metrics-to-standalone-repo.md](1669-14-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. @@ -65,7 +65,7 @@ This issue is a subissue of EPIC #1669 (Overhaul: Packages). ### 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). + [1669-14-extract-torrust-metrics-to-standalone-repo.md](1669-14-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. diff --git a/docs/issues/drafts/1669-06-rename-torrust-tracker-clock-to-torrust-clock.md b/docs/issues/drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md similarity index 97% rename from docs/issues/drafts/1669-06-rename-torrust-tracker-clock-to-torrust-clock.md rename to docs/issues/drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md index 1c2ae81a8..82dd4dd10 100644 --- a/docs/issues/drafts/1669-06-rename-torrust-tracker-clock-to-torrust-clock.md +++ b/docs/issues/drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md @@ -4,7 +4,7 @@ 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 +spec-path: docs/issues/drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md branch: null related-pr: null last-updated-utc: 2026-05-15 12:00 @@ -42,7 +42,7 @@ 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)). + (see [1669-13-extract-torrust-clock-to-standalone-repo.md](1669-13-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 @@ -88,7 +88,7 @@ This issue is a subissue of EPIC #1669 (Overhaul: Packages). ### 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). + [1669-13-extract-torrust-clock-to-standalone-repo.md](1669-13-extract-torrust-clock-to-standalone-repo.md). - Changes to the crate's API or behaviour. ### Companion work (other repositories) diff --git a/docs/issues/drafts/1669-07-rename-torrust-tracker-located-error-to-torrust-located-error.md b/docs/issues/drafts/1669-10-rename-torrust-tracker-located-error-to-torrust-located-error.md similarity index 99% rename from docs/issues/drafts/1669-07-rename-torrust-tracker-located-error-to-torrust-located-error.md rename to docs/issues/drafts/1669-10-rename-torrust-tracker-located-error-to-torrust-located-error.md index 36c4af1af..374d6bdf0 100644 --- a/docs/issues/drafts/1669-07-rename-torrust-tracker-located-error-to-torrust-located-error.md +++ b/docs/issues/drafts/1669-10-rename-torrust-tracker-located-error-to-torrust-located-error.md @@ -4,7 +4,7 @@ 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 +spec-path: docs/issues/drafts/1669-10-rename-torrust-tracker-located-error-to-torrust-located-error.md branch: null related-pr: null last-updated-utc: 2026-05-15 12:00 diff --git a/docs/issues/drafts/1669-11-update-all-package-readmes.md b/docs/issues/drafts/1669-11-update-all-package-readmes.md new file mode 100644 index 000000000..93215457f --- /dev/null +++ b/docs/issues/drafts/1669-11-update-all-package-readmes.md @@ -0,0 +1,127 @@ +--- +doc-type: issue +issue-type: task +status: draft +priority: p3 +github-issue: null +spec-path: docs/issues/drafts/1669-11-update-all-package-readmes.md +branch: null +related-pr: null +last-updated-utc: 2026-05-18 00:00 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - docs/issues/open/1669-overhaul-packages/readme-audit.md + - docs/issues/open/1669-overhaul-packages/EPIC.md + - packages/ +--- + + + +# Issue #[To be assigned] - Update all package READMEs + +## Goal + +Bring every package's `README.md` up to a consistent quality bar — clear title, short +description, scope summary, and usage or integration notes — so that packages are +well-documented before they are extracted to standalone repositories. + +## Background + +The baseline README audit (`docs/issues/open/1669-overhaul-packages/readme-audit.md`, +produced in SI-01) rated each of the 26+ packages as **good**, **minimal**, or **stub**. +Several packages have placeholder READMEs with wrong titles or no meaningful content. + +This subissue is intentionally ordered **after** the rename subissues (SI-07 through SI-10) +so that all READMEs are written against the final package names, and **before** the extraction +subissues (SI-12 through SI-15) so that extracted standalone repositories launch with +good documentation from day one. + +This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) +(Overhaul: Packages). + +## Scope + +### In Scope + +- Review and update `README.md` for every package listed in + `docs/issues/open/1669-overhaul-packages/readme-audit.md`. +- Minimum quality bar for each README: + - Correct title (matching the final crate name after renames). + - One-paragraph description of what the package does and what it does not do. + - Scope summary: key public types / traits / constants. + - Dependency context: what it depends on, what depends on it. + - Quick-start or integration example where meaningful. +- Prioritise packages rated **stub** first, then **minimal**, then **good** (review/polish only). + +### Out of Scope + +- Updating `AGENTS.md`, `docs/packages.md`, or top-level `README.md` (handled in separate docs + cleanup work). +- Writing API reference docs (that is `rustdoc`-level work, a separate concern). +- Adding new tests or code changes. + +### Prerequisites + +- SI-07 (align `torrust-` prefix rename) complete +- SI-08 (rename `torrust-tracker-metrics`) complete +- SI-09 (rename `torrust-tracker-clock`) complete +- SI-10 (rename `torrust-tracker-located-error`) complete + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| T1 | BLOCKED | Confirm rename subissues SI-07–SI-10 are complete | Blocked on SI-07, SI-08, SI-09, SI-10 | +| T2 | TODO | Update all **stub**-rated package READMEs (see audit) | Three or more packages; titles and descriptions rewritten from scratch | +| T3 | TODO | Update all **minimal**-rated package READMEs (see audit) | Expand description, add scope and dependency context | +| T4 | TODO | Review all **good**-rated package READMEs for title accuracy after renames | Minor edits only (title, crate name references) | +| T5 | TODO | Run `linter all` (markdownlint, cspell) | Exit code `0` | + +## Progress Tracking + +### Workflow Checkpoints + +- [ ] Spec drafted in `docs/issues/drafts/` +- [ ] Spec reviewed and approved by user/maintainer +- [ ] Rename prerequisite subissues complete (SI-07 through SI-10) +- [ ] 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`) +- [ ] 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-18 00:00 UTC - josecelano - Spec drafted as subissue of EPIC #1669; uses + readme-audit.md baseline from SI-01. Ordered after renaming (SI-07–SI-10) and before + extraction (SI-12+). + +## Acceptance Criteria + +- [ ] Every package under `packages/` has a `README.md` with a correct title matching its + final crate name. +- [ ] Every package README contains at minimum a description paragraph, scope summary, and + dependency context. +- [ ] No package is rated **stub** in a post-implementation re-audit. +- [ ] `linter all` exits with code `0` (markdownlint passes on all package READMEs). + +## Verification Plan + +### Automatic Checks + +- `linter all` + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command / Steps | Expected Result | Status | Evidence | +| --- | --------------------------------------- | ----------------------------------------------------------------- | ------------------------------ | ------ | -------- | +| M1 | All package READMEs have correct titles | Open each `packages/*/README.md`; verify `# ` heading | Titles match final crate names | TODO | | +| M2 | No stub READMEs remain | Re-run readme audit tool from SI-01 | Zero packages rated stub | TODO | | diff --git a/docs/issues/drafts/1669-08-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md b/docs/issues/drafts/1669-12-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md similarity index 99% rename from docs/issues/drafts/1669-08-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md rename to docs/issues/drafts/1669-12-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md index 4b9fe9013..3ca62dcaa 100644 --- a/docs/issues/drafts/1669-08-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md +++ b/docs/issues/drafts/1669-12-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md @@ -4,7 +4,7 @@ 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 +spec-path: docs/issues/drafts/1669-12-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md branch: null related-pr: null last-updated-utc: 2026-05-15 12:00 diff --git a/docs/issues/drafts/1669-09-extract-torrust-clock-to-standalone-repo.md b/docs/issues/drafts/1669-13-extract-torrust-clock-to-standalone-repo.md similarity index 97% rename from docs/issues/drafts/1669-09-extract-torrust-clock-to-standalone-repo.md rename to docs/issues/drafts/1669-13-extract-torrust-clock-to-standalone-repo.md index 4ba8f3725..d1f6ea8c8 100644 --- a/docs/issues/drafts/1669-09-extract-torrust-clock-to-standalone-repo.md +++ b/docs/issues/drafts/1669-13-extract-torrust-clock-to-standalone-repo.md @@ -4,7 +4,7 @@ issue-type: task status: draft priority: p3 github-issue: null -spec-path: docs/issues/drafts/1669-09-extract-torrust-clock-to-standalone-repo.md +spec-path: docs/issues/drafts/1669-13-extract-torrust-clock-to-standalone-repo.md branch: null related-pr: null last-updated-utc: 2026-05-15 12:00 @@ -17,7 +17,7 @@ semantic-links: - 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-09-rename-torrust-tracker-clock-to-torrust-clock.md - docs/issues/drafts/1669-02-move-duration-since-unix-epoch-to-torrust-clock.md --- @@ -47,7 +47,7 @@ deps (`chrono`, `tracing`) are published crates. Extraction is therefore unblock **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)) + ([1669-09-rename-torrust-tracker-clock-to-torrust-clock.md](1669-09-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)) diff --git a/docs/issues/drafts/1669-10-extract-torrust-metrics-to-standalone-repo.md b/docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md similarity index 96% rename from docs/issues/drafts/1669-10-extract-torrust-metrics-to-standalone-repo.md rename to docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md index 1d4f5f95a..2083bd7af 100644 --- a/docs/issues/drafts/1669-10-extract-torrust-metrics-to-standalone-repo.md +++ b/docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md @@ -4,7 +4,7 @@ issue-type: task status: draft priority: p3 github-issue: null -spec-path: docs/issues/drafts/1669-10-extract-torrust-metrics-to-standalone-repo.md +spec-path: docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md branch: null related-pr: null last-updated-utc: 2026-05-15 12:00 @@ -17,7 +17,7 @@ semantic-links: - 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 + - docs/issues/drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md --- @@ -38,12 +38,12 @@ already published on crates.io. After the `torrust-tracker-metrics` → `torrust 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)) +([1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md](1669-08-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)) +([1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md](1669-08-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) diff --git a/docs/issues/drafts/1669-11-extract-torrust-tracker-client-to-standalone-repo.md b/docs/issues/drafts/1669-15-extract-torrust-tracker-client-to-standalone-repo.md similarity index 99% rename from docs/issues/drafts/1669-11-extract-torrust-tracker-client-to-standalone-repo.md rename to docs/issues/drafts/1669-15-extract-torrust-tracker-client-to-standalone-repo.md index 6fb8c7931..b39dcb1ea 100644 --- a/docs/issues/drafts/1669-11-extract-torrust-tracker-client-to-standalone-repo.md +++ b/docs/issues/drafts/1669-15-extract-torrust-tracker-client-to-standalone-repo.md @@ -4,7 +4,7 @@ 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 +spec-path: docs/issues/drafts/1669-15-extract-torrust-tracker-client-to-standalone-repo.md branch: null related-pr: null last-updated-utc: 2026-05-15 12:00 diff --git a/docs/issues/open/1669-overhaul-packages/EPIC.md b/docs/issues/open/1669-overhaul-packages/EPIC.md index ab9fd31ba..be37622d5 100644 --- a/docs/issues/open/1669-overhaul-packages/EPIC.md +++ b/docs/issues/open/1669-overhaul-packages/EPIC.md @@ -6,13 +6,13 @@ 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 +last-updated-utc: 2026-05-18 00:00 semantic-links: skill-links: - create-issue related-artifacts: - docs/packages.md - - docs/media/packages/ + - docs/issues/open/1669-overhaul-packages/ - AGENTS.md --- @@ -114,11 +114,12 @@ 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` | +| 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` | +| Yes | `torrust-net-primitives` | `net-primitives` | New package (created by SI-05) | +| No | `torrust-metrics` | `metrics` | Renamed from `torrust-tracker-metrics` | ### `torrust-tracker-` prefix @@ -203,30 +204,38 @@ 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)_ +- [ ] SI-04 — Move `AnnouncePolicy` from `torrust-tracker-configuration` to `torrust-tracker-primitives` _(Rule M; no blockers)_ +- [ ] SI-05 — Create `torrust-net-primitives` and move `ServiceBinding` from `torrust-tracker-primitives` _(Rule M + new package; no blockers)_ +- [ ] SI-06 — Resolve `bittorrent-tracker-core` ↔ `torrust-rest-tracker-api-client` layer violation _(Rule M; prerequisite for `bittorrent-tracker-core` extraction)_ +- [ ] SI-07 — Align `torrust-` prefix: rename 7 tracker-specific packages to `torrust-tracker-` _(Rule U; no blockers)_ +- [ ] SI-08 — Rename `torrust-tracker-metrics` to `torrust-metrics` _(Rule U; no blockers)_ +- [ ] SI-09 — Rename `torrust-tracker-clock` to `torrust-clock` _(Rule P; requires SI-03)_ +- [ ] SI-10 — Rename `torrust-tracker-located-error` to `torrust-located-error` _(Rule P; no blockers)_ +- [ ] SI-11 — Update all package READMEs _(documentation; after SI-07–SI-10; before SI-12)_ +- [ ] SI-12 — Extract and rename `torrust-tracker-contrib-bencode` to `torrust-bencode` _(Rule E; no blockers within this EPIC)_ +- [ ] SI-13 — Extract `torrust-clock` to standalone repository _(Rule E; requires SI-02 + SI-09)_ +- [ ] SI-14 — Extract `torrust-metrics` to standalone repository _(Rule E; requires SI-08)_ +- [ ] SI-15 — 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) | +| SI | Issue | Local Spec | Status | Notes | +| ----- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------ | +| SI-01 | #TBD — Establish baseline: dependency graph + README audit | [docs/issues/drafts/1669-01-establish-baseline-analysis.md](../../drafts/1669-01-establish-baseline-analysis.md) | 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-13 | +| 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-09 (clock rename) | +| SI-04 | #TBD — Move `AnnouncePolicy` from `torrust-tracker-configuration` to `torrust-tracker-primitives` | [docs/issues/drafts/1669-04-move-announce-policy-to-torrust-tracker-primitives.md](../../drafts/1669-04-move-announce-policy-to-torrust-tracker-primitives.md) | TODO | Rule M; fixes inverted dep (primitives → configuration); no blockers | +| SI-05 | #TBD — Create `torrust-net-primitives` and move `ServiceBinding` from `torrust-tracker-primitives` | [docs/issues/drafts/1669-05-create-torrust-net-primitives-and-move-service-binding.md](../../drafts/1669-05-create-torrust-net-primitives-and-move-service-binding.md) | TODO | Rule M + new package; generic networking type; breaks server-lib → tracker-primitives dep | +| SI-06 | #TBD — Resolve `bittorrent-tracker-core` ↔ `torrust-rest-tracker-api-client` layer violation | [docs/issues/drafts/1669-06-resolve-bittorrent-tracker-core-rest-api-layer-violation.md](../../drafts/1669-06-resolve-bittorrent-tracker-core-rest-api-layer-violation.md) | TODO | Rule M; stale unused dev dep — one-line `Cargo.toml` deletion; unblocks `bittorrent-tracker-core` extraction | +| SI-07 | #TBD — Align `torrust-` prefix: rename 7 tracker-specific packages to `torrust-tracker-` | [docs/issues/drafts/1669-07-align-torrust-prefix-rename-tracker-specific-packages.md](../../drafts/1669-07-align-torrust-prefix-rename-tracker-specific-packages.md) | TODO | Rule U; none of the 7 are published; pure workspace rename; no blockers | +| SI-08 | #TBD — Rename `torrust-tracker-metrics` to `torrust-metrics` | [docs/issues/drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md](../../drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md) | TODO | Rule U; not yet published; no blockers; prerequisite for SI-14 | +| SI-09 | #TBD — Rename `torrust-tracker-clock` to `torrust-clock` | [docs/issues/drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md](../../drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md) | TODO | Rule P; published on crates.io; requires SI-03; prerequisite for SI-13 | +| SI-10 | #TBD — Rename `torrust-tracker-located-error` to `torrust-located-error` | [docs/issues/drafts/1669-10-rename-torrust-tracker-located-error-to-torrust-located-error.md](../../drafts/1669-10-rename-torrust-tracker-located-error-to-torrust-located-error.md) | TODO | Rule P; published on crates.io; no blockers | +| SI-11 | #TBD — Update all package READMEs | [docs/issues/drafts/1669-11-update-all-package-readmes.md](../../drafts/1669-11-update-all-package-readmes.md) | TODO | Documentation; requires SI-07–SI-10; before SI-12 | +| SI-12 | #TBD — Extract and rename `torrust-tracker-contrib-bencode` to `torrust-bencode` | [docs/issues/drafts/1669-12-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md](../../drafts/1669-12-extract-torrust-tracker-contrib-bencode-to-torrust-bencode.md) | TODO | Rule E; no workspace-dep blockers; Apache-2.0; one internal consumer | +| SI-13 | #TBD — Extract `torrust-clock` to standalone repository | [docs/issues/drafts/1669-13-extract-torrust-clock-to-standalone-repo.md](../../drafts/1669-13-extract-torrust-clock-to-standalone-repo.md) | TODO | Rule E; requires SI-02 + SI-09; 11 workspace consumers to migrate | +| SI-14 | #TBD — Extract `torrust-metrics` to standalone repository | [docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md](../../drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md) | TODO | Rule E; requires SI-08; 7 workspace consumers to migrate | +| SI-15 | #TBD — Extract `torrust-tracker-client` to standalone repository | [docs/issues/drafts/1669-15-extract-torrust-tracker-client-to-standalone-repo.md](../../drafts/1669-15-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. @@ -322,8 +331,8 @@ against this constraint (verified May 2026). | `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) | +| `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-13-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-14-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` | @@ -342,14 +351,40 @@ against this constraint (verified May 2026). ### Analysis tooling -The issue references several tools (screenshots from CodeScene already in the issue comment): +Four complementary analyses are recommended to assess whether the current package structure +represents coherent bounded contexts: + +1. **Dependency graph** — structural coupling: which crates depend on which; detect cycles + and hotspots. Tools: `cargo metadata`, `cargo-depgraph`, `cargo-modules`, `cargo-deps`. + +2. **Semantic domain graph** — conceptual mapping: which crates handle which domain concepts + (Announce, Scrape, Swarm, Peer, …); identify crates that mix unrelated concerns. + +3. **Git co-change graph** — historical coupling: which crates have been modified together + over time; this often reveals the "real architecture" independent of declared dependencies. + Tools: `git log`, GitNexus. + +4. **Bounded context analysis** — ownership clarity: identify crates that mix concerns + (e.g. peer validation + database + metrics + protocol parsing in one package). + +Recommended pragmatic stack for the baseline analysis: + +```text +cargo metadata → workspace structure + declared deps +cargo-modules → module-level dependency graph +git log → co-change history +Graphviz → visualization of the above +``` + +The baseline analysis subissue (SI-01) should pick the tool(s), run them, and commit their +output as artifacts under `docs/issues/open/1669-overhaul-packages/`. + +Previously referenced 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 From 83d2c827dd8e9e005a33bc9e4aa096f4e40ca457 Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Mon, 18 May 2026 12:55:23 +0100 Subject: [PATCH 04/11] chore(analysis): remove old workspace-coupling shell script Replaced by the Rust binary at contrib/dev-tools/analysis/workspace-coupling/. --- .../dev-tools/analysis/workspace-coupling.sh | 227 ------------------ 1 file changed, 227 deletions(-) delete mode 100755 contrib/dev-tools/analysis/workspace-coupling.sh diff --git a/contrib/dev-tools/analysis/workspace-coupling.sh b/contrib/dev-tools/analysis/workspace-coupling.sh deleted file mode 100755 index 21b6bcd37..000000000 --- a/contrib/dev-tools/analysis/workspace-coupling.sh +++ /dev/null @@ -1,227 +0,0 @@ -#!/usr/bin/env bash -# -# workspace-coupling.sh -# -# Generates a workspace coupling report for the Torrust Tracker repository. -# -# For every workspace package that has workspace-level dependencies the script: -# 1. Lists the declared workspace dependencies (normal / dev / build). -# 2. Scans the package's src/ directory for `use DEP_MODULE::` statements and -# fully-qualified `DEP_MODULE::` path references, then lists the distinct -# top-level import paths found. -# -# A short import list (1-3 items) is a signal that the dependency may be weak -# and worth reviewing (e.g. moving a single constant to eliminate the edge). -# -# Requirements: cargo, jq, ripgrep (rg) -# -# Usage: -# ./contrib/dev-tools/analysis/workspace-coupling.sh [OUTPUT_FILE] -# -# If OUTPUT_FILE is omitted the report is written to: -# docs/media/packages/workspace-coupling-report.md -# -# Exit codes: 0 on success, non-zero on error. - -set -euo pipefail - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -WORKSPACE_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)" -OUTPUT_FILE="${1:-$WORKSPACE_ROOT/docs/media/packages/workspace-coupling-report.md}" - -echo "Workspace root : $WORKSPACE_ROOT" >&2 -echo "Output file : $OUTPUT_FILE" >&2 -echo "" >&2 - -# --------------------------------------------------------------------------- -# 1. Load workspace metadata -# --------------------------------------------------------------------------- -cd "$WORKSPACE_ROOT" -METADATA=$(cargo metadata --format-version 1 2>/dev/null) - -# Build a JSON array of workspace member names (used as a lookup set later). -WORKSPACE_NAME_SET=$(echo "$METADATA" | jq -c ' - .workspace_members as $members | - [.packages[] | select(.id as $id | $members | index($id) != null) | .name] -') - -# Sorted list of workspace member names, one per line. -WORKSPACE_MEMBER_NAMES=$(echo "$WORKSPACE_NAME_SET" | jq -r 'sort | .[]') - -# Count total workspace members for the header. -TOTAL=$(echo "$WORKSPACE_NAME_SET" | jq 'length') - -# --------------------------------------------------------------------------- -# 2. Helper: convert a crate name to its Rust module identifier -# (hyphens → underscores). -# --------------------------------------------------------------------------- -crate_to_module() { echo "$1" | tr '-' '_'; } - -# --------------------------------------------------------------------------- -# 3. Render the report -# --------------------------------------------------------------------------- -{ - echo "# Workspace Coupling Report" - echo "" - echo "Generated: $(date -u '+%Y-%m-%d %H:%M UTC')" - echo "" - echo "Workspace packages: $TOTAL" - echo "" - echo "---" - echo "" - echo "## How to read this report" - echo "" - echo "Each section covers one workspace package that has at least one workspace-level" - echo "dependency. For every dependency the items actually imported from it are listed:" - echo "" - echo "- **Normal dep** — required for compilation of the library/binary." - echo "- **Dev dep** — required only in tests and benchmarks." - echo "- **Build dep** — required only in \`build.rs\`." - echo "" - echo "Items are extracted by scanning the package's \`src/\` directory for" - echo "\`use MODULE::\` statements and \`MODULE::\` fully-qualified path references." - echo "The scan is text-based; it may miss items imported through re-exports or macros," - echo "but it is accurate enough to identify thin-dependency patterns." - echo "" - echo "**Signal**: a dependency with only 1–3 distinct import paths may be a candidate" - echo "for elimination (move the item, break the edge)." - echo "" - echo "---" - echo "" - echo "## Packages with no workspace dependencies" - echo "" - echo "These packages are leaves (no workspace dep) and are prime extraction candidates." - echo "" - - # List leaf packages. - LEAF_LIST="" - while IFS= read -r PKG_NAME; do - DEP_COUNT=$(echo "$METADATA" | jq --arg name "$PKG_NAME" \ - --argjson ws_names "$WORKSPACE_NAME_SET" ' - .packages[] | select(.name == $name) | - [.dependencies[] | select(.name as $n | $ws_names | index($n) != null)] | length - ') - if [ "$DEP_COUNT" -eq 0 ]; then - echo "- \`$PKG_NAME\`" - LEAF_LIST="${LEAF_LIST}${PKG_NAME}\n" - fi - done <<< "$WORKSPACE_MEMBER_NAMES" - - echo "" - echo "---" - echo "" - echo "## Package coupling details" - echo "" -} > "$OUTPUT_FILE" - -# --------------------------------------------------------------------------- -# 4. Per-package sections (only packages that have workspace deps) -# --------------------------------------------------------------------------- -while IFS= read -r PKG_NAME; do - # Extract this package's workspace dependencies (all kinds). - PKG_MANIFEST=$(echo "$METADATA" | jq -r --arg name "$PKG_NAME" ' - .packages[] | select(.name == $name) | .manifest_path - ') - PKG_DIR="$(dirname "$PKG_MANIFEST")" - PKG_SRC_DIR="$PKG_DIR/src" - - # Build a sorted list of workspace deps as JSON objects {name, kind}. - WORKSPACE_DEPS=$(echo "$METADATA" | jq -c --arg name "$PKG_NAME" \ - --argjson ws_names "$WORKSPACE_NAME_SET" ' - .packages[] | select(.name == $name) | - [ - .dependencies[] | - select(.name as $n | $ws_names | index($n) != null) | - {name: .name, kind: (.kind // "normal")} - ] | sort_by(.kind, .name) - ') - - DEP_COUNT=$(echo "$WORKSPACE_DEPS" | jq 'length') - if [ "$DEP_COUNT" -eq 0 ]; then - continue - fi - - { - echo "### \`$PKG_NAME\`" - echo "" - echo "Workspace deps: $DEP_COUNT" - echo "" - } >> "$OUTPUT_FILE" - - # For each workspace dependency, scan the source for imports. - while IFS= read -r DEP_JSON; do - DEP_NAME=$(echo "$DEP_JSON" | jq -r '.name') - DEP_KIND=$(echo "$DEP_JSON" | jq -r '.kind') - DEP_MODULE=$(crate_to_module "$DEP_NAME") - - { - echo "#### \`$DEP_NAME\` [$DEP_KIND]" - echo "" - } >> "$OUTPUT_FILE" - - if [ -d "$PKG_SRC_DIR" ]; then - # Search for: `use DEP_MODULE::` and bare `DEP_MODULE::Foo` references. - # Extract the path up to the next space, semicolon, brace, or comma. - IMPORTS=$( - rg --no-filename --no-line-number \ - "${DEP_MODULE}::[A-Za-z_]" \ - "$PKG_SRC_DIR" 2>/dev/null \ - | grep -oP "${DEP_MODULE}::[A-Za-z_][A-Za-z0-9_]*(?:::[A-Za-z_][A-Za-z0-9_]*)?" \ - | sort -u \ - || true - ) - - if [ -n "$IMPORTS" ]; then - echo "$IMPORTS" | while IFS= read -r IMPORT; do - echo "- \`$IMPORT\`" - done >> "$OUTPUT_FILE" - else - # Check if there are any references at all (maybe macro-only usage) - ANY=$( - rg --no-filename --no-line-number \ - "${DEP_MODULE}" \ - "$PKG_SRC_DIR" 2>/dev/null | head -1 \ - || true - ) - if [ -n "$ANY" ]; then - echo "_Items not extracted — dependency used without a direct \`use\` path (macro, re-export, or glob import)._" >> "$OUTPUT_FILE" - else - echo "_No \`${DEP_MODULE}::\` references found in \`src/\` — may be used only in \`Cargo.toml\` feature flags or \`build.rs\`._" >> "$OUTPUT_FILE" - fi - fi - else - echo "_Source directory \`src/\` not found at \`$PKG_SRC_DIR\`._" >> "$OUTPUT_FILE" - fi - - echo "" >> "$OUTPUT_FILE" - - done < <(echo "$WORKSPACE_DEPS" | jq -c '.[]') - -done <<< "$WORKSPACE_MEMBER_NAMES" - -# --------------------------------------------------------------------------- -# 5. Observations placeholder -# --------------------------------------------------------------------------- -{ - echo "---" - echo "" - echo "## Observations" - echo "" - echo "_(To be filled in after reviewing the report above.)_" - echo "" - echo "### Known thin dependencies (pre-existing)" - echo "" - echo "- \`torrust-tracker-clock\` → \`torrust-tracker-primitives\`: only" - echo " \`DurationSinceUnixEpoch\` imported. Addressed by SI-02." - echo "- \`torrust-tracker-configuration\` → \`torrust-tracker-clock\`: only" - echo " \`DEFAULT_TIMEOUT\` imported. Addressed by SI-03." - echo "" - echo "### New findings" - echo "" - echo "_(Record any new thin-dependency or cluster-dependency findings here, with a" - echo "reference to the subissue opened for each.)_" - echo "" -} >> "$OUTPUT_FILE" - -echo "Done." >&2 -echo "Report: $OUTPUT_FILE" >&2 From f6d08df2a477c9a96e814e22fca7bdd484da6634 Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Mon, 18 May 2026 13:12:03 +0100 Subject: [PATCH 05/11] docs(issues): add temp review plan for epic 1669 --- .../review-2026-05-18-temp.md | 132 ++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md diff --git a/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md b/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md new file mode 100644 index 000000000..f22935fed --- /dev/null +++ b/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md @@ -0,0 +1,132 @@ +# EPIC Review Notes (Temp) + +Date: 2026-05-18 +Scope: [EPIC.md](EPIC.md) and SI drafts linked from the Active Subissues table. +Review focus: consistency, dependency integrity, sequencing risk. + +## Working Mode + +Address one finding at a time, in order. + +1. Pick the next open finding from the queue. +2. Apply only the minimal doc edits needed to close that finding. +3. Re-check cross-references impacted by that edit. +4. Mark the finding as done with a short note. + +## Findings Queue + +### F1 (High) - SI-14 prerequisite cannot be satisfied by SI-08 as written + +Status: OPEN + +Problem: + +- SI-14 requires publish completion before extraction starts: [docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md](../../drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md#L42), [docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md](../../drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md#L47), [docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md](../../drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md#L94). +- SI-08 explicitly says publishing is out of scope and has no publish task: [docs/issues/drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md](../../drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md#L65), [docs/issues/drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md](../../drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md#L70), [docs/issues/drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md](../../drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md#L77). + +Why this matters: + +- SI-14 remains structurally blocked even if SI-08 is completed. + +Proposed minimal fix: + +- Choose one policy and align both specs: + - Option A: keep SI-08 as rename-only; in SI-14 change prerequisite wording to rename completion only and move publish responsibility into SI-14. + - Option B: add publish task + acceptance criteria to SI-08, keep SI-14 as currently written. + +Recommendation: + +- Option A, to keep rename and extraction concerns separate. + +### F2 (High) - EPIC shows extracted state that conflicts with SI statuses + +Status: OPEN + +Problem: + +- EPIC lists already extracted packages: [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L154), [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L158), [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L159). +- Same EPIC marks SI-12 and SI-15 as TODO/blocked: [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L215), [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L218). + +Why this matters: + +- Current state reporting becomes ambiguous. + +Proposed minimal fix: + +- Either rename section title to planned/future extracted state, or update SI rows/checklists to reflect completion if truly done. + +Recommendation: + +- Retitle section to clearly indicate target state, unless extraction is already merged. + +### F3 (Medium) - Baseline is described as established while SI-01 is still TODO + +Status: OPEN + +Problem: + +- EPIC first-cycle says baseline established: [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L260), [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L262). +- SI-01 remains TODO in EPIC and SI-01 acceptance/checkpoints are unchecked: [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L204), [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L224), [docs/issues/drafts/1669-01-establish-baseline-analysis.md](../../drafts/1669-01-establish-baseline-analysis.md#L141). + +Why this matters: + +- Phase reporting can drift from issue status. + +Proposed minimal fix: + +- Mark SI-01 appropriately (if done), or reword EPIC first-cycle outcome to pending/in progress. + +### F4 (Medium) - Package count mismatch (26 vs 27) + +Status: OPEN + +Problem: + +- Coupling report says 27 workspace packages: [docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md](workspace-coupling-report.md#L5). +- EPIC and SI-01 repeatedly refer to 26: [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L56), [docs/issues/drafts/1669-01-establish-baseline-analysis.md](../../drafts/1669-01-establish-baseline-analysis.md#L45), [docs/issues/drafts/1669-01-establish-baseline-analysis.md](../../drafts/1669-01-establish-baseline-analysis.md#L109). + +Why this matters: + +- Acceptance criteria and coverage checks can be off-by-one. + +Proposed minimal fix: + +- Update EPIC and SI-01 to a single source-of-truth count and timestamp, or phrase counts as point-in-time with explicit date and include/exclude rules. + +### F5 (Medium) - SI-02 prerequisite points at SI-09 T12 (doc update) instead of technical completion + +Status: OPEN + +Problem: + +- SI-02 prerequisite requires SI-09 T12: [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#L68), [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#L105). +- SI-09 T12 is EPIC table/doc update, not rename mechanics: [docs/issues/drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md](../../drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md#L119). + +Why this matters: + +- Introduces avoidable scheduling blockage. + +Proposed minimal fix: + +- Change SI-02 prerequisite to SI-09 technical completion criteria (crate rename and dependency/use-path migration), not T12. + +### F6 (Low) - SI-03 related-artifacts points to non-matching rename spec path + +Status: OPEN + +Problem: + +- SI-03 related-artifacts references a rename spec path that does not match current naming: [docs/issues/drafts/1669-03-move-default-timeout-from-configuration-to-clock.md](../../drafts/1669-03-move-default-timeout-from-configuration-to-clock.md#L19). +- Existing rename draft is: [docs/issues/drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md](../../drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md). + +Why this matters: + +- Weakens traceability and tooling reliability. + +Proposed minimal fix: + +- Replace artifact path with the canonical SI-09 file path. + +## Progress Log + +- 2026-05-18: Initial review logged with six findings, severity-ranked. From f83350ee5521f07f02314a14a5300994ce8abc37 Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Mon, 18 May 2026 13:18:43 +0100 Subject: [PATCH 06/11] docs(issues): fix SI-14 publish prerequisite (F1) Move publish responsibility from SI-08 into SI-14 itself (new task T1b). SI-08 stays rename-only. SI-14 prerequisite now requires only SI-08 rename completion, per the policy of deferring publish and extract as late as possible (Refactor -> Publish -> Extract). Also mark F1 done in the review plan. --- ...extract-torrust-metrics-to-standalone-repo.md | 16 ++++++++++------ .../review-2026-05-18-temp.md | 10 +++++++++- 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md b/docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md index 2083bd7af..b2e70acd3 100644 --- a/docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md +++ b/docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md @@ -35,16 +35,18 @@ of the tracker. 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. +rename (SI-08), extraction is unblocked. Publishing the renamed crate on crates.io is +the first technical step of the extraction itself (T1b), following the project policy of +deferring publication as late as possible. The rename subissue ([1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md](1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md)) -must be complete — including publishing `torrust-metrics` on crates.io — before this -subissue begins. +must be complete before this subissue begins. Publishing `torrust-metrics` on crates.io +is deferred to this subissue (T1b). **Prerequisite**: Metrics rename subissue ([1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md](1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md)) -complete (all tasks through publishing on crates.io). +complete (SI-08 all tasks done). This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) (Overhaul: Packages). @@ -91,7 +93,8 @@ 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 | +| T1 | BLOCKED | Confirm metrics rename (SI-08) is complete | `packages/metrics/Cargo.toml` has `name = "torrust-metrics"` | +| T1b | TODO | Publish `torrust-metrics` on crates.io | Successful `cargo publish -p 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 | @@ -112,7 +115,8 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. - [ ] Spec drafted in `docs/issues/drafts/` - [ ] Spec reviewed and approved by user/maintainer -- [ ] Metrics rename subissue complete (prerequisite) +- [ ] Metrics rename subissue complete (SI-08; prerequisite) +- [ ] `torrust-metrics` published on crates.io (T1b; required before extraction) - [ ] GitHub issue created and issue number added to this spec - [ ] Spec moved to `docs/issues/open/` with issue number prefix - [ ] Standalone repository created diff --git a/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md b/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md index f22935fed..2f602c7f7 100644 --- a/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md +++ b/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md @@ -17,7 +17,7 @@ Address one finding at a time, in order. ### F1 (High) - SI-14 prerequisite cannot be satisfied by SI-08 as written -Status: OPEN +Status: DONE Problem: @@ -38,6 +38,14 @@ Recommendation: - Option A, to keep rename and extraction concerns separate. +Resolution (2026-05-18): + +- SI-08 remains rename-only (no publish step). Publishing is deferred as long as + possible per project policy (Refactor → Publish → Extract). +- SI-14 updated: prerequisite changed to "SI-08 complete (rename done)"; new task T1b + added within SI-14 to publish `torrust-metrics` on crates.io before extraction begins. +- Workflow checkpoint added in SI-14 for the publish step. + ### F2 (High) - EPIC shows extracted state that conflicts with SI statuses Status: OPEN From 6effa6a0c048092c8ae5e1aea7dc51ec9130007e Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Mon, 18 May 2026 13:23:11 +0100 Subject: [PATCH 07/11] docs(issues): clarify EPIC planned-extraction section title (F2) Rename 'Extracted from workspace' to 'Planned for extraction from workspace' and add a clarifying note. Both packages are still in the workspace; the table describes the target end state for SI-12 and SI-15. --- docs/issues/open/1669-overhaul-packages/EPIC.md | 5 ++++- .../1669-overhaul-packages/review-2026-05-18-temp.md | 9 ++++++++- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/issues/open/1669-overhaul-packages/EPIC.md b/docs/issues/open/1669-overhaul-packages/EPIC.md index be37622d5..fa5c0a3b9 100644 --- a/docs/issues/open/1669-overhaul-packages/EPIC.md +++ b/docs/issues/open/1669-overhaul-packages/EPIC.md @@ -151,7 +151,10 @@ destination group with a "Renamed from …" note. | No | `bittorrent-udp-tracker-core` | `udp-tracker-core` | — | | No | `bittorrent-udp-tracker-protocol` | `udp-protocol` | — | -### Extracted from workspace +### Planned for extraction from workspace + +These packages are not yet extracted. The table describes the target end state once +the corresponding subissues (SI-12, SI-15) are complete. | Final crate name | Extracted from | Notes | | ------------------------ | --------------------------------- | -------------------------------------------------------------------- | diff --git a/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md b/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md index 2f602c7f7..1dcaba736 100644 --- a/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md +++ b/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md @@ -48,7 +48,7 @@ Resolution (2026-05-18): ### F2 (High) - EPIC shows extracted state that conflicts with SI statuses -Status: OPEN +Status: DONE Problem: @@ -67,6 +67,13 @@ Recommendation: - Retitle section to clearly indicate target state, unless extraction is already merged. +Resolution (2026-05-18): + +- Both packages (`torrust-bencode`, `torrust-tracker-client`) are still in the workspace; + extraction is not done. +- EPIC section renamed from "Extracted from workspace" to "Planned for extraction from + workspace" with a clarifying note pointing to SI-12 and SI-15. + ### F3 (Medium) - Baseline is described as established while SI-01 is still TODO Status: OPEN From ff152f4c1caa58f2c9b759a2ad8fb04b7307ff8e Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Mon, 18 May 2026 13:42:18 +0100 Subject: [PATCH 08/11] docs(issues): add config-splitting research task (T8) to SI-01 baseline (F3) --- .../1669-01-establish-baseline-analysis.md | 66 ++++++++++++++++--- .../review-2026-05-18-temp.md | 10 ++- project-words.txt | 1 + 3 files changed, 66 insertions(+), 11 deletions(-) diff --git a/docs/issues/drafts/1669-01-establish-baseline-analysis.md b/docs/issues/drafts/1669-01-establish-baseline-analysis.md index e890483db..5a68bbfec 100644 --- a/docs/issues/drafts/1669-01-establish-baseline-analysis.md +++ b/docs/issues/drafts/1669-01-establish-baseline-analysis.md @@ -7,7 +7,7 @@ github-issue: null spec-path: docs/issues/drafts/1669-01-establish-baseline-analysis.md branch: null related-pr: null -last-updated-utc: 2026-05-18 00:00 +last-updated-utc: 2026-05-18 12:00 semantic-links: skill-links: - create-issue @@ -15,6 +15,7 @@ semantic-links: - contrib/dev-tools/analysis/workspace-coupling/src/main.rs - docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md - docs/issues/open/1669-overhaul-packages/readme-audit.md + - packages/configuration/src/lib.rs - docs/issues/open/1669-overhaul-packages/EPIC.md --- @@ -90,10 +91,14 @@ The output is a markdown report saved to `docs/issues/open/1669-overhaul-packages/readme-audit.md`. - Review the coupling report for thin-dependency findings and record them as observations in the coupling report itself or a linked notes section. +- Research whether `packages/configuration` should be split into per-service sub-packages + (e.g., tracker-core config, UDP config, HTTP config, REST API config); see T8. ### Out of Scope - Fixing any of the coupling issues found (each fix becomes its own subissue). +- Deciding to split or restructure `packages/configuration` — that is a separate subissue + if the T8 research finds it warranted. - Semantic domain graph, git co-change graph, or bounded-context analysis (deferred; revisit if the coupling report leaves open questions). - Generating visual graphs (e.g. DOT/SVG) — the markdown table is sufficient for the first @@ -103,15 +108,49 @@ The output is a markdown report saved to Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. -| ID | Status | Task | Notes / Expected Output | -| --- | ------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| T1 | TODO | Create Rust binary `contrib/dev-tools/analysis/workspace-coupling/` and add it to workspace members | Binary compiles cleanly (`cargo build -p workspace-coupling`) | -| T2 | TODO | Run binary; review output for obvious errors (missing packages, wrong module names) | Report covers all 26 workspace packages | -| T3 | TODO | Save report to `docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md` and commit | File committed in the analysis branch | -| T4 | TODO | Manually audit each package README; fill in `docs/issues/open/1669-overhaul-packages/readme-audit.md` table | Table covers all 26 packages; rating = good / minimal / stub | -| T5 | TODO | Review coupling report; annotate thin-dependency findings (SI-02/SI-03 patterns and any new ones found) | Findings recorded in a "Observations" section at the bottom of the report | -| T6 | TODO | For each new thin-dependency finding: open (or update) a corresponding subissue in EPIC #1669 Active Subissues | New subissues added to EPIC quick list if applicable | -| T7 | TODO | Run `linter all` | Exit code `0` | +| ID | Status | Task | Notes / Expected Output | +| --- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| T1 | TODO | Create Rust binary `contrib/dev-tools/analysis/workspace-coupling/` and add it to workspace members | Binary compiles cleanly (`cargo build -p workspace-coupling`) | +| T2 | TODO | Run binary; review output for obvious errors (missing packages, wrong module names) | Report covers all 26 workspace packages | +| T3 | TODO | Save report to `docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md` and commit | File committed in the analysis branch | +| T4 | TODO | Manually audit each package README; fill in `docs/issues/open/1669-overhaul-packages/readme-audit.md` table | Table covers all 26 packages; rating = good / minimal / stub | +| T5 | TODO | Review coupling report; annotate thin-dependency findings (SI-02/SI-03 patterns and any new ones found) | Findings recorded in a "Observations" section at the bottom of the report | +| T6 | TODO | For each new thin-dependency finding: open (or update) a corresponding subissue in EPIC #1669 Active Subissues | New subissues added to EPIC quick list if applicable | +| T7 | TODO | Run `linter all` | Exit code `0` | +| T8 | TODO | Research how to scope `packages/configuration` per service: (a) split into sub-packages, or (b) gate with Cargo features. Audit which config structs each service needs; prototype the two scenarios below for each approach; record findings and open a new subissue if a change is warranted | Findings section added to coupling report; new subissue opened if viable | + +### T8 — prototype targets + +The goal is to understand how hard it is today to build a smaller tracker binary by +assembling only the packages a given deployment really needs. Build one prototype per +scenario on the current codebase (no refactoring; just wiring what exists): + +| # | Scenario | Required packages (expected) | Key question | +| --- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | +| P1 | Public UDP-only tracker (no API) | `tracker-core`, `udp-tracker-core`, `udp-tracker-server`, `configuration` (UDP + core subset) | Can the binary compile without HTTP/REST-API packages? | +| P2 | Private HTTP tracker + REST management API (no UDP) | `tracker-core`, `http-tracker-core`, `axum-http-tracker-server`, `axum-rest-tracker-api-server`, `configuration` (HTTP + REST-API + core subset) | Can the binary compile without UDP packages? | + +For each prototype record: + +- Whether it compiled with zero changes to existing packages. +- Which `packages/configuration` structs were actually used and which were dead weight. +- Any circular dependency or versioning problem that would block splitting. +- An estimate of binary size reduction vs. the full tracker binary. + +### T8 — known trade-offs to assess + +| Trade-off | Notes | +| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Smaller / safer binaries (reduced attack surface) | Benefit for users who need only one protocol | +| Custom container builds required | Users must build their own images; no official slim images today | +| Incomplete config files | A UDP-only binary would not parse HTTP config sections; partial configs need clear schema boundaries | +| Versioning complexity | Per-service versions are too complex; a single version-per-config-file concept does not map well either. Coordinated versioning (all config sub-packages share a version, bumped together on any breaking change) sounds reasonable but is hard to maintain. Core goal: avoid forcing consumers to import the whole tracker config when they only need, e.g., the UDP config. | +| `packages/configuration` as re-export facade | Splitting does not require removing `packages/configuration`; it can re-export from the specialized sub-packages so that the main full-tracker binary and all existing code continue to work without refactoring. | +| Cargo features as alternative to splitting | Instead of separate packages, add Cargo features to `packages/configuration` (e.g., `udp`, `http`, `rest-api`). Consumers enable only the features they need; the main binary enables all. No package-splitting overhead, no versioning coordination problem. Trade-off: one package is still pulled in as a dependency even if only a small feature is used; all feature combinations must be tested. | +| "Symphony vs Laravel" | Symphony: compose from packages; Laravel: enable/disable in one binary. Current tracker is closer to Laravel. | + +Conclusion from T8 feeds into a new subissue (if splitting is warranted) or an +explicit "will not split" decision recorded in the coupling report observations. ## Progress Tracking @@ -133,6 +172,10 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. - 2026-05-18 00:00 UTC - GitHub Copilot - Spec drafted as subissue SI-01 of EPIC #1669. Scope refined during discussion: item-level import scan is central (not optional) because without it thin-dependency patterns like SI-02/SI-03 cannot be found systematically. +- 2026-05-18 12:00 UTC - josecelano - Added T8: research whether `packages/configuration` + should be split into per-service sub-packages. Includes two prototype scenarios (UDP-only + and HTTP+REST-API) and a trade-off table. Outcome either opens a new subissue or records + a "will not split" decision. ## Acceptance Criteria @@ -146,6 +189,9 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. for each of the 26 packages. - [ ] Any thin-dependency findings not already covered by existing subissues are recorded as observations in the coupling report. +- [ ] T8 research findings (configuration splitting) are recorded in the coupling report or + a linked observations file; either a new subissue is opened or a "will not split" + decision is documented. - [ ] `linter all` exits with code `0`. ## Verification Plan diff --git a/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md b/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md index 1dcaba736..462ffb279 100644 --- a/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md +++ b/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md @@ -76,7 +76,7 @@ Resolution (2026-05-18): ### F3 (Medium) - Baseline is described as established while SI-01 is still TODO -Status: OPEN +Status: IN PROGRESS Problem: @@ -91,6 +91,14 @@ Proposed minimal fix: - Mark SI-01 appropriately (if done), or reword EPIC first-cycle outcome to pending/in progress. +Action taken (2026-05-18): + +- SI-01 scope extended with new task T8: research `packages/configuration` splitting into + per-service sub-packages, with two prototype scenarios (UDP-only and HTTP+REST-API) and + a trade-off table. Outcome either opens a new subissue or records a decision. +- SI-01 remains open. EPIC first-cycle outcome text still reads "Baseline established" while + SI-01 is in progress — the EPIC wording fix is deferred until SI-01 is actually complete. + ### F4 (Medium) - Package count mismatch (26 vs 27) Status: OPEN diff --git a/project-words.txt b/project-words.txt index 4ec5da415..050d825ac 100644 --- a/project-words.txt +++ b/project-words.txt @@ -149,6 +149,7 @@ keyout Kibibytes kptr ksys +Laravel lcov leecher leechers From 313e0d46c22ed541832b4fb928afde5a8513076d Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Mon, 18 May 2026 13:47:16 +0100 Subject: [PATCH 09/11] =?UTF-8?q?docs(issues):=20fix=20package=20count=202?= =?UTF-8?q?6=E2=86=9227=20in=20EPIC=20and=20SI-01=20(F4)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../1669-01-establish-baseline-analysis.md | 24 +++++++++---------- .../open/1669-overhaul-packages/EPIC.md | 6 ++--- .../review-2026-05-18-temp.md | 15 +++++++++++- 3 files changed, 29 insertions(+), 16 deletions(-) diff --git a/docs/issues/drafts/1669-01-establish-baseline-analysis.md b/docs/issues/drafts/1669-01-establish-baseline-analysis.md index 5a68bbfec..6c65c8977 100644 --- a/docs/issues/drafts/1669-01-establish-baseline-analysis.md +++ b/docs/issues/drafts/1669-01-establish-baseline-analysis.md @@ -43,7 +43,7 @@ This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) ## Background -The workspace contains 26 packages that grew organically over multiple refactoring cycles. +The workspace contains 27 packages (including the root `torrust-tracker` crate) that grew organically over multiple refactoring cycles. Two coupling problems have already been identified manually: - `torrust-tracker-clock` depends on `torrust-tracker-primitives` only to import @@ -52,7 +52,7 @@ Two coupling problems have already been identified manually: `DEFAULT_TIMEOUT` (SI-03). These were discovered through code inspection. A systematic analysis would surface similar -findings across all 26 packages without relying on luck or familiarity with the codebase. +findings across all 27 packages without relying on luck or familiarity with the codebase. ### Why the item-level view matters @@ -111,9 +111,9 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. | ID | Status | Task | Notes / Expected Output | | --- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | T1 | TODO | Create Rust binary `contrib/dev-tools/analysis/workspace-coupling/` and add it to workspace members | Binary compiles cleanly (`cargo build -p workspace-coupling`) | -| T2 | TODO | Run binary; review output for obvious errors (missing packages, wrong module names) | Report covers all 26 workspace packages | +| T2 | TODO | Run binary; review output for obvious errors (missing packages, wrong module names) | Report covers all 27 workspace packages | | T3 | TODO | Save report to `docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md` and commit | File committed in the analysis branch | -| T4 | TODO | Manually audit each package README; fill in `docs/issues/open/1669-overhaul-packages/readme-audit.md` table | Table covers all 26 packages; rating = good / minimal / stub | +| T4 | TODO | Manually audit each package README; fill in `docs/issues/open/1669-overhaul-packages/readme-audit.md` table | Table covers all 27 packages; rating = good / minimal / stub | | T5 | TODO | Review coupling report; annotate thin-dependency findings (SI-02/SI-03 patterns and any new ones found) | Findings recorded in a "Observations" section at the bottom of the report | | T6 | TODO | For each new thin-dependency finding: open (or update) a corresponding subissue in EPIC #1669 Active Subissues | New subissues added to EPIC quick list if applicable | | T7 | TODO | Run `linter all` | Exit code `0` | @@ -182,11 +182,11 @@ explicit "will not split" decision recorded in the coupling report observations. - [ ] `contrib/dev-tools/analysis/workspace-coupling/` exists, compiles cleanly (`cargo build -p workspace-coupling`), and produces valid markdown output. - [ ] `docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md` is committed - and covers all 26 workspace packages. + and covers all 27 workspace packages. - [ ] Every workspace package that has workspace-level dependencies appears in the report with at least one import path listed per dependency (or a documented reason why none was found). - [ ] `docs/issues/open/1669-overhaul-packages/readme-audit.md` is committed with a rating - for each of the 26 packages. + for each of the 27 packages. - [ ] Any thin-dependency findings not already covered by existing subissues are recorded as observations in the coupling report. - [ ] T8 research findings (configuration splitting) are recorded in the coupling report or @@ -203,12 +203,12 @@ explicit "will not split" decision recorded in the coupling report observations. ### Manual Verification -| ID | Scenario | Expected Result | -| --- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | -| MV1 | Open `docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md` and count package sections | 26 sections minus leaf packages (those with no workspace deps) should appear | -| MV2 | Find `torrust-tracker-configuration` in the report; check the `torrust-tracker-clock` dep section | Should list `torrust_tracker_clock::DEFAULT_TIMEOUT` (confirms SI-03 detection) | -| MV3 | Find `torrust-tracker-clock` in the report; check the `torrust-tracker-primitives` dep section | Should list `torrust_tracker_primitives::DurationSinceUnixEpoch` (SI-02) | -| MV4 | Run `cargo run -p workspace-coupling -- /tmp/test-report.md` on a clean checkout | Binary exits `0`; output file matches committed report structurally | +| ID | Scenario | Expected Result | +| --- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | +| MV1 | Open `docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md` and count package sections | 27 packages total: 5 leaf packages listed in the "no workspace dependencies" section; 22 packages in the coupling detail sections | +| MV2 | Find `torrust-tracker-configuration` in the report; check the `torrust-tracker-clock` dep section | Should list `torrust_tracker_clock::DEFAULT_TIMEOUT` (confirms SI-03 detection) | +| MV3 | Find `torrust-tracker-clock` in the report; check the `torrust-tracker-primitives` dep section | Should list `torrust_tracker_primitives::DurationSinceUnixEpoch` (SI-02) | +| MV4 | Run `cargo run -p workspace-coupling -- /tmp/test-report.md` on a clean checkout | Binary exits `0`; output file matches committed report structurally | ## References diff --git a/docs/issues/open/1669-overhaul-packages/EPIC.md b/docs/issues/open/1669-overhaul-packages/EPIC.md index fa5c0a3b9..b32d02f44 100644 --- a/docs/issues/open/1669-overhaul-packages/EPIC.md +++ b/docs/issues/open/1669-overhaul-packages/EPIC.md @@ -43,7 +43,7 @@ concerns are mixed together: 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), +- **Only 6 of 27 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. @@ -53,7 +53,7 @@ landscape shifts (new packages, splits, significant growth). ## Package Inventory -The workspace currently contains **26 packages** across three crate-name prefixes. +The workspace currently contains **27 packages** (including the root `torrust-tracker` crate) across three crate-name prefixes. "Published" means a crate with that name exists on crates.io (verified May 2026). ### `torrust-` prefix (non-`torrust-tracker-`) @@ -97,7 +97,7 @@ The workspace currently contains **26 packages** across three crate-name prefixe | 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 +**Observation**: only 6 of 27 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." diff --git a/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md b/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md index 462ffb279..406522ad2 100644 --- a/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md +++ b/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md @@ -76,7 +76,7 @@ Resolution (2026-05-18): ### F3 (Medium) - Baseline is described as established while SI-01 is still TODO -Status: IN PROGRESS +Status: DONE Problem: @@ -98,6 +98,7 @@ Action taken (2026-05-18): a trade-off table. Outcome either opens a new subissue or records a decision. - SI-01 remains open. EPIC first-cycle outcome text still reads "Baseline established" while SI-01 is in progress — the EPIC wording fix is deferred until SI-01 is actually complete. +- Changes committed in ff152f4c. ### F4 (Medium) - Package count mismatch (26 vs 27) @@ -116,6 +117,15 @@ Proposed minimal fix: - Update EPIC and SI-01 to a single source-of-truth count and timestamp, or phrase counts as point-in-time with explicit date and include/exclude rules. +Resolution (2026-05-18): + +- The 27th package is the root `torrust-tracker` crate (the main binary, `src/`). It was + excluded from the original 26-package count because EPIC/SI-01 were drafted before the + coupling report was generated. +- All occurrences of "26 packages" updated to "27 packages" in EPIC.md (lines 46, 56, 100) + and SI-01 (Background, T2 notes, T4 notes, acceptance criteria ×2, MV1). +- MV1 verification criterion reworded to: "27 packages total: 5 leaves + 22 with deps." + ### F5 (Medium) - SI-02 prerequisite points at SI-09 T12 (doc update) instead of technical completion Status: OPEN @@ -153,3 +163,6 @@ Proposed minimal fix: ## Progress Log - 2026-05-18: Initial review logged with six findings, severity-ranked. +- 2026-05-18: F1 resolved and committed (f83350ee). F2 resolved and committed (6effa6a0). +- 2026-05-18: F3 partially resolved (T8 added to SI-01) and committed (ff152f4c). EPIC wording deferred to SI-01 completion. +- 2026-05-18: F4 in progress — updating package count from 26 to 27 in EPIC.md and SI-01. From cd56ad3ffa6d250c571a3f67bdb3be39079c656f Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Mon, 18 May 2026 13:50:14 +0100 Subject: [PATCH 10/11] docs(issues): fix SI-02 prerequisite (F5) and SI-03 artifact path (F6) --- ...ation-since-unix-epoch-to-torrust-clock.md | 10 ++++---- ...ult-timeout-from-configuration-to-clock.md | 2 +- .../review-2026-05-18-temp.md | 23 ++++++++++++++++--- 3 files changed, 27 insertions(+), 8 deletions(-) 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 index 424d5be41..4cdb77e81 100644 --- 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 @@ -65,9 +65,11 @@ independent `pub type DurationSinceUnixEpoch = Duration` definition. Once all wo 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-09-rename-torrust-tracker-clock-to-torrust-clock.md](1669-09-rename-torrust-tracker-clock-to-torrust-clock.md)) -must be complete before this subissue begins. +**Prerequisite**: SI-09 technical steps must be complete before this subissue begins: the +crate must be renamed (`name = "torrust-clock"` in `packages/clock/Cargo.toml`), all +dependent `Cargo.toml` files updated to use the new key, and all `use`-path references +migrated to `torrust_clock::` (SI-09 T1–T4). The EPIC table update (SI-09 T12) is not a +blocker. This issue is a subissue of EPIC [#1669](../open/1669-overhaul-packages/EPIC.md) (Overhaul: Packages). @@ -102,7 +104,7 @@ 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` | +| T1 | BLOCKED | Confirm SI-09 technical steps complete (T1–T4: crate renamed to `torrust-clock`, dep keys updated, `use`-paths migrated workspace-wide) | `name = "torrust-clock"` in `packages/clock/Cargo.toml`; workspace builds cleanly | | 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 | 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 index 28f88538e..f0c02d9be 100644 --- 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 @@ -16,7 +16,7 @@ semantic-links: - 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 + - docs/issues/drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md --- diff --git a/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md b/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md index 406522ad2..1ea1f4d9c 100644 --- a/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md +++ b/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md @@ -128,7 +128,7 @@ Resolution (2026-05-18): ### F5 (Medium) - SI-02 prerequisite points at SI-09 T12 (doc update) instead of technical completion -Status: OPEN +Status: DONE Problem: @@ -143,9 +143,18 @@ Proposed minimal fix: - Change SI-02 prerequisite to SI-09 technical completion criteria (crate rename and dependency/use-path migration), not T12. +Resolution (2026-05-18): + +- SI-09 T12 is the EPIC table update only; the actual blocker for SI-02 is T1–T4 (crate + rename, Cargo dep key updates, use-path migration). +- SI-02 prerequisite paragraph rewritten to reference SI-09 T1–T4 explicitly and note that + T12 is not a blocker. +- SI-02 T1 task description updated from "T12 of clock rename spec" to "SI-09 T1–T4 + complete (crate renamed, dep keys updated, use-paths migrated workspace-wide)". + ### F6 (Low) - SI-03 related-artifacts points to non-matching rename spec path -Status: OPEN +Status: DONE Problem: @@ -160,9 +169,17 @@ Proposed minimal fix: - Replace artifact path with the canonical SI-09 file path. +Resolution (2026-05-18): + +- SI-03 `related-artifacts` entry corrected from + `docs/issues/drafts/rename-torrust-tracker-clock-to-torrust-clock.md` to + `docs/issues/drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md`. + ## Progress Log - 2026-05-18: Initial review logged with six findings, severity-ranked. - 2026-05-18: F1 resolved and committed (f83350ee). F2 resolved and committed (6effa6a0). - 2026-05-18: F3 partially resolved (T8 added to SI-01) and committed (ff152f4c). EPIC wording deferred to SI-01 completion. -- 2026-05-18: F4 in progress — updating package count from 26 to 27 in EPIC.md and SI-01. +- 2026-05-18: F4 resolved and committed (313e0d46). Package count updated 26→27; 27th is root `torrust-tracker` crate. +- 2026-05-18: F5 resolved — SI-02 prerequisite rewritten to reference SI-09 T1–T4 (technical completion), not T12. +- 2026-05-18: F6 resolved — SI-03 related-artifacts path corrected to `1669-09-rename-torrust-tracker-clock-to-torrust-clock.md`. From 890d769150c742fca796cc9b3ed5ce119dc33b95 Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Mon, 18 May 2026 13:53:21 +0100 Subject: [PATCH 11/11] docs(issues): remove completed EPIC review temp file --- .../review-2026-05-18-temp.md | 185 ------------------ 1 file changed, 185 deletions(-) delete mode 100644 docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md diff --git a/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md b/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md deleted file mode 100644 index 1ea1f4d9c..000000000 --- a/docs/issues/open/1669-overhaul-packages/review-2026-05-18-temp.md +++ /dev/null @@ -1,185 +0,0 @@ -# EPIC Review Notes (Temp) - -Date: 2026-05-18 -Scope: [EPIC.md](EPIC.md) and SI drafts linked from the Active Subissues table. -Review focus: consistency, dependency integrity, sequencing risk. - -## Working Mode - -Address one finding at a time, in order. - -1. Pick the next open finding from the queue. -2. Apply only the minimal doc edits needed to close that finding. -3. Re-check cross-references impacted by that edit. -4. Mark the finding as done with a short note. - -## Findings Queue - -### F1 (High) - SI-14 prerequisite cannot be satisfied by SI-08 as written - -Status: DONE - -Problem: - -- SI-14 requires publish completion before extraction starts: [docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md](../../drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md#L42), [docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md](../../drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md#L47), [docs/issues/drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md](../../drafts/1669-14-extract-torrust-metrics-to-standalone-repo.md#L94). -- SI-08 explicitly says publishing is out of scope and has no publish task: [docs/issues/drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md](../../drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md#L65), [docs/issues/drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md](../../drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md#L70), [docs/issues/drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md](../../drafts/1669-08-rename-torrust-tracker-metrics-to-torrust-metrics.md#L77). - -Why this matters: - -- SI-14 remains structurally blocked even if SI-08 is completed. - -Proposed minimal fix: - -- Choose one policy and align both specs: - - Option A: keep SI-08 as rename-only; in SI-14 change prerequisite wording to rename completion only and move publish responsibility into SI-14. - - Option B: add publish task + acceptance criteria to SI-08, keep SI-14 as currently written. - -Recommendation: - -- Option A, to keep rename and extraction concerns separate. - -Resolution (2026-05-18): - -- SI-08 remains rename-only (no publish step). Publishing is deferred as long as - possible per project policy (Refactor → Publish → Extract). -- SI-14 updated: prerequisite changed to "SI-08 complete (rename done)"; new task T1b - added within SI-14 to publish `torrust-metrics` on crates.io before extraction begins. -- Workflow checkpoint added in SI-14 for the publish step. - -### F2 (High) - EPIC shows extracted state that conflicts with SI statuses - -Status: DONE - -Problem: - -- EPIC lists already extracted packages: [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L154), [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L158), [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L159). -- Same EPIC marks SI-12 and SI-15 as TODO/blocked: [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L215), [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L218). - -Why this matters: - -- Current state reporting becomes ambiguous. - -Proposed minimal fix: - -- Either rename section title to planned/future extracted state, or update SI rows/checklists to reflect completion if truly done. - -Recommendation: - -- Retitle section to clearly indicate target state, unless extraction is already merged. - -Resolution (2026-05-18): - -- Both packages (`torrust-bencode`, `torrust-tracker-client`) are still in the workspace; - extraction is not done. -- EPIC section renamed from "Extracted from workspace" to "Planned for extraction from - workspace" with a clarifying note pointing to SI-12 and SI-15. - -### F3 (Medium) - Baseline is described as established while SI-01 is still TODO - -Status: DONE - -Problem: - -- EPIC first-cycle says baseline established: [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L260), [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L262). -- SI-01 remains TODO in EPIC and SI-01 acceptance/checkpoints are unchecked: [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L204), [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L224), [docs/issues/drafts/1669-01-establish-baseline-analysis.md](../../drafts/1669-01-establish-baseline-analysis.md#L141). - -Why this matters: - -- Phase reporting can drift from issue status. - -Proposed minimal fix: - -- Mark SI-01 appropriately (if done), or reword EPIC first-cycle outcome to pending/in progress. - -Action taken (2026-05-18): - -- SI-01 scope extended with new task T8: research `packages/configuration` splitting into - per-service sub-packages, with two prototype scenarios (UDP-only and HTTP+REST-API) and - a trade-off table. Outcome either opens a new subissue or records a decision. -- SI-01 remains open. EPIC first-cycle outcome text still reads "Baseline established" while - SI-01 is in progress — the EPIC wording fix is deferred until SI-01 is actually complete. -- Changes committed in ff152f4c. - -### F4 (Medium) - Package count mismatch (26 vs 27) - -Status: OPEN - -Problem: - -- Coupling report says 27 workspace packages: [docs/issues/open/1669-overhaul-packages/workspace-coupling-report.md](workspace-coupling-report.md#L5). -- EPIC and SI-01 repeatedly refer to 26: [docs/issues/open/1669-overhaul-packages/EPIC.md](EPIC.md#L56), [docs/issues/drafts/1669-01-establish-baseline-analysis.md](../../drafts/1669-01-establish-baseline-analysis.md#L45), [docs/issues/drafts/1669-01-establish-baseline-analysis.md](../../drafts/1669-01-establish-baseline-analysis.md#L109). - -Why this matters: - -- Acceptance criteria and coverage checks can be off-by-one. - -Proposed minimal fix: - -- Update EPIC and SI-01 to a single source-of-truth count and timestamp, or phrase counts as point-in-time with explicit date and include/exclude rules. - -Resolution (2026-05-18): - -- The 27th package is the root `torrust-tracker` crate (the main binary, `src/`). It was - excluded from the original 26-package count because EPIC/SI-01 were drafted before the - coupling report was generated. -- All occurrences of "26 packages" updated to "27 packages" in EPIC.md (lines 46, 56, 100) - and SI-01 (Background, T2 notes, T4 notes, acceptance criteria ×2, MV1). -- MV1 verification criterion reworded to: "27 packages total: 5 leaves + 22 with deps." - -### F5 (Medium) - SI-02 prerequisite points at SI-09 T12 (doc update) instead of technical completion - -Status: DONE - -Problem: - -- SI-02 prerequisite requires SI-09 T12: [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#L68), [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#L105). -- SI-09 T12 is EPIC table/doc update, not rename mechanics: [docs/issues/drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md](../../drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md#L119). - -Why this matters: - -- Introduces avoidable scheduling blockage. - -Proposed minimal fix: - -- Change SI-02 prerequisite to SI-09 technical completion criteria (crate rename and dependency/use-path migration), not T12. - -Resolution (2026-05-18): - -- SI-09 T12 is the EPIC table update only; the actual blocker for SI-02 is T1–T4 (crate - rename, Cargo dep key updates, use-path migration). -- SI-02 prerequisite paragraph rewritten to reference SI-09 T1–T4 explicitly and note that - T12 is not a blocker. -- SI-02 T1 task description updated from "T12 of clock rename spec" to "SI-09 T1–T4 - complete (crate renamed, dep keys updated, use-paths migrated workspace-wide)". - -### F6 (Low) - SI-03 related-artifacts points to non-matching rename spec path - -Status: DONE - -Problem: - -- SI-03 related-artifacts references a rename spec path that does not match current naming: [docs/issues/drafts/1669-03-move-default-timeout-from-configuration-to-clock.md](../../drafts/1669-03-move-default-timeout-from-configuration-to-clock.md#L19). -- Existing rename draft is: [docs/issues/drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md](../../drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md). - -Why this matters: - -- Weakens traceability and tooling reliability. - -Proposed minimal fix: - -- Replace artifact path with the canonical SI-09 file path. - -Resolution (2026-05-18): - -- SI-03 `related-artifacts` entry corrected from - `docs/issues/drafts/rename-torrust-tracker-clock-to-torrust-clock.md` to - `docs/issues/drafts/1669-09-rename-torrust-tracker-clock-to-torrust-clock.md`. - -## Progress Log - -- 2026-05-18: Initial review logged with six findings, severity-ranked. -- 2026-05-18: F1 resolved and committed (f83350ee). F2 resolved and committed (6effa6a0). -- 2026-05-18: F3 partially resolved (T8 added to SI-01) and committed (ff152f4c). EPIC wording deferred to SI-01 completion. -- 2026-05-18: F4 resolved and committed (313e0d46). Package count updated 26→27; 27th is root `torrust-tracker` crate. -- 2026-05-18: F5 resolved — SI-02 prerequisite rewritten to reference SI-09 T1–T4 (technical completion), not T12. -- 2026-05-18: F6 resolved — SI-03 related-artifacts path corrected to `1669-09-rename-torrust-tracker-clock-to-torrust-clock.md`.