feat(configuration): add typed public_url fields to v3 tracker config structs by josecelano · Pull Request #2016 · torrust/torrust-tracker

josecelano · 2026-07-21T16:17:34Z

Summary

Implements sub-issue #1417 (part 4/11 of EPIC #1978 — Configuration Overhaul).

Adds a public_url field to HttpTracker, UdpTracker, and TrackerApi configuration structs, allowing operators to declare the public-facing URL for each service. The field is optional (None by default) so that all existing configurations remain valid without change.

What Changed

New: `public_url.rs` — typed URL newtypes

HttpUrl — wraps url::Url, enforces http/https scheme at construction and deserialization
UdpUrl — wraps url::Url, enforces udp scheme
Both implement Serialize, Deserialize, Display, AsRef<str>, AsRef<url::Url>

Config struct changes

Struct	New field	Type
`HttpTracker`	`public_url`	`Option<HttpUrl>`
`UdpTracker`	`public_url`	`Option<UdpUrl>`
`TrackerApi`	`public_url`	`Option<HttpUrl>`
`TrackerApi`	—	Added `#[serde(deny_unknown_fields)]` (was missing)
`HealthCheckApi`	—	Added `#[serde(deny_unknown_fields)]` for consistency

Documentation and convention enforcement

ADR docs/adrs/20260721100000_use_newtypes_for_constrained_configuration_field_types.md — records decision to use typed newtypes for domain-constrained config fields instead of String or url::Url
packages/configuration/AGENTS.md — AI-agent enforcement rules (wrong/correct examples, 8-step checklist)
Module doc notices — all nine v3_0_0 modules now carry a //! **Field type convention** notice pointing to public_url and the ADR
docs/adrs/index.md — new row for ADR 20260721100000
project-words.txt — added unvalidated

Testing

68 unit tests pass (cargo test --workspace)
Pre-commit gate green: cargo machete, cargo deny check bans, linter all, doc tests
Pre-push gate green: nightly fmt/check/doc + full stable test suite

- Mark torrust#1640 DONE in EPIC subissue table and progress log (PR torrust#2014 merged v3 network schema slice; deferred runtime consumers tracked under torrust#1980) - Mark torrust#1417 IN_PROGRESS in EPIC; start branch 1417-add-public-service-url - Update torrust#1640 spec: status done, add closed-out progress entry - Update torrust#1417 spec: scope decisions from maintainer review - public_url on HttpTracker, UdpTracker, HttpApi only (not HealthCheckApi) - url crate parse + scheme validation at deserialization - deny_unknown_fields added to HttpApi and HealthCheckApi for consistency - Revised implementation plan (T0-T6) and acceptance criteria (AC1-AC5)

Implements issue torrust#1417 (EPIC torrust#1978 subissue 4/11). - Add `HttpUrl` and `UdpUrl` newtypes to `v3_0_0/public_url.rs`. Each wraps `url::Url` and validates its scheme at construction; `Deserialize` enforces the invariant at the config boundary. - Add `public_url: Option<HttpUrl>` to `HttpTracker` and `HttpApi`. - Add `public_url: Option<UdpUrl>` to `UdpTracker`. - Add `#[serde(deny_unknown_fields)]` to `HttpApi` and `HealthCheckApi` for consistency with all other v3 structs. - Add field-type convention notice to all v3 config module docs and group `pub mod` declarations by category in `mod.rs`. - Add `packages/configuration/AGENTS.md` encoding the newtype rule for future contributors and AI agents. - Add ADR 20260721100000: use newtypes for domain-constrained config fields.

Copilot

Pull request overview

Implements configuration schema v3 support for declaring each service’s public-facing URL by introducing typed URL newtypes (HttpUrl, UdpUrl) and wiring optional public_url fields into the relevant v3 config structs. This supports upcoming use-cases like metrics labeling, logging, and service discovery in reverse-proxy and multi-domain deployments.

Changes:

Added HttpUrl / UdpUrl newtypes with scheme validation at deserialization time and TOML round-tripping.
Added public_url: Option<...> to HttpTracker, UdpTracker, and HttpApi, plus added #[serde(deny_unknown_fields)] to HttpApi and HealthCheckApi.
Added ADR + documentation/convention notes (module docs, package AGENTS.md, ADR index/issue spec updates) and updated project-words.txt.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`project-words.txt`	Adds “unvalidated” to spell-check dictionary.
`packages/configuration/src/v3_0_0/public_url.rs`	Introduces validated URL newtypes (`HttpUrl`, `UdpUrl`) with serde support + tests.
`packages/configuration/src/v3_0_0/http_tracker.rs`	Adds `public_url: Option<HttpUrl>` + tests for default/accept/reject.
`packages/configuration/src/v3_0_0/udp_tracker.rs`	Adds `public_url: Option<UdpUrl>` + tests for default/accept/reject.
`packages/configuration/src/v3_0_0/tracker_api.rs`	Adds `public_url: Option<HttpUrl>`, adds `deny_unknown_fields`, and adds tests.
`packages/configuration/src/v3_0_0/health_check_api.rs`	Adds `#[serde(deny_unknown_fields)]` and module doc notice.
`packages/configuration/src/v3_0_0/mod.rs`	Documents “typed newtypes for constrained fields” convention; exports `public_url` module; reorganizes module grouping comments.
`packages/configuration/src/v3_0_0/core.rs`	Adds module doc notice about constrained field typing.
`packages/configuration/src/v3_0_0/network.rs`	Adds module doc notice about constrained field typing.
`packages/configuration/src/v3_0_0/tls.rs`	Adds module doc notice about constrained field typing.
`packages/configuration/src/v3_0_0/logging.rs`	Adds module doc notice about constrained field typing.
`packages/configuration/src/v3_0_0/database.rs`	Adds module doc notice about constrained field typing.
`packages/configuration/AGENTS.md`	Adds package-specific AI-agent rules (newtypes, deny unknown fields, default patterns).
`docs/adrs/20260721100000_use_newtypes_for_constrained_configuration_field_types.md`	ADR recording the “use newtypes for constrained config fields” decision and rationale.
`docs/adrs/index.md`	Registers the new ADR in the ADR index.
`docs/issues/open/1978-configuration-overhaul-epic.md`	Updates EPIC tracking/status notes for subissue progression.
`docs/issues/open/1640-1978-per-http-tracker-on-reverse-proxy-setting.md`	Marks #1640 done and updates progress log.
`docs/issues/open/1417-1978-add-public-service-url-to-configuration.md`	Updates #1417 spec to match typed-newtype approach + deny-unknown-fields additions.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

