docs(issues): refine epic subissue specifications

Author: josecelano

docs/issues/1532-http-tracker-client-add-optional-announce-params.md

@@ -61,28 +61,39 @@ cargo run -p torrust-tracker-client --bin http_tracker_client announce \
 
 Supported `--event` values: `started`, `stopped`, `completed` (case-insensitive).
 
+`--peer-id` input contract:
+
+- Accept a 20-character ASCII value.
+- Reject any value that is not exactly 20 bytes.
+- Surface validation errors as CLI argument errors.
+
 ## Goals
 
 - [ ] Add optional CLI flags to the `announce` sub-command in
       `console/tracker-client/src/console/clients/http/app.rs`:
       `--event`, `--uploaded`, `--downloaded`, `--left`, `--port`, `--peer-addr`,
       `--peer-id`, `--compact`
-- [ ] Parse each flag and pass its value to the corresponding `QueryBuilder` setter
+- [ ] Parse each flag and map it into `announce::Query` values
+- [ ] Extend `QueryBuilder` with missing setters for
+      `event`, `uploaded`, `downloaded`, `left`, and `port`
 - [ ] Defaults remain unchanged when a flag is omitted
-- [ ] Add `FromStr` / `clap` value parsing for `Event` (already has `Display`; needs `FromStr`)
+- [ ] Add CLI parsing for `Event` in the tracker-client layer
 - [ ] Pass `linter all` and `cargo machete` with zero warnings
 - [ ] Update the module-level doc comment in `app.rs` with new usage examples
 
 ## Implementation Plan
 
-### Task 1: Add `FromStr` for `Event`
+### Task 1: Add CLI parsing for `Event`
 
-`Event` already implements `Display`. Add a `FromStr` implementation (or derive it via `clap`'s
-`ValueEnum`) so it can be parsed directly from the command line.
+Use a CLI-facing enum (for example `CliEvent`) in
+`console/tracker-client/src/console/clients/http/app.rs` and map it into
+`bittorrent_tracker_client::http::client::requests::announce::Event`.
 
-- [ ] Implement `clap::ValueEnum` for `Event` in
-      `packages/tracker-client/src/http/client/requests/announce.rs`
-      (or add `FromStr` and map it in the CLI layer)
+Do not rely on `packages/http-protocol` `Event`, which is a different type and
+belongs to a different layer.
+
+- [ ] Implement `clap::ValueEnum` for the CLI-facing `event` type
+- [ ] Add explicit mapping from CLI event type to tracker-client request `Event`
 
 ### Task 2: Extend the `Announce` sub-command struct
 
