Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
Original file line number Diff line number Diff line change
Expand Up @@ -44,10 +44,9 @@ semantic-links:
- docs/containers.md
---


# Issue #1640 - Move `on_reverse_proxy` to per-tracker config (and relocate `Network`)

> **EPIC position**: Subissue #3 of 9. Depends on #2 (tsltls typo fix). Must be implemented before #1417 (public_url) and #1490 (secrets) — both reference the `Network` block established here. Both #1640 and #1490 touch `Core`, so #1640 goes first.
> **EPIC position**: Subissue #3 of 11. Depends on #2 (`tsl` → `tls` typo fix). Must be implemented before #1417 (public_url) and #1490 (secrets) — both reference the `Network` block established here. Both #1640 and #1490 touch `Core`, so #1640 goes first.

## Goal

Expand Down Expand Up @@ -149,7 +148,7 @@ pub struct Network {
// Server-layer config for each HTTP tracker
pub struct HttpTracker {
pub bind_address: SocketAddr,
pub tsl_config: Option<TslConfig>,
pub tls_config: Option<TlsConfig>,
pub tracker_usage_statistics: bool,
pub net: Network, // ← replaces individual fields
// ipv6_v6only REMOVED — now inside net
Expand Down Expand Up @@ -184,7 +183,7 @@ pub struct Core {
We considered moving `bind_address` into `Network` since it is a networking concern. We decided to keep it flat for two reasons:

1. **Primary key role**: `bind_address` is the HashMap key for tracker instance containers in `AppContainer` (`HashMap<SocketAddr, Arc<HttpTrackerCoreContainer>>`). Nesting it inside `net` would make lookup more cumbersome without benefit.
2. **TLS asymmetry**: `tsl_config` (TLS certificate paths) cannot go into `Network`. Keeping `bind_address` and `tsl_config` at the same level while `on_reverse_proxy`, `external_ip`, and `ipv6_v6only` group into `net` creates a cleaner boundary between _socket binding_ (flat) and _socket behaviour / network identity_ (grouped).
2. **TLS asymmetry**: `tls_config` (TLS certificate paths) cannot go into `Network`. Keeping `bind_address` and `tls_config` at the same level while `on_reverse_proxy`, `external_ip`, and `ipv6_v6only` group into `net` creates a cleaner boundary between _socket binding_ (flat) and _socket behaviour / network identity_ (grouped).

### Compatibility with Existing ADRs

Expand Down Expand Up @@ -255,12 +254,12 @@ These fields (`domain`, `use_tls_proxy`) describe how each tracker instance is e

> **Note on TLS vs reverse proxy**: There are two independent TLS configurations:
>
> - `tsl_config` on `HttpTracker` — the tracker terminates TLS **directly** (clients connect via HTTPS directly to the tracker). No proxy involved.
> - `tls_config` on `HttpTracker` — the tracker terminates TLS **directly** (clients connect via HTTPS directly to the tracker). No proxy involved.
> - `use_tls_proxy` in the deployer — TLS is terminated at a **reverse proxy** (Caddy, nginx) before forwarding plain HTTP to the tracker.
>
> Both are orthogonal to `on_reverse_proxy` (trusting `X-Forwarded-For` headers). You can have:
>
> - Direct HTTPS tracker (`tsl_config` set) with or without trusting proxy headers
> - Direct HTTPS tracker (`tls_config` set) with or without trusting proxy headers
> - Tracker behind a TLS proxy (`use_tls_proxy`) with `on_reverse_proxy = true` (common case)
> - Tracker behind a plain HTTP proxy (no TLS) with `on_reverse_proxy = true`
> - Tracker directly exposed via plain HTTP without any proxy
Expand Down Expand Up @@ -305,7 +304,7 @@ pub struct Network { // † this issue
pub struct HttpTracker {
// Socket binding — how the OS binds the listener
pub bind_address: SocketAddr,
pub tsl_config: Option<TslConfig>, // direct TLS (tracker terminates)
pub tls_config: Option<TlsConfig>, // direct TLS (tracker terminates)

// Instance metadata
pub tracker_usage_statistics: bool,
Expand Down
31 changes: 13 additions & 18 deletions docs/issues/open/1978-configuration-overhaul-epic.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ status: open
github-issue: 1978
spec-path: docs/issues/open/1978-configuration-overhaul-epic.md
epic-owner: josecelano
last-updated-utc: 2026-07-20 12:23
last-updated-utc: 2026-07-20 15:25
semantic-links:
skill-links:
- create-issue
Expand Down Expand Up @@ -83,8 +83,8 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`.

| Order | Issue | Local Spec | Status | Notes |
| ----- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------- |
| 1 | [#1979](../../issues/1979) — Copy `v2_0_0` → `v3_0_0` as baseline | `docs/issues/open/1979-1978-copy-configuration-schema-v2-to-v3-baseline.md` | TODO | Foundation: all other subissues depend on this |
| 2 | [#1981](../../issues/1981) — Fix `tsl_config` → `tls_config` typo | `docs/issues/open/1981-1978-fix-tsl-config-tls-config-typo.md` | TODO | Mechanical rename; ~21 files; do early to avoid conflicts with #5 |
| 1 | [#1979](../../issues/1979) — Copy `v2_0_0` → `v3_0_0` as baseline | `docs/issues/open/1979-1978-copy-configuration-schema-v2-to-v3-baseline.md` | DONE | Merged in PR #1999; v3 baseline and smoke tests are in `develop` |
| 2 | [#1981](../../issues/1981) — Fix `tsl_config` → `tls_config` typo | `docs/issues/open/1981-1978-fix-tsl-config-tls-config-typo.md` | DONE | Implemented for v3; v2 compatibility retained until final migration |
| 3 | [#1640](../../issues/1640) — Support per-HTTP-tracker `on_reverse_proxy` setting | `docs/issues/open/1640-1978-per-http-tracker-on-reverse-proxy-setting.md` | TODO | Heaviest change (~30 files); establishes per-instance `Network` block |
| 4 | [#1417](../../issues/1417) — Include public service URL in configuration | `docs/issues/open/1417-1978-add-public-service-url-to-configuration.md` | TODO | Depends on #3 for `Network` placement decision; adds flat `public_url` field |
| 5 | [#1415](../../issues/1415) — Use `ServiceBinding` instead of bare `SocketAddr` for service identity | `docs/issues/open/1415-1978-use-service-binding-instead-of-socket-addr.md` | TODO | Independent; no config changes; can be parallel with #6, #7, #8, #9 |
Expand Down Expand Up @@ -174,23 +174,14 @@ For each subissue implementation in this EPIC, the default completion policy is:

### Workflow Checkpoints

- [ ] Epic spec drafted in `docs/issues/drafts/`
- [ ] Epic spec reviewed and approved by user/maintainer
- [ ] GitHub epic issue created and issue number added to this spec
- [x] Subissues created and linked in this spec
- [ ] Subissue statuses kept up to date in the `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 acceptance criteria reviewed and checked off
- [x] Epic spec drafted in `docs/issues/open/1978-configuration-overhaul-epic.md`
- [x] Epic spec reviewed and approved by user/maintainer
- [x] GitHub epic issue created: #1978
- [x] Subissues created and linked in this spec
- [ ] Subissue statuses kept up to date in the `Subissues` table
- [ ] For each implemented subissue: automatic checks completed and recorded
- [x] Subissue statuses kept up to date in the `Subissues` table
- [x] 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
- [x] For each implemented subissue: acceptance criteria reviewed post-implementation
- [ ] Epic acceptance criteria reviewed and checked off
- [ ] Epic issue closed and spec moved from `docs/issues/open/` to `docs/issues/closed/`

Expand All @@ -207,13 +198,17 @@ For each subissue implementation in this EPIC, the default completion policy is:
- 2026-07-20 12:12 UTC - agent - Added #1136 as subissue 7 of 11 after #1453; documented the secure-default per-listener UDP connection ID validation policy and reconciled the local EPIC with existing subissue #1987.
- 2026-07-20 12:23 UTC - agent - Updated the GitHub EPIC body, linked #1136,
and verified all 11 native subissues in the documented order.
- 2026-07-20 13:21 UTC - agent - Recorded #1979 as completed by merged PR #1999 and
started #1981 as the next subissue; identified its schema compatibility boundary for maintainer review.
- 2026-07-20 15:25 UTC - agent - Completed #1981 with v3-corrected TLS names and
schema-neutral module naming; preserved v2 compatibility and verified the full workspace. #1640 is next.

## Acceptance Criteria

- [x] All required subissues are created and linked.
- [ ] Implementation order is explicit and justified.
- [ ] Dependencies and blockers are documented and current.
- [ ] Epic status reflects actual state of linked subissues.
- [x] Implementation order is explicit and justified.
- [x] Dependencies and blockers are documented and current.
- [x] Epic status reflects actual state of linked subissues.
- [ ] Every completed subissue includes automated verification evidence.
- [ ] Every completed subissue includes manual verification evidence.
- [ ] Every completed subissue includes post-implementation acceptance criteria review.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
---
doc-type: issue
issue-type: task
status: open
status: done
priority: p0
github-issue: 1979
spec-path: docs/issues/open/1979-1978-copy-configuration-schema-v2-to-v3-baseline.md
branch: "config-copy-v2-to-v3-baseline"
related-pr: 1999
last-updated-utc: 2026-07-13 21:00
last-updated-utc: 2026-07-20 13:21
semantic-links:
skill-links:
- create-issue
Expand All @@ -17,7 +17,6 @@ semantic-links:
- share/default/config/
---


# Issue #1979 - Copy configuration schema v2_0_0 to v3_0_0 as baseline

> **EPIC position**: Subissue #1 of 9 in EPIC #1978. **Foundation — all other subissues depend on this.** Must be merged before any other subissue begins.
Expand Down Expand Up @@ -76,18 +75,19 @@ This approach:

- [ ] Spec drafted in `docs/issues/drafts/`
- [ ] Spec reviewed and approved by user/maintainer
- [ ] GitHub issue created and issue number added to this spec
- [ ] Implementation completed
- [ ] Automatic verification completed (`linter all`, relevant tests)
- [x] GitHub issue created and issue number added to this spec
- [x] Implementation completed
- [x] Automatic verification completed (`linter all`, relevant tests)
- [ ] Manual verification scenarios executed and recorded
- [ ] Acceptance criteria reviewed after implementation
- [ ] Issue closed and spec moved to `docs/issues/open/`
- [x] Acceptance criteria reviewed after implementation
- [ ] Issue closed and spec moved from `docs/issues/open/` to `docs/issues/closed/`

### Progress Log

- 2026-07-13 21:00 UTC - josecelano - Initial spec drafted
- 2026-07-15 00:00 UTC - josecelano - GitHub issue #1979 created; spec moved to `docs/issues/open/1979-1978-copy-configuration-schema-v2-to-v3-baseline.md`
- 2026-07-20 00:00 UTC - agent - Implementation completed: T1–T5 and T8–T9 done; T6/T7 deferred to #1980 (consumer migration must happen atomically)
- 2026-07-20 13:21 UTC - agent - Reconciled the spec after PR #1999 merged; automatic verification and acceptance review are complete, while manual scenarios and archival remain open.

## Acceptance Criteria

Expand Down
Loading
Loading