ef657997b2
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
151 lines
5 KiB
Markdown
151 lines
5 KiB
Markdown
# Backend-Agent Status Slice Design
|
|
|
|
**Goal:** Stabilize the current backend foundation and add the first small, real backend-agent status path without introducing database or MQTT dependencies yet.
|
|
|
|
**Architecture:** The backend keeps its existing in-memory/runtime-only character, but gains stronger HTTP test coverage and a minimal player status ingestion endpoint. The agent reuses its internal health snapshot and posts a compact status payload to the backend on a timer, so the first end-to-end data flow is exercised before larger sync and broker work begins.
|
|
|
|
**Tech Stack:** Go stdlib HTTP server/client, existing repo docs, existing agent health model.
|
|
|
|
---
|
|
|
|
## Decision
|
|
|
|
For the next slice, we intentionally do **not** implement full player registration, persistence, authentication, or MQTT.
|
|
|
|
Instead we build a narrow vertical slice with these boundaries:
|
|
|
|
1. harden existing backend routes and validation coverage
|
|
2. add `POST /api/v1/player/status` in the backend with shared error handling
|
|
3. add a small agent status reporter that periodically sends the current health snapshot
|
|
4. document the temporary v1-dev contract clearly so later persistence and auth can replace it cleanly
|
|
|
|
## Why this order
|
|
|
|
### Option A - Recommended: backend hardening, then minimal status path
|
|
|
|
Pros:
|
|
|
|
- least architectural churn for the current repo stage
|
|
- gives the project its first real backend-agent integration
|
|
- keeps risk low because the payload is small and derived from already tested agent state
|
|
- creates a natural foundation for later registration, revisions, and MQTT state
|
|
|
|
Cons:
|
|
|
|
- still not very visible to end users
|
|
- uses temporary in-memory handling on the backend
|
|
|
|
### Option B - Agent-first connectivity expansion
|
|
|
|
Pros:
|
|
|
|
- fast to implement in the agent
|
|
- extends the new health model quickly
|
|
|
|
Cons:
|
|
|
|
- creates local connectivity logic without a meaningful server contract
|
|
- duplicates future work once the backend path exists
|
|
|
|
### Option C - Bigger vertical slice with registration and status
|
|
|
|
Pros:
|
|
|
|
- closer to the eventual architecture
|
|
- more obviously “real” system behavior
|
|
|
|
Cons:
|
|
|
|
- too much surface area for the current codebase maturity
|
|
- would mix lifecycle hardening, API design, auth placeholders, and agent behavior at once
|
|
|
|
## Scope
|
|
|
|
### Backend
|
|
|
|
- keep `GET /healthz`, `GET /api/v1`, `GET /api/v1/meta`, and the existing `message-wall` route
|
|
- add route-level tests for the existing endpoints
|
|
- expand `message_wall` validation tests to match the documented rules more closely
|
|
- add `POST /api/v1/player/status`
|
|
- accept a small JSON payload and respond with a compact acknowledgement
|
|
- no database write, no in-memory historical store yet beyond the request/response path unless needed for tests
|
|
|
|
### Agent
|
|
|
|
- keep the current lifecycle and health snapshot model
|
|
- add an HTTP status reporter component that transforms the snapshot into a backend payload
|
|
- send periodic status updates on a configurable interval
|
|
- keep failures non-fatal and log them as structured events
|
|
- no registration, no retries beyond the next normal interval, no MQTT yet
|
|
|
|
## Proposed temporary API contract
|
|
|
|
### Request
|
|
|
|
`POST /api/v1/player/status`
|
|
|
|
```json
|
|
{
|
|
"screen_id": "info01-dev",
|
|
"ts": "2026-03-22T16:00:00Z",
|
|
"status": "running",
|
|
"server_url": "http://127.0.0.1:8080",
|
|
"mqtt_broker": "tcp://127.0.0.1:1883",
|
|
"heartbeat_every_seconds": 30,
|
|
"started_at": "2026-03-22T15:59:30Z",
|
|
"last_heartbeat_at": "2026-03-22T16:00:00Z"
|
|
}
|
|
```
|
|
|
|
### Response
|
|
|
|
```json
|
|
{
|
|
"status": "accepted"
|
|
}
|
|
```
|
|
|
|
### Notes
|
|
|
|
- this is a dev-stage HTTP substitute for the richer future status/heartbeat model described in `API-MQTT-VERTRAG.md`
|
|
- the payload is deliberately derived from fields the agent already owns today
|
|
- later player identity, auth, richer connectivity flags, and persistence can evolve this contract without invalidating the current slice
|
|
|
|
## Error handling
|
|
|
|
- invalid JSON -> existing shared API error envelope with `400`
|
|
- missing `screen_id` or invalid timestamps -> shared API error envelope with `400`
|
|
- successful ingest -> `200` with compact acknowledgement
|
|
- agent-side send failures -> structured log event, but the agent keeps running
|
|
|
|
## Testing strategy
|
|
|
|
### Backend tests
|
|
|
|
- route tests for `/healthz`, `/api/v1`, `/api/v1/meta`
|
|
- route tests for valid and invalid `POST /api/v1/player/status`
|
|
- broaden `message_wall` validation tests for version, unit, fit mode, duplicate slots, out-of-bounds slots, empty slots
|
|
|
|
### Agent tests
|
|
|
|
- reporter payload generation from `HealthSnapshot`
|
|
- status send success path using `httptest.Server`
|
|
- non-fatal error handling on send failure
|
|
- interval-driven reporting using injectable ticker/clock seams where needed
|
|
|
|
## Out of scope
|
|
|
|
- database persistence of player status
|
|
- player registration
|
|
- auth tokens
|
|
- MQTT broker integration
|
|
- screenshots and media sync
|
|
- admin UI visualization of the status data
|
|
|
|
## Expected result
|
|
|
|
After this slice, the repository still remains intentionally simple, but it gains:
|
|
|
|
- hardened backend route and validation coverage
|
|
- the first real backend-agent HTTP interaction
|
|
- a cleaner base for later registration, sync, and MQTT work
|