Services: register outside services, see their health and message state, and replay after an outage
- Dominant language
- C#
- Stars
- 6
- Forks
- 7
- Avg merge
- 4h 42m
- Merged PRs (30d)
- 307
Description
Arnel, 14 September 2026: when a workflow sends messages to outside services (#831), an operator needs to see, as screens rather than logs, whether each service is alive, what is waiting, what failed, and fix it. And if a server goes down mid-flow, the work must be recoverable.
## Change
**A registry of subscribers.** `POST /api/services` registers an outside service: name, the message types it handles, its delivery URL or transport topic, an optional health URL, and the machine key it writes back with (#653). Managed by `manage_services`.
**Heartbeats and health.** A service calls `POST /api/services/{name}/heartbeat` (or barakoCMS polls its health URL). The service is Healthy, Late (no heartbeat within its interval) or Down.
**Message state per service.** `GET /api/services` and `GET /api/services/{name}` return pending, in flight, delivered in the last hour, failed and dead lettered counts, the oldest pending message's age, and the last error with sensitive values redacted (#527).
**Operator actions.**
- Replay a dead lettered message: the same message id is sent again, so the service's `Idempotency-Key` stops a double post.
- Replay everything dead lettered for a service since a time, after an outage.
- Cancel a pending message.
- Pause and resume delivery to a service.
Every action is audited.
**Recovery rules this commits to.**
- A message exists only if the write that caused it committed (outbox, #831), so an API crash mid-save leaves neither.
- A service being down only delays: messages wait in the outbox with backoff, then dead letter after a configured age, never dropped.
- A workflow run waiting for a reply (#831 phase 2) is stored, so it survives a restart and resumes or times out.
- #612 must land first: a service retrying after a network failure needs the original response back, not a 409.
- The outbox is only as safe as the database, so a deployment relying on this needs an off-host backup (#780) or a managed database (BaryoVM#80).
## Done when
- Stopping a test subscriber marks it Down, messages accumulate as pending, restarting it drains them in order, and none are delivered twice.
- A dead lettered message replayed from the API posts once.
- Killing the API between the save and delivery loses no message, proven by a test that restarts the host.
## Where it lives
Module: `BarakoCMS.Services`, owning the registry documents, heartbeats and operator endpoints. The core exposes read and replay access to its outbox and dead letters through an interface; it does not reference the module.
Contributor guide
Research direction
Start with the BarakoCMS.Services module and the core outbox/dead-letter interface described in the issue. Read #831 and #612 first, then trace the existing service and delivery entry points. Done means the registry, health states, operator actions, auditing, and restart/replay behavior are covered by the listed integration scenarios.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- api, backend, databases, distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100