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 @@ -9,7 +9,7 @@ github-issue: 2448
spec-path: docs/issues/closed/2448-1488-si-17-migrate-standalone-udp-environment/ISSUE.md
branch: "2448-migrate-standalone-udp-environment"
related-pr: 2459
last-updated-utc: "2026-10-25 08:09"
last-updated-utc: "2026-10-26 19:50"
semantic-links:
skill-links:
- create-issue
Expand All @@ -31,7 +31,7 @@ semantic-links:
- docs/issues/closed/2342-1488-si-14-migrate-udp-receive-reset-token-lifecycle/ISSUE.md
- docs/issues/closed/2370-1488-si-15-define-udp-active-request-policy/ISSUE.md
- docs/issues/closed/2449-1488-si-23-migrate-rest-api-test-environment/ISSUE.md
- docs/issues/open/2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md
- docs/issues/closed/2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md
- docs/issues/closed/2410-1488-si-22-process-queued-events-before-listeners-stop/EPIC.md
- docs/issues/open/1488-overhaul-tracker-shutdown/ISSUE.md
---
Expand Down Expand Up @@ -360,7 +360,7 @@ Notes:
health-check API environments stop through the legacy path. Found while
refreshing this spec; the maintainer chose one item each:
[SI-23](../2449-1488-si-23-migrate-rest-api-test-environment/ISSUE.md) (#2449) and
[SI-24](../../open/2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md) (#2450).
[SI-24](../2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md) (#2450).

## Rollback

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,14 @@
schema-version: 1
doc-type: issue
issue-type: task
status: planned
status: done
priority: p2
epic: 1488
github-issue: 2450
spec-path: docs/issues/open/2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md
spec-path: docs/issues/closed/2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md
branch: "2450-migrate-health-check-api-test-environment"
related-pr: 2652
last-updated-utc: "2026-10-26 16:31"
last-updated-utc: "2026-10-26 20:04"
semantic-links:
skill-links:
- create-issue
Expand Down Expand Up @@ -186,8 +186,8 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`.
| T1 | DONE | Migrate `Environment` start/stop | D1-D5, with the T1 tests below, each mutation-proven. |
| T2 | DONE | Migrate the field reads | Contract tests use `bind_address()`. |
| T3 | DONE | Documentation | Task inventory records the migrated health-check API environment. |
| T4 | IN_PROGRESS | Verification and completion review | Automatic checks, manual scenario, AC review, pre-push checks, independent review. |
| T5 | IN_PROGRESS | Review round on #2652 | `stop()` deregisters (D6), the F3 correction, the audit; a new independent review on the final tree. |
| T4 | DONE | Verification and completion review | Automatic checks, manual scenario, AC review, pre-push checks, independent review. |
| T5 | DONE | Review round on #2652 | `stop()` deregisters (D6), the F3 correction, the audit; a new independent review on the final tree. |

T1 tests (use the `write-unit-test` skill, every wait bounded):

Expand Down Expand Up @@ -225,12 +225,12 @@ before maintainer review and commit. Sign every commit with GPG.
- [x] Implementation completed
- [x] Automatic verification completed (`linter all`, relevant tests, and pre-push checks)
- [x] Manual verification scenarios executed and recorded in issue-local `manual-verification-evidence.md`
- [ ] Acceptance criteria reviewed after implementation and updated with evidence
- [x] Acceptance criteria reviewed after implementation and updated with evidence
- [x] Evidence-based implementation completion review recorded: issue-local retrospective created for material discoveries, or progress log states why none was needed
- [ ] Reviewer validated acceptance criteria and updated checkboxes
- [x] Reviewer validated acceptance criteria and updated checkboxes
- [x] Independent reviewer reports recorded in issue-local `agent-review-reports.md`
- [ ] Committer verified spec progress is up to date before commit
- [ ] Issue closed and spec moved from `docs/issues/open/` to `docs/issues/closed/`
- [x] Committer verified spec progress is up to date before commit
- [x] Issue closed and spec moved from `docs/issues/open/` to `docs/issues/closed/`

### Progress Log

Expand All @@ -246,28 +246,30 @@ before maintainer review and commit. Sign every commit with GPG.
- 2026-10-26 12:42 UTC - GitHub Copilot - Copilot's review of #2652 (`review-finding:pr-2652-f1`) found that a fixed-port stop-then-start panics, because the token-aware start registers the service and the `Registar` cannot remove it. This corrects the 07:38 entry: the discovery is material, so `implementation-retrospective.md` is added. The maintainer chose to document and pin the limitation and file a follow-up; recorded in V7, with V6 re-run after the new last production change. The acceptance criteria stay TODO.
- 2026-10-26 16:24 UTC - GitHub Copilot - Review round on #2652 (`review-finding:pr-2652-f1`, `-f2`, `-f3`). This reverses the 12:42 UTC decision to document the fixed-port limitation: da2ce7 re-raised the finding as a Major (`-f2`) and asked for the fix, and measuring the cost showed a small additive registry method was enough. The maintainer chose to fix it in this PR (route R1) with `Registar::deregister`. Opened torrust/torrust-server-lib#2 at 16:04 UTC (CI green, merged 16:19 UTC), published `torrust-server-lib` 0.4.0, bumped it here, and made `stop()` deregister its own binding (D6, AC8), also when a task failed, with a green fixed-port restart test replacing the `should_panic` pin. The earlier independent review entry is corrected in `agent-review-reports.md` (`-f3`). V6 and V7 and the retrospective are rewritten to the final state. A new independent review on the final tree and the audit follow. The acceptance criteria stay TODO.
- 2026-10-26 16:31 UTC - GitHub Copilot - A new independent Task Reviewer ran on the final tree and returned REVIEW FAILED for one documentation blocker (V5 lacked the prose-first comparison of the three tests added in this round) and six low findings, with no production defect; recorded in `agent-review-reports.md`. Fixed: V5 now covers the eleven environment tests, the production call-site count is corrected from eight to seven, V4 is labelled as measured at T1, `related-pr` is set, and the dropped-`stop()` risk is stated. The acceptance criteria stay TODO.
- 2026-10-26 19:50 UTC - GitHub Copilot - PR #2652 merged on 2026-10-26 at 19:34 UTC by the maintainer, and #2450 is closed. The maintainer merged without waiting for the re-requested review of da2ce7, whose earlier findings F2 and F3 were fixed and their threads resolved. Archived this spec to `docs/issues/closed/`: `status: done`, `spec-path` and `issue-spec` updated, T4 and T5 marked DONE, the roadmap row 17 of EPIC #1488 marked Done, and every live link to the old `docs/issues/open/` path repaired. The acceptance criteria and the checkpoints for AC review, reviewer validation and committer verification stay unticked: the maintainer has not told the author to tick them.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Minor][F1] Repair the remaining live audit reference to the moved spec

The new archive entry says every live link was repaired, but docs/pr-reviews/pr-2451-review/PR-REVIEW.md:9 still lists docs/issues/open/2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md under semantic-links.related-artifacts. That target exists at the base and is removed here. This is current navigational metadata, not a dated command quotation, so the archive skill's historical-record exception does not apply. Update that entry to the closed path while preserving historical prose. The omitted audit file is outside this diff; this comment is anchored to the new claim that its reference was repaired.

- 2026-10-26 20:04 UTC - GitHub Copilot - The maintainer told the author to tick the acceptance criteria. This corrects the 19:50 UTC entry, which said they stay unticked: AC1 to AC8, the definition-of-done items and the checkpoints for AC review, reviewer validation and committer verification are now ticked, each AC row has its evidence pointer, and the evidence is the final-tree review in `agent-review-reports.md` and `manual-verification-evidence.md` (V0 to V7).

## Acceptance Criteria

- [ ] AC1: `Environment` starts the health-check API through
- [x] AC1: `Environment` starts the health-check API through
`start_with_cancellation`.
- [ ] AC2: `Environment::stop()` cancels the token and joins the server task
- [x] AC2: `Environment::stop()` cancels the token and joins the server task
and the drain controller.
- [ ] AC3: `stop()` returns an error naming each failing task, after joining
- [x] AC3: `stop()` returns an error naming each failing task, after joining
both, and keeps its current signature (D1).
- [ ] AC4: A stopped environment can be started again, on an ephemeral or a
- [x] AC4: A stopped environment can be started again, on an ephemeral or a
fixed port, and serves the health check.
- [ ] AC5: No caller reads the environment's running state directly.
- [ ] AC6: The shutdown task inventory reflects the migration.
- [ ] AC7: Dropping a running environment without `stop()` releases its
- [x] AC5: No caller reads the environment's running state directly.
- [x] AC6: The shutdown task inventory reflects the migration.
- [x] AC7: Dropping a running environment without `stop()` releases its
binding within the test deadline.
- [ ] AC8: `stop()` removes the environment's own registration from the
- [x] AC8: `stop()` removes the environment's own registration from the
`registar`, also when a task failed, and keeps the services of other
owners (D6).
- [ ] `linter all` exits with code `0`
- [ ] Relevant tests pass
- [ ] Manual verification scenarios are executed and documented in issue-local `manual-verification-evidence.md`
- [ ] Acceptance criteria are re-reviewed after implementation and reflect actual behavior
- [x] `linter all` exits with code `0`
- [x] Relevant tests pass
- [x] Manual verification scenarios are executed and documented in issue-local `manual-verification-evidence.md`
- [x] Acceptance criteria are re-reviewed after implementation and reflect actual behavior

## Verification Plan

Expand Down Expand Up @@ -299,14 +301,14 @@ Notes:

| AC ID | Status (`TODO`/`DONE`) | Evidence |
| ----- | ---------------------- | -------- |
| AC1 | TODO | |
| AC2 | TODO | |
| AC3 | TODO | |
| AC4 | TODO | |
| AC5 | TODO | |
| AC6 | TODO | |
| AC7 | TODO | |
| AC8 | TODO | |
| AC1 | DONE | `environment.rs` `start()` calls `server::start_with_cancellation`; no `Halted` in the module (evidence V3). Final review: `agent-review-reports.md`, entry 16:32 UTC. |
| AC2 | DONE | Tests `it_should_stop_without_a_failure_when_the_server_and_its_drain_controller_finish_through_cancellation` and `it_should_release_the_health_check_api_binding_when_stopped`; mutation M1 (evidence V2). |
| AC3 | DONE | Join and error tests in `environment::tests` (V1, V2); signature unchanged; `contract.rs` callers unchanged. |
| AC4 | DONE | `it_should_serve_requests_after_being_stopped_and_started_again` (port 0) and `it_should_serve_requests_after_being_stopped_and_started_again_on_a_fixed_port` (evidence V7). |
| AC5 | DONE | No `state.binding` or `env.state` read in `tests/`; `state` and `Running` are private; callers use `bind_address()` (evidence V0 and V1). |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Nit][F2] Describe the actual visibility boundary in the acceptance evidence

The new evidence says Running is private, but packages/axum-health-check-api-server/src/environment.rs:36 declares pub struct Running. Its fields and Environment::state are private, which is sufficient for AC5 and the accessor migration. Correct the evidence to describe those fields rather than claim that the public typestate itself became private; no runtime change is needed.

| AC6 | DONE | `docs/features/shutdown-process/task-inventory.md`, health-check row of the test environments table. |
| AC7 | DONE | `it_should_release_the_health_check_api_binding_when_dropped_without_being_stopped` (evidence V2). |
| AC8 | DONE | `it_should_remove_only_its_own_registration_from_the_registar_when_stopped` and `it_should_remove_its_registration_even_when_stopped_with_a_failed_task`; mutations M-A and M-B (evidence V7). |

## Dependencies

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
doc-type: manual-verification-evidence
issue-spec: docs/issues/open/2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md
last-updated-utc: "2026-10-26 16:31"
issue-spec: docs/issues/closed/2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md
last-updated-utc: "2026-10-26 19:50"
---

# Manual Verification Evidence
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,15 @@ github-issue: null
spec-path: docs/issues/drafts/2482-gate-axum-health-check-api-server-test-environment/ISSUE.md
branch: "{issue-number}-2482-gate-axum-health-check-api-server-test-environment"
related-pr: null
last-updated-utc: "2026-10-22 18:10"
last-updated-utc: "2026-10-26 19:50"
semantic-links:
skill-links:
- create-issue
related-artifacts:
- docs/adrs/20261021190318_share_workspace_test_support_through_testing_features.md
- docs/issues/open/2482-1669-reorganize-shared-test-support/EPIC.md
- docs/issues/open/2482-1669-reorganize-shared-test-support/test-support-inventory.md
- docs/issues/open/2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md
- docs/issues/closed/2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md
- docs/issues/open/1669-overhaul-packages/workspace-coupling-report-2026-10-06.md
- packages/axum-health-check-api-server/src/environment.rs
---
Expand Down Expand Up @@ -197,4 +197,4 @@ without `--all-features`, and check the test count.

- Parent EPIC: [`#2482`](../../open/2482-1669-reorganize-shared-test-support/EPIC.md); ADR above
- Inventory pattern A; EPIC #1488 subissue
[#2450](../../open/2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md)
[#2450](../../closed/2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md)
14 changes: 6 additions & 8 deletions docs/issues/open/1488-overhaul-tracker-shutdown/ISSUE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ epic: null
github-issue: 1488
spec-path: docs/issues/open/1488-overhaul-tracker-shutdown/ISSUE.md
epic-owner: josecelano
last-updated-utc: "2026-10-25 08:09"
last-updated-utc: "2026-10-26 19:50"
semantic-links:
skill-links:
- create-issue
Expand Down Expand Up @@ -65,9 +65,8 @@ status as of 2026-10-07.
wrappers currently bridge the manager token to `Halted`, leaving two normal
cancellation layers; periodic jobs still ignore `JobManager` cancellation.
**Status: fixed in the application** (sequences 3 to 11) and in the
standalone HTTP, UDP, and REST API environments (SI-16, SI-17, and SI-23); the
health-check API test environment still uses `Halted` until SI-24, and the
legacy API is removed by SI-18 and SI-19.
standalone HTTP, UDP, REST API, and health-check API environments (SI-16,
SI-17, SI-23, and SI-24); the legacy API is removed by SI-18 and SI-19.
3. **Torrent cleanup and activity metrics ignore `CancellationToken`** — they
listen for `ctrl_c` directly instead of using the shared token.
**Status: fixed** by SI-4 (#2169) and #2221.
Expand All @@ -89,9 +88,8 @@ status as of 2026-10-07.
8. **Double-signal on Ctrl+C** — both `main.rs` and each server's
`global_shutdown_signal()` catch the same signal, creating a potential race.
**Status: fixed in the application**: production servers use the token
lifecycle; only the legacy stop path of the health-check API test
environment still observes the OS signal, until SI-24 migrates it; SI-19
removes the legacy API.
lifecycle, and the test environments no longer use the legacy stop path
(SI-24 migrated the last one); SI-19 removes the legacy API.
9. **Event listeners drop events on shutdown** — found on 2026-10-01, after
the original analysis. Every event listener stops as soon as cancellation is
requested, even with events still queued, and servers that are still
Expand Down Expand Up @@ -209,7 +207,7 @@ deterministic tests, and manual evidence.
| 14 | #2471 | [Stop the HTTP test environment when dropped without `stop()`](../../closed/2471-1488-fix-http-environment-drop-path/ISSUE.md) | Done | Bug. Gap found on 2026-10-07: a dropped HTTP test environment keeps its server running, before and after SI-16 (checked on the tree before SI-16). Hold the token as a `DropGuard`, as #2459 did for UDP. Merged in PR #2544 on 2026-10-16. |
| 15 | #2410 | [Process queued events before listeners stop](../../closed/2410-1488-si-22-process-queued-events-before-listeners-stop/EPIC.md) | Done | Bug, sub-EPIC (SI-22) with four sub-issues, #2413 to #2416 (docs and ADR draft; listener drain; per-component tokens; stop order): event producers stop before consumers; listeners process queued events within an admission budget. Merged in PRs #2553, #2578, #2591, and #2623, closed by the close-out PR. |
| 16 | #2449 | [Migrate REST API test environment](../../closed/2449-1488-si-23-migrate-rest-api-test-environment/ISSUE.md) | Done | SI-23. One test environment migration; found while refreshing SI-17 (2026-10-06). Merged in PR #2643 on 2026-10-25; one token and one `DropGuard`, because the environment owns no listener. |
| 17 | #2450 | [Migrate health-check API test environment](../2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md) | Planned | SI-24. One test environment migration; found while refreshing SI-17 (2026-10-06). May run alongside SI-22 (no dependency on it). |
| 17 | #2450 | [Migrate health-check API test environment](../../closed/2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md) | Done | SI-24. One test environment migration; found while refreshing SI-17 (2026-10-06). Merged in PR #2652 on 2026-10-26; one token and one `DropGuard`, because the environment owns no listener. Review found that a fixed-port restart panicked because the registry could not remove a registration, so `torrust-server-lib` 0.4.0 added `Registar::deregister` and `stop()` removes its own binding. |
| 18 | SI-18 | [Deprecate legacy shutdown API](../../drafts/1488-si-18-deprecate-legacy-shutdown-api/ISSUE.md) | Draft | Compatibility-preserving source deprecation only. |
| 19 | SI-19 | [Remove legacy shutdown API and library OS signals](../../drafts/1488-si-19-remove-legacy-shutdown-api/ISSUE.md) | Draft | Breaking release after migration, deprecation, and compatibility gates. |
| 20 | SI-20 | [Configure shutdown policy and deployment contract](../../drafts/1488-si-20-configure-shutdown-policy/ISSUE.md) | Draft | Apply approved Q3/Q4 outcomes, budgets, configuration, and deployment guidance. |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ epic: 1669
github-issue: 2482
spec-path: docs/issues/open/2482-1669-reorganize-shared-test-support/EPIC.md
epic-owner: josecelano
last-updated-utc: "2026-10-26 17:35"
last-updated-utc: "2026-10-26 19:50"
semantic-links:
skill-links:
- create-issue
Expand Down Expand Up @@ -512,9 +512,9 @@ Append one line per meaningful update.
build).
- Related ADRs: [`20260629000000_adopt_independent_package_versioning.md`](../../../adrs/20260629000000_adopt_independent_package_versioning.md)
- Baseline issue: #2446
- Shutdown overhaul EPIC: #1488, with subissues that change the environments (#2449 and #2471 are closed):
- Shutdown overhaul EPIC: #1488, with subissues that change the environments (#2449, #2450 and #2471 are closed):
[#2449](../../closed/2449-1488-si-23-migrate-rest-api-test-environment/ISSUE.md),
[#2450](../2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md) and
[#2450](../../closed/2450-1488-si-24-migrate-health-check-api-test-environment/ISSUE.md) and
[#2471](../../closed/2471-1488-fix-http-environment-drop-path/ISSUE.md)
- Earlier review of this spec: PR #2462 (as a draft task), PR #2484 (spec PR), and the #1669
orchestrator's review of 2026-10-21 (spec refresh PR)
Loading