bdc77e87e3
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
138 lines
5.2 KiB
Markdown
138 lines
5.2 KiB
Markdown
# Info-Board Neu - Erster HTTP-Statuspfad fuer den Player-Agent
|
|
|
|
## Ziel
|
|
|
|
Dieses Dokument beschreibt den ersten bewusst kleinen Statuspfad zwischen `player/agent` und `server/backend`.
|
|
|
|
Er ist fuer die aktuelle Entwicklungsstufe gedacht und noch kein finales Persistenz-, Authentifizierungs- oder MQTT-Modell.
|
|
|
|
## V1-Dev-Entscheidung
|
|
|
|
- der Agent sendet zunaechst Statusdaten per HTTP an das Backend
|
|
- das Backend validiert und bestaetigt den Request und haelt den letzten bekannten Status pro Screen in-memory vor
|
|
- der Pfad dient als erste echte Backend-Agent-Integration vor Registration, Sync und MQTT
|
|
|
|
## Endpoint
|
|
|
|
- `POST /api/v1/player/status`
|
|
|
|
## Request-Felder
|
|
|
|
Mindestens enthalten:
|
|
|
|
- `screen_id`
|
|
- `ts`
|
|
- `status`
|
|
|
|
Fuer die aktuelle Entwicklungsstufe sind zulaessig:
|
|
|
|
- `status`: `starting`, `running`, `stopped`
|
|
- `server_connectivity`: `unknown`, `online`, `degraded`, `offline`
|
|
- `heartbeat_every_seconds`: positive Ganzzahl
|
|
|
|
Aktuell zusaetzlich enthalten:
|
|
|
|
- `server_connectivity`
|
|
- `server_url`
|
|
- `mqtt_broker`
|
|
- `heartbeat_every_seconds`
|
|
- `started_at`
|
|
- `last_heartbeat_at`
|
|
|
|
## Beispiel
|
|
|
|
```json
|
|
{
|
|
"screen_id": "info01-dev",
|
|
"ts": "2026-03-22T16:00:00Z",
|
|
"status": "running",
|
|
"server_connectivity": "online",
|
|
"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"
|
|
}
|
|
```
|
|
|
|
## Antwort
|
|
|
|
Bei gueltigem Request liefert das Backend aktuell:
|
|
|
|
```json
|
|
{
|
|
"status": "accepted"
|
|
}
|
|
```
|
|
|
|
Bei ungueltigen Requests wird wie bei den anderen API-Endpunkten der gemeinsame Fehlerumschlag verwendet.
|
|
|
|
## Aktueller Read-Pfad
|
|
|
|
Zusätzlich zur Write-Route gibt es in dieser Stufe:
|
|
|
|
- `GET /status`
|
|
- `GET /api/v1/screens/status`
|
|
- `GET /api/v1/screens/{screenId}/status`
|
|
|
|
`GET /status` liefert eine kleine serverseitig gerenderte HTML-Statusseite fuer den Browser.
|
|
Sie nutzt dieselbe in-memory Statusuebersicht wie die JSON-Endpunkte und ist als erste sichtbare Diagnoseoberflaeche gedacht.
|
|
|
|
`GET /api/v1/screens/status` liefert eine kleine Uebersicht aller bisher berichtenden Screens mit ihrem jeweils letzten bekannten Datensatz.
|
|
Die Rueckgabe wird aktuell fuer Diagnosezwecke priorisiert sortiert: zuerst `offline`, dann `degraded`, dann `online`, innerhalb derselben Gruppe nach `screen_id`.
|
|
Zusaetzlich enthaelt die Antwort eine `summary` mit kompakten Counts fuer `total`, `online`, `degraded`, `offline` und `stale`.
|
|
|
|
Aktuell unterstuetzte Query-Parameter fuer die Uebersicht:
|
|
|
|
- `server_connectivity=<value>` zum Filtern nach Reachability-Zustand
|
|
- `stale=true|false` zum Filtern nach serverseitiger Veraltet-Einschaetzung
|
|
- `updated_since=<RFC3339>` zum Filtern nach `received_at`
|
|
- `limit=<positive integer>` zum Begrenzen der Anzahl zurueckgelieferter Screens
|
|
|
|
Die Query-Parameter beeinflussen die Liste in `screens`; die `summary` beschreibt weiterhin den gesamten aktuell bekannten Statusbestand.
|
|
|
|
`GET /api/v1/screens/{screenId}/status` liefert den zuletzt akzeptierten Status fuer einen einzelnen Screen zurueck.
|
|
Wenn fuer den Screen noch kein Status vorliegt, liefert das Backend `404` mit dem gemeinsamen Fehlerumschlag.
|
|
|
|
Der aktuell zurueckgelieferte Datensatz enthaelt damit sowohl den Lifecycle-Status (`status`) als auch den vom Agenten lokal abgeleiteten Reachability-Zustand (`server_connectivity`).
|
|
|
|
Zusaetzlich fuegt das Backend im Read-Pfad derzeit hinzu:
|
|
|
|
- `received_at` als serverseitigen Annahmezeitpunkt des letzten gueltigen Reports
|
|
- `stale` als einfache serverseitige Einordnung, ob der letzte Report bereits veraltet wirkt
|
|
- `derived_state` als zusammengefasste Diagnoseeinschaetzung fuer Konsumenten des Read-Pfads
|
|
|
|
`stale` ist aktuell bewusst nur eine kleine Diagnosehilfe fuer die Entwicklungsstufe und noch kein vollstaendiges Online-/Offline-Modell fuer spaetere Admin-Oberflaechen.
|
|
Die Schwelle wird derzeit einfach aus dem gemeldeten `heartbeat_every_seconds` abgeleitet: mehr als zwei Intervalle ohne neuen Report gelten als veraltet.
|
|
|
|
`derived_state` wird aktuell bewusst einfach abgeleitet:
|
|
|
|
- `offline` bei `stale = true` oder `server_connectivity = offline`
|
|
- `degraded` bei `server_connectivity = degraded|unknown` oder wenn `status` nicht `running` ist
|
|
- `online` in den verbleibenden Faellen
|
|
|
|
## Abgrenzung
|
|
|
|
Noch nicht Teil dieser Stufe:
|
|
|
|
- dauerhafte Speicherung in Datenbank oder State-Store
|
|
- Screen-Authentifizierung
|
|
- MQTT-Heartbeat oder MQTT-Status
|
|
- Admin-UI-Anzeige des letzten Status
|
|
- Retry-Queue oder lokale Zwischenspeicherung im Agent
|
|
|
|
Agent-seitig wird die Server-Erreichbarkeit aktuell lokal als `unknown`, `online`, `degraded` oder `offline` aus dem Erfolg der HTTP-Reports abgeleitet.
|
|
|
|
Fuer den transportierten Wert im erfolgreichen HTTP-Report gilt aktuell bewusst einfach:
|
|
|
|
- wenn ein Report vom Backend akzeptiert wurde, wird dieser Report selbst als `server_connectivity = online` gespeichert
|
|
- anhaltende Ausfaelle werden primaer ueber lokale Agent-Zustaende und serverseitige `stale`-Ableitung sichtbar
|
|
|
|
## Folgeschritte
|
|
|
|
Auf diesem Pfad bauen spaeter auf:
|
|
|
|
- Screen-Identitaet und Authentifizierung
|
|
- persistierter letzter Heartbeat und letzter Status auf dem Server
|
|
- Trennung zwischen HTTP-Snapshot und MQTT-Heartbeat
|
|
- Admin-Vorschau fuer Online-/Offline- und Degraded-Zustaende
|