Skip to content

docs(packages): add epic spec and subissue drafts for packages overhaul #1669 #1789

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
josecelano wants to merge 1 commit into
base: develop
Choose a base branch
from
Draft

docs(packages): add epic spec and subissue drafts for packages overhaul #1669 #1789

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 163 additions & 0 deletions docs/issues/drafts/1669-02-move-duration-since-unix-epoch-to-torrust-clock.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
---

<!-- skill-link: create-issue -->

# 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 | |
147 changes: 147 additions & 0 deletions docs/issues/drafts/1669-03-move-default-timeout-from-configuration-to-clock.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
---

<!-- skill-link: create-issue -->

# 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 | |
Loading