Skip to content

feat(rest-api-protocol): migrate health_check context to contract-first architecture #1946

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

Merged
josecelano merged 3 commits into from
Jun 25, 2026
Merged

feat(rest-api-protocol): migrate health_check context to contract-first architecture #1946

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d0b4f0f
feat(rest-api-protocol): migrate health_check context to contract-fir…
josecelano Jun 24, 2026
4b0b403
refactor(rest-api-protocol): restructure v1 resources into context-ba…
josecelano Jun 25, 2026
0591cf2
docs: address Copilot PR review comments
josecelano Jun 25, 2026
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
62 changes: 50 additions & 12 deletions docs/issues/open/1938-rest-api-contract-first-migration/EPIC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,24 +65,60 @@ The contexts are ordered by complexity and dependency depth. Follow-up tasks (SI

## Context Status Summary

| Context / Task | Axum Handlers | Protocol DTOs? | Port Trait? | Use-case? | Runtime Adapter? | Notes |
| ------------------------------- | :-----------: | :------------: | :---------: | :-------: | :--------------: | ---------------------------------- |
| `torrent` | 2 ✅ done | ✅ | ✅ | ✅ | ✅ | Reference pattern |
| SI-1: `health_check` | 1 | ❌ | ❌ | ❌ | ❌ | No tracker deps needed |
| SI-2: `whitelist` | 3 | ❌ | ❌ | ❌ | ❌ | Reuses `ActionStatus` |
| SI-3: `auth_key` | 4 | ❌ | ❌ | ❌ | ❌ | Form DTOs + `clock` |
| SI-4: `stats` | 2 | ❌ | ❌ | ❌ | ❌ | 28-field DTO, SI-30 traits |
| SI-5: deprecate `rest-api-core` | — | — | — | — | — | Post-migration cleanup |
| SI-6: introduce `ApiClient` | — | — | — | — | — | Typed wrapper over `ApiHttpClient` |
| Context / Task | Axum Handlers | Protocol DTOs? | Port Trait? | Use-case? | Runtime Adapter? | Notes |
| ------------------------------- | :-----------: | :------------: | :---------: | :-------: | :--------------: | --------------------------------------------------------------------------------- |
| `torrent` | 2 ✅ done | ✅ | ✅ | ✅ | ✅ | Reference pattern — lives under `v1::context::torrent::resources::torrent` |
| SI-1: `health_check` | 1 ✅ done | ✅ | ❌ N/A | ❌ N/A | ❌ N/A | No tracker deps — DTOs under `v1::context::health_check::resources::health_check` |
| SI-2: `whitelist` | 3 | ❌ | ❌ | ❌ | ❌ | Reuses `ActionStatus` |
| SI-3: `auth_key` | 4 | ❌ | ❌ | ❌ | ❌ | Form DTOs + `clock` |
| SI-4: `stats` | 2 | ❌ | ❌ | ❌ | ❌ | 28-field DTO, SI-30 traits |
| SI-5: deprecate `rest-api-core` | — | — | — | — | — | Post-migration cleanup |
| SI-6: introduce `ApiClient` | — | — | — | — | — | Typed wrapper over `ApiHttpClient` |

## Scope

### In Scope

- Create protocol DTOs (request/response/error types) in `rest-api-protocol` for each remaining context.
Each context follows a normalized module structure under `packages/rest-api-protocol/src/v1/context/`:

```text
context/
└── <context-name>/
├── mod.rs # context docs + pub mod resources;
└── resources/
├── mod.rs # pub mod <resource>;
└── <resource>.rs # DTO definitions
```

See the `torrent` context for the reference pattern.
- Define port traits in `rest-api-application` for each context's query/command operations.
These are flat files named after the context in `packages/rest-api-application/src/ports/`:

```text
ports/
├── mod.rs # pub mod torrent; pub mod whitelist; ...
└── <context>.rs # port trait definition
```

- Implement use-case services in `rest-api-application`.
Similarly flat files in `packages/rest-api-application/src/use_cases/`:

```text
use_cases/
├── mod.rs # pub mod torrent; pub mod whitelist; ...
└── <context>.rs # use-case service implementation
```

- Implement runtime adapters in `rest-api-runtime-adapter` wrapping tracker internals.
Flat files in `packages/rest-api-runtime-adapter/src/adapters/`:

```text
adapters/
├── mod.rs # pub mod torrent; pub mod whitelist; ...
└── <context>.rs # adapter implementation
```

- Rewire Axum handlers to dispatch through use cases instead of direct internals.
- Update tests to use adapter conversion functions.
- Remove internal crate dependencies from `axum-rest-api-server` as contexts are migrated.
Expand Down Expand Up @@ -154,6 +190,8 @@ The following table maps each internal crate dependency to the sub-issue that re

### Progress Log

| Date | Event |
| ---------- | --------------------------------------------- |
| 2026-06-24 | Draft EPIC created after SI-33 PoC validation |
| Date | Event |
| ---------- | -------------------------------------------------------------------------------------- |
| 2026-06-24 | Draft EPIC created after SI-33 PoC validation |
| 2026-06-24 | SI-1 (health_check) implemented — protocol DTOs migrated |
| 2026-06-24 | Specs updated to document normalized `context/` module structure for all protocol DTOs |
73 changes: 48 additions & 25 deletions docs/issues/open/1939-1938-si-1-migrate-health-check-context.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ epic: 1938
github-issue: 1939
spec-path: docs/issues/open/1939-1938-si-1-migrate-health-check-context.md
last-updated-utc: 2026-06-24
updated-reason: Updated to reference context/ module structure instead of resources/
semantic-links:
skill-links:
- create-issue
Expand All @@ -31,33 +32,34 @@ The `health_check` endpoint is defined in `packages/axum-rest-api-server/src/v1/

Per the contract-first architecture defined in [SI-33](../../open/1930-1669-si-33-rest-api-contract-first-architecture.md), this context should have:

- DTOs in `rest-api-protocol`
- DTOs in `rest-api-protocol` under the normalized module structure:
`v1::context::health_check::resources::health_check`
- A port trait and use-case service in `rest-api-application`
- A runtime adapter (if needed) in `rest-api-runtime-adapter`
- A runtime adapter in `rest-api-runtime-adapter`
- Only thin HTTP routing/extraction in `axum-rest-api-server`

## Current State

**Location**: `packages/axum-rest-api-server/src/v1/context/health_check/`

| Artifact | Current Location | Target Location |
| --------------- | ---------------------------------------- | ------------------------------------- |
| `Status` enum | `resources.rs` in Axum | `rest-api-protocol/src/v1/resources/` |
| `Report` struct | `resources.rs` in Axum | `rest-api-protocol/src/v1/resources/` |
| Handler | `handlers.rs` | Axum (keep, but simplify) |
| Route | `src/routes.rs` (at `/api/health_check`) | Axum (keep) |
| Artifact | Current Location | Target Location |
| --------------- | ---------------------------------------- | ------------------------------------------------------------------- |
| `Status` enum | `resources.rs` in Axum | `rest-api-protocol/src/v1/context/health_check/resources/report.rs` |
| `Report` struct | `resources.rs` in Axum | `rest-api-protocol/src/v1/context/health_check/resources/report.rs` |
| Handler | `handlers.rs` | Axum (keep, but simplify) |
| Route | `src/routes.rs` (at `/api/health_check`) | Axum (keep) |

**Tracker dependency**: None — the handler returns a static response. This is the simplest context to migrate.

## Scope

### In Scope

- Move `Status` enum to `rest-api-protocol/src/v1/resources/health_check.rs`.
- Move `Report` struct to `rest-api-protocol/src/v1/resources/health_check.rs`.
- Move `Status` enum to `rest-api-protocol/src/v1/context/health_check/resources/report.rs`.
- Move `Report` struct to `rest-api-protocol/src/v1/context/health_check/resources/report.rs`.
- (Optional) Add a simple `HealthCheckPort` trait + use-case in `rest-api-application` if needed for testability; otherwise keep as direct protocol DTO mapping.
- Rewire Axum handler to return protocol DTOs.
- Update `rest-api-protocol/src/v1/resources/mod.rs` exports.
- Update `rest-api-protocol/src/v1/context/mod.rs` and `health_check/` module tree exports.
- Verify no behavioural change.

### Out of Scope
Expand All @@ -70,31 +72,52 @@ Per the contract-first architecture defined in [SI-33](../../open/1930-1669-si-3
This is a straightforward DTO relocation. Steps:

1. Create protocol DTOs matching the current `Status` and `Report` types.
2. Expose them from `rest-api-protocol::v1::resources::health_check`.
2. Expose them from `rest-api-protocol::v1::context::health_check::resources::report`.
3. Remove the local definitions from the Axum server.
4. Update imports in the handler.
5. Add conversion from protocol `Report` to JSON response (already `Serialize`).

Since there is no tracker dependency, no runtime adapter is needed — the handler can construct protocol DTOs directly.

## Module Structure Convention

All protocol DTOs follow the normalized context-based module structure under
`packages/rest-api-protocol/src/v1/context/` (see the `torrent` context for the reference pattern):

```text
context/<context-name>/
├── mod.rs
└── resources/
├── mod.rs
└── <resource>.rs
```

Ports, use-cases, and adapters are flat files named after the context:

```text
packages/rest-api-application/src/ports/<context>.rs
packages/rest-api-application/src/use_cases/<context>.rs
packages/rest-api-runtime-adapter/src/adapters/<context>.rs
```

## Implementation Plan

| ID | Status | Task | Notes |
| --- | ------ | -------------------------------------------------------------------------------------------------- | ----------------------------------- |
| T1 | TODO | Add `health_check` module to `rest-api-protocol/src/v1/resources/` with `Status` and `Report` DTOs | Match current serialization exactly |
| T2 | TODO | Export new module from `rest-api-protocol/src/v1/resources/mod.rs` | |
| T3 | TODO | Remove local `Status` and `Report` from Axum `health_check` resources | |
| T4 | TODO | Update Axum handler to import and use protocol DTOs | |
| T5 | TODO | Verify pre-commit and pre-push checks pass | |
| T6 | TODO | Verify integration tests pass | |
| ID | Status | Task | Notes |
| --- | ------ | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| T1 | DONE | Add `health_check` context module to `rest-api-protocol/src/v1/context/` with `Status` and `Report` DTOs (resources subdir) | Match current serialization exactly |
| T2 | DONE | Export new context from `rest-api-protocol/src/v1/context/mod.rs` and set up normalized `resources/` module tree | |
| T3 | DONE | Remove local `Status` and `Report` from Axum `health_check` resources | |
| T4 | DONE | Update Axum handler to import and use protocol DTOs | |
| T5 | DONE | Verify pre-commit checks pass | Pre-commit checks pass |
| T6 | DONE | Verify integration tests compile | Compilation verified |

## Verification / Progress

- [ ] Protocol DTOs created and exported
- [ ] Local DTOs removed from Axum server
- [ ] Handler uses protocol DTOs
- [ ] Pre-commit checks pass
- [ ] Pre-push checks pass
- [x] Protocol DTOs created and exported
- [x] Local DTOs removed from Axum server
- [x] Handler uses protocol DTOs
- [x] Pre-commit checks pass
- [ ] Pre-push checks pass (to be verified before merge)

### Progress Log

Expand Down
21 changes: 21 additions & 0 deletions docs/issues/open/1940-1938-si-2-migrate-whitelist-context.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ epic: 1938
github-issue: 1940
spec-path: docs/issues/open/1940-1938-si-2-migrate-whitelist-context.md
last-updated-utc: 2026-06-24
updated-reason: Added normalized module structure convention note
semantic-links:
skill-links:
- create-issue
Expand Down Expand Up @@ -38,6 +39,26 @@ Per the contract-first architecture, the migration needs to:
- Implement a runtime adapter wrapping `WhitelistManager`.
- Rewire Axum handlers to dispatch through the use-case service.

All protocol types follow the normalized context-based module structure under `packages/rest-api-protocol/src/v1/context/`:

```text
context/<context-name>/
├── mod.rs
└── resources/
├── mod.rs
└── <resource>.rs
```

Ports, use-cases, and adapters are flat files named after the context:

```text
packages/rest-api-application/src/ports/<context>.rs
packages/rest-api-application/src/use_cases/<context>.rs
packages/rest-api-runtime-adapter/src/adapters/<context>.rs
```

See the `torrent` and `health_check` contexts for the reference pattern.

## Current State

**Location**: `packages/axum-rest-api-server/src/v1/context/whitelist/`
Expand Down
Loading
Loading