codecov · 2026-07-21T16:27:33Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.46%. Comparing base (a4105db) to head (56c4a24).
⚠️ Report is 2 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #2016      +/-   ##
===========================================
- Coverage    81.51%   81.46%   -0.05%     
===========================================
  Files          340      340              
  Lines        24000    24076      +76     
  Branches     24000    24076      +76     
===========================================
+ Hits         19564    19614      +50     
- Misses        4147     4164      +17     
- Partials       289      298       +9

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

- Add #[serde(deny_unknown_fields)] to remaining v3 structs (Database, Logging, TlsConfig, Configuration) so the AGENTS.md rule 'every v3_0_0 struct must carry deny_unknown_fields' is now accurate. - Soften database.rs module doc: note that path: String is a legacy multi-driver field predating the newtype convention, tracked by torrust#1490. - Correct EPIC torrust#1978 progress log: implementation used typed newtypes (Option<HttpUrl>/Option<UdpUrl>) on three structs, not flat Option<String> on four; add PR torrust#2016 progress entry. Resolves Copilot review threads on PR torrust#2016.

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

- Add IN_REVIEW to allowed status values in EPIC torrust#1978 table - Bump EPIC last-updated-utc to 2026-07-21 17:00 - Update torrust#1417 spec: Subissue #4 of 9 -> #4 of 11 - Fix Goal section: remove HealthCheckApi from public_url scope - Fix Scope section: remove HealthCheckApi and update type from Option<String> to typed Option<HttpUrl>/Option<UdpUrl> newtypes Resolves Copilot review threads PRRT_kwDOGp2yqc6Sp69Y, PRRT_kwDOGp2yqc6Sp69_, PRRT_kwDOGp2yqc6Sp6-e, PRRT_kwDOGp2yqc6Sp6-t on PR torrust#2016.

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated no new comments.

josecelano · 2026-07-21T17:30:13Z

ACK 56c4a24

josecelano added 3 commits July 21, 2026 16:12

docs(issues): align implementation plan table in torrust#1417 spec

a2271bd

Copilot AI review requested due to automatic review settings July 21, 2026 16:17

josecelano temporarily deployed to coverage July 21, 2026 16:17 — with GitHub Actions Inactive

Copilot started reviewing on behalf of josecelano July 21, 2026 16:18 View session

josecelano self-assigned this Jul 21, 2026

Copilot AI reviewed Jul 21, 2026

View reviewed changes

Comment thread docs/issues/open/1978-configuration-overhaul-epic.md Outdated

Comment thread packages/configuration/AGENTS.md

Comment thread packages/configuration/src/v3_0_0/database.rs

Copilot AI review requested due to automatic review settings July 21, 2026 16:44

josecelano temporarily deployed to coverage July 21, 2026 16:44 — with GitHub Actions Inactive

Copilot started reviewing on behalf of josecelano July 21, 2026 16:44 View session

Copilot AI reviewed Jul 21, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 21, 2026 17:04

josecelano temporarily deployed to coverage July 21, 2026 17:04 — with GitHub Actions Inactive

Copilot started reviewing on behalf of josecelano July 21, 2026 17:05 View session

Copilot AI reviewed Jul 21, 2026

View reviewed changes

josecelano merged commit 88434c6 into torrust:develop Jul 21, 2026
18 checks passed

Navigation Menu

Uh oh!

feat(configuration): add typed public_url fields to v3 tracker config structs - #2016

feat(configuration): add typed public_url fields to v3 tracker config structs#2016
josecelano merged 5 commits into
torrust:developfrom
josecelano:1417-add-public-service-url

josecelano commented Jul 21, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jul 21, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

josecelano commented Jul 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

josecelano commented Jul 21, 2026

Summary

What Changed

New: public_url.rs — typed URL newtypes

Config struct changes

Documentation and convention enforcement

Testing

Related

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

josecelano commented Jul 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

New: `public_url.rs` — typed URL newtypes

codecov Bot commented Jul 21, 2026 •

edited

Loading