@@ -95,7 +106,7 @@ Announce {
     tracker_url: String,
     info_hash: String,
     #[arg(long)]
-    event: Option<Event>,
+  event: Option<CliEvent>,
     #[arg(long)]
     uploaded: Option<u64>,
     #[arg(long)]
@@ -109,14 +120,20 @@ Announce {
     #[arg(long, name = "peer-id")]
     peer_id: Option<String>,
     #[arg(long)]
-    compact: Option<u8>,
+    compact: Option<CliCompact>,
 }
 ```
 
+`CliCompact` should accept only `0` and `1` and map to
+`announce::Compact::{NotAccepted, Accepted}`.
+
 ### Task 3: Thread optional values through `announce_command`
 
 - [ ] Update `announce_command` signature to accept the optional parameters
+- [ ] Add missing `QueryBuilder` setters in
+      `packages/tracker-client/src/http/client/requests/announce.rs`
 - [ ] Apply each `Some(value)` to the `QueryBuilder` chain before calling `.query()`
+- [ ] Parse and validate `--peer-id` into `bittorrent_udp_tracker_protocol::PeerId`
 
 ### Task 4: Update docs
 

docs/issues/1533-udp-tracker-client-add-optional-announce-params.md

@@ -64,6 +64,12 @@ cargo run -p torrust-tracker-client --bin udp_tracker_client announce \
 Supported `--event` values: `none`, `completed`, `started`, `stopped` (matching
 `bittorrent_udp_tracker_protocol::AnnounceEvent` variants, case-insensitive).
 
+`--peer-id` input contract:
+
+- Accept a 20-character ASCII value.
+- Reject any value that is not exactly 20 bytes.
+- Surface validation errors as CLI argument errors.
+
 ## Goals
 
 - [ ] Add optional CLI flags to the `Announce` variant in
@@ -137,6 +143,8 @@ Announce {
       `checker::Client::send_announce_request()`
 - [ ] Update `send_announce_request` in `checker.rs` to accept an optional parameter struct
       (or individual `Option` arguments) and apply overrides when `Some`
+- [ ] Validate and parse `--peer-id` into `bittorrent_udp_tracker_protocol::PeerId`
+- [ ] Reject negative values for `uploaded`, `downloaded`, and `left` at the CLI layer
 
 ### Task 4: Update docs
 

docs/issues/1561-http-tracker-client-avoid-duplicating-announce-suffix.md

@@ -13,6 +13,14 @@ accept both forms:
 - base URL, for example `https://tracker.torrust-demo.com/`
 - full announce URL, for example `https://tracker.torrust-demo.com/announce`
 
+The `/announce` suffix is common in public tracker lists (for example
+newtrackon), but not guaranteed by protocol-level requirements. The client
+should therefore support a mixed strategy:
+
+- If the input URL path is empty (domain only) or exactly `/`, append
+  `/announce`.
+- If the input URL already contains a path segment, keep it as provided.
+
 - GitHub issue: <https://github.com/torrust/torrust-tracker/issues/1561>
 - Parent EPIC: <https://github.com/torrust/torrust-tracker/issues/669>
 
@@ -69,33 +77,35 @@ Expected accepted inputs for announce:
 - `https://tracker.torrust-demo.com`
 - `https://tracker.torrust-demo.com/`
 - `https://tracker.torrust-demo.com/announce`
+- `https://tracker.torrust-demo.com/custom-tracker-endpoint`
 
 Expected final request path for announce:
 
-- exactly one `/announce`
-
-Expected accepted inputs for scrape:
-
-- `https://tracker.torrust-demo.com`
-- `https://tracker.torrust-demo.com/`
-- `https://tracker.torrust-demo.com/scrape`
+- exactly one effective endpoint path, resolved by the rule below
 
-Expected final request path for scrape:
+Path resolution rule for `announce`:
 
-- exactly one `/scrape`
+- Input path empty or `/` -> resolve to `/announce`
+- Input path non-empty (for example `/announce`, `/foo`, `/foo/bar`) -> keep it
+  unchanged
 
 The client should not rely on callers pre-trimming or pre-normalizing the URL.
 
+Scope note: this issue is about tracker protocol endpoints (`announce` and
+`scrape`). The `health_check` endpoint is out of scope.
+
 ## Goals
 
 - [ ] Accept both bare tracker base URLs and full announce URLs in the HTTP
       client
+- [ ] Append `/announce` only for bare URLs (`host` or `host/`)
+- [ ] Keep provided path unchanged when a non-empty path already exists
 - [ ] Avoid duplicating the `announce` path suffix in the final request URL
-- [ ] Avoid duplicating the `scrape` path suffix in the final request URL
 - [ ] Keep authenticated path handling working, including URLs that append the
       authentication key after the endpoint path
 - [ ] Preserve existing behaviour for valid base URLs
 - [ ] Add tests covering the supported input forms
+- [ ] Keep `health_check` behaviour unchanged in this issue
 - [ ] `linter all` exits with code `0`
 - [ ] `cargo machete` reports no unused dependencies
 - [ ] Existing tests pass
@@ -117,12 +127,14 @@ Instead, add a helper that derives a normalized endpoint URL from the parsed
 
 The key rule is: the final URL must contain the endpoint suffix exactly once.
 
-### Task 2: Normalize announce and scrape independently
+### Task 2: Apply base-URL detection for announce
+
+For announce requests:
 
-Ensure announce requests always resolve to exactly one `announce` segment and
-scrape requests always resolve to exactly one `scrape` segment.
+- If the input URL path is empty or `/`, append `announce`
+- Otherwise, keep the original path unchanged
 
-Do not implement a narrow fix that only handles `announce`.
+Do not append `announce` when any path segment already exists.
 
 ### Task 3: Preserve authenticated endpoint support
 
@@ -151,8 +163,7 @@ Add tests in `packages/tracker-client/src/http/client/mod.rs` covering at least:
 - base URL without trailing slash + announce
 - base URL with trailing slash + announce
 - full `/announce` URL + announce
-- base URL without trailing slash + scrape
-- full `/scrape` URL + scrape
+- full custom path URL + announce (path unchanged)
 - authenticated announce path with a full `/announce` base URL
 
 The tests should assert the exact final URL string.
@@ -163,16 +174,20 @@ Update the module docs in
 `console/tracker-client/src/console/clients/http/app.rs` or package docs so the
 accepted URL forms are explicit.
 
+### Task 6: Keep `health_check` out of scope
+
+Do not change `health_check` behavior as part of this bug fix. If endpoint
+normalization is later generalized to all methods, that should be handled in a
+separate issue with dedicated tests.
+
 ## Acceptance Criteria
 
 - [ ] Passing `https://tracker.torrust-demo.com` to the announce command sends
       the request to `/announce`
 - [ ] Passing `https://tracker.torrust-demo.com/announce` to the announce
       command also sends the request to `/announce`
-- [ ] Passing `https://tracker.torrust-demo.com` to the scrape command sends
-      the request to `/scrape`
-- [ ] Passing `https://tracker.torrust-demo.com/scrape` to the scrape command
-      also sends the request to `/scrape`
+- [ ] Passing a URL with a non-empty path (for example `/foo`) keeps `/foo`
+      unchanged and does not append `announce`
 - [ ] Authenticated requests still generate correct URLs
 - [ ] No duplicated endpoint suffix appears in final request URLs
 - [ ] `linter all` exits with code `0`

docs/issues/1562-http-tracker-client-add-option-show-response-pretty-json.md

@@ -41,6 +41,10 @@ Add `--format` to HTTP commands with the following values:
 - `compact` (default)
 - `pretty`
 
+Formatting applies to both typed responses and fallback JSON generated for
+unrecognized responses (from #672). Raw-byte fallback remains plain text and is
+not reformatted.
+
 Defaulting to `compact` is intentional because:
 
 - It is better for shell pipelines and machine parsing.
@@ -121,6 +125,8 @@ Update examples in `app.rs` module docs to include `--format pretty` usage.
 - [ ] `announce --format pretty` prints multiline indented JSON
 - [ ] `scrape --format pretty` prints multiline indented JSON
 - [ ] Omitting `--format` still produces compact single-line JSON
+- [ ] When fallback JSON is produced, `--format pretty` prints indented JSON and
+      default output remains compact
 - [ ] Invalid format values are rejected by clap with usage guidance
 - [ ] `linter all` exits with code `0`
 - [ ] `cargo machete` reports no unused dependencies

docs/issues/1563-udp-tracker-client-add-option-show-response-pretty-json.md

@@ -43,6 +43,10 @@ Add `--format` to UDP commands with values:
 - `compact` (default)
 - `pretty`
 
+Formatting applies to both typed responses and fallback JSON generated for
+unrecognized responses (from #671 style behavior). Raw-byte fallback remains
+plain text and is not reformatted.
+
 Defaulting to `compact` is intentional because:
 
 - It is better for shell pipelines and machine parsing.
@@ -128,6 +132,8 @@ Update examples to show both default and explicit `--format pretty` usage.
 - [ ] Running UDP `announce --format compact` prints single-line JSON
 - [ ] Running UDP `scrape --format pretty` prints multiline JSON
 - [ ] Omitting `--format` produces compact single-line JSON
+- [ ] When fallback JSON is produced, `--format pretty` prints indented JSON and
+      default output remains compact
 - [ ] Invalid format values are rejected by clap with usage guidance
 - [ ] `linter all` exits with code `0`
 - [ ] `cargo machete` reports no unused dependencies

docs/issues/672-http-tracker-client-print-unrecognized-responses.md

@@ -47,6 +47,9 @@ let scrape_response = scrape::Response::try_from_bencoded(&body)
 `scrape::Response::try_from_bencoded` also panics internally via
 `serde_bencode::from_bytes(bytes).expect(...)`.
 
+The scrape parser path also contains nested `.unwrap()` calls while iterating
+decoded file dictionaries. Those must be removed from reachable runtime paths.
+
 ## Proposed Behaviour
 
 The two-step fallback strategy:
@@ -80,14 +83,17 @@ Warning: Could not deserialize HTTP tracker response. Raw bytes: [100, 56, ...]
 
 - [ ] Replace both `panic!(...)` / `.unwrap_or_else(|_| panic!(...))` calls in `app.rs` with
       graceful fallback logic
-- [ ] Remove the `panic!` inside `scrape::Response::try_from_bencoded`; change the internal
-      `expect(...)` to return `Err` properly
+- [ ] Remove panic/unwrap usage from the scrape decode path:
+      `expect(...)` in `try_from_bencoded` and nested `.unwrap()` calls in
+      parser helpers
 - [ ] Add `bencode2json` as a dependency of the `torrust-tracker-client` console crate
 - [ ] On deserialization failure, print the raw bencoded payload as generic JSON (via
       `bencode2json`)
 - [ ] If `bencode2json` conversion also fails, print a warning with the raw byte slice
 - [ ] The process exits with a non-zero exit code when the response cannot be deserialized
       (print the fallback JSON/bytes to stdout, return an `Err` from the command function)
+- [ ] Fallback JSON output is compact by default in this issue; once `--format`
+      is introduced in #1562, fallback JSON must respect the selected format
 - [ ] `linter all` exits with code `0`
 - [ ] `cargo machete` reports no unused dependencies
 - [ ] All existing tests pass
@@ -109,6 +115,9 @@ pub fn try_from_bencoded(bytes: &[u8]) -> Result<Self, BencodeParseError> {
 
 A new `BencodeParseError` variant may be needed for `serde_bencode::Error`.
 
+Also replace nested `.unwrap()` calls in scrape parsing helpers with proper
+error propagation into `BencodeParseError`.
+
 ### Task 2: Add `bencode2json` dependency
 
 In `console/tracker-client/Cargo.toml`, add:
@@ -169,6 +178,7 @@ Add examples showing the fallback output in the module-level doc comment.
 - [ ] Running the client against the Torrust Tracker still prints the typed JSON response
       and exits `0`
 - [ ] No `panic!` or `.unwrap()` in the announce or scrape command paths
+- [ ] No reachable panic/unwrap remains in the scrape decoding path
 - [ ] `linter all` exits with code `0`
 - [ ] `cargo machete` reports no unused dependencies
 - [ ] All existing tests pass

project-words.txt

@@ -167,6 +167,7 @@ mysqld
 Naim
 nanos
 newkey
+newtrackon
 newtype
 newtypes
 nextest