BaryoDev / BaryoDev/barakoCMS

Services: register outside services, see their health and message state, and replay after an outage

Open
#833 0 comments 0 reactions 0 assignees View on GitHub
module
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.