Files

807 lines
34 KiB
Markdown

# Broker und WebSocket-Protokoll
Stand: 01.11.2026
Dieses Dokument beschreibt das aktuelle WebSocket-Protokoll, die Aufgaben und
den Ablauf des Brokers sowie die Stellen, an denen die Implementierung von der
in der Aufgabenstellung beschriebenen Soll-Logik abweicht.
Die zentrale Implementierung liegt in:
- `CMBNet/cmbnet/ws/broker.py`
- `CMBNet/cmbnet/ws/routes.py`
- `CMBNet/cmbnet/ws/protocol.py`
- `CMBNet/cmbnet/ws/heartbeat.py`
## 1. Grundidee
Der Broker ist eine Vermittlungsinstanz zwischen allen aktiven WebSocket-Clients
eines Mandanten. Die Socket-Objekte sind prozesslokal, der Client-Zustand und
die Zustell-Queue liegen gemeinsam in SQLite. Er
- verwaltet die WebSocket-Verbindungen und deren Authentifizierungsstatus,
- ordnet Nachrichten anhand ihres Codes einem Empfängerkreis zu,
- wendet fachliche Zustandsänderungen für Straßen und Gruppen an,
- persistiert Chat-Nachrichten für die spätere Nachlieferung,
- puffert nicht zustellbare Nachrichten pro Client-ID,
- überwacht die Lebenszeichen der Gruppen.
Die Web-APIs liefern den Clients unabhängig vom Broker den aktuellen
Initialzustand. Der Broker ist damit nicht die einzige Quelle für den Zustand,
sondern verteilt Änderungen und gleicht kurzfristige Verbindungsunterbrechungen
aus.
## 2. Transport, Authentifizierung und Client-ID
### Endpoint
Jeder Mandant hat einen eigenen WebSocket-Endpoint:
```text
ws(s)://<host>/<tenant>/ws
```
Beispiel:
```text
wss://qgelm.de/cmb/RV/ws
```
Der Endpoint liegt in `cmbnet/ws/routes.py`. Der Mandant wird über den Pfad
aufgelöst, der Account über das Flask-Session-Cookie des Browsers.
### Code-0-Handshake
Nach dem Öffnen der WebSocket-Verbindung sendet der Client Code 0:
```json
{
"code": 0,
"msg": "<einmaliges-token>",
"client_id": "<client-id-der-webview>"
}
```
Das Token wird vorher über `GET /<tenant>/api/auth/ws-token` geholt. Es ist
mandanten- und accountgebunden, nur einmal verwendbar und standardmäßig eine
Stunde gültig.
Die `client_id` wird in `templates/base.html` bei jedem Laden einer Webview
einmalig erzeugt. Sie wird bewusst **nicht** in `sessionStorage` gespeichert:
Ein Neuladen erzeugt eine neue Webview und damit eine neue Broker-Verbindung.
Die Client-ID ist an den Account gebunden, der den Code-0-Handshake ausführt.
Mehrere Clients desselben Accounts erhalten getrennte Verbindungen und Queues.
Der Broker akzeptiert aus Kompatibilitätsgründen auch die ältere Objektform und
den alten Schlüssel `session_id`:
```json
{
"code": 0,
"msg": {
"token": "<token>",
"session_id": "<alte-sitzungs-id>"
}
}
```
Fehlt eine gültige Client-ID vollständig, erzeugt der Broker eine eindeutige
Ersatz-ID (`legacy-<account>-<zufall>`). Ein solcher Altclient kann nach einem
Reconnect keine frühere Queue wiedererkennen.
Nach erfolgreicher Prüfung antwortet der Server mit einer Code-0-Bestätigung:
```json
{
"code": 0,
"sender_id": 0,
"receiver_id": null,
"ts": 1793449907241,
"seq": 1,
"msg": "authenticated"
}
```
Diese Bestätigung ist eine Implementierungserweiterung. Sie ist in der
ursprünglichen Protokollliste nicht enthalten. Der mobile Client wartet darauf
beziehungsweise auf einen kurzen Fallback, bevor er gepufferte fachliche
Nachrichten sendet.
### Nachrichtenumschlag
Alle Nachrichten werden als JSON-Text übertragen:
```json
{
"sender_id": 3,
"receiver_id": 20,
"code": 100,
"ts": 1793449907246,
"seq": 42,
"msg": "{\"street_id\": 30, \"state\": \"erledigt\"}"
}
```
- `sender_id`: serverseitig aus der Session gesetzt; Clientangaben werden
überschrieben.
- `receiver_id`: Empfänger-ID, soweit sinnvoll; bei Broadcasts `null`.
- `code`: primäres Steuerungsmerkmal.
- `ts`: Zeitstempel in Millisekunden.
- `seq`: fortlaufende Sequenznummer für genau diese Client-ID.
- `msg`: Text oder JSON-String mit dem fachlichen Inhalt.
Die Sequenznummer wird vom Broker erst beim tatsächlichen Versand an eine
Client-Verbindung ergänzt. Jede Client-ID besitzt eine eigene Zählung; mehrere
Clients desselben Accounts beeinflussen sich nicht. Die Zählung beginnt bei 1
und bleibt über einen WebSocket-Reconnect derselben Webview erhalten. Wird eine
Nachricht gepuffert, erhält sie ihre Sequenznummer erst bei der späteren
Zustellung. Ein fehlgeschlagener Sendevorgang verbraucht keine Sequenznummer.
Nach einem Neuladen der Seite entsteht eine neue Client-ID und damit eine neue
Zählung ab 1.
Clients merken sich die zuletzt empfangene Sequenznummer. Trifft nach einem
Reconnect eine andere Nummer als `zuletzt + 1` ein, zeigt der Client einen
Code-99-ähnlichen Neulade-Dialog an. Die Sequenzzählung liegt in
`ws_clients.last_seq` und bleibt damit auch bei einem Worker-Wechsel oder
Neustart eines Workers erhalten. Nach einem vollständigen Verlust der
Datenbank beginnt sie neu und löst bei bereits geöffneten Clients den
Neulade-Hinweis aus.
`sender_id` und `receiver_id` werden nicht in jedem Fall mit lesbaren Namen
ergänzt. Chat-Nachrichten enthalten zusätzlich ein `sender`-Objekt mit
Accountname, Rolle und Gruppenalias. Bei Code 100/200/300 enthält das Payload
überwiegend nur IDs; Name und Alias werden im Client aus den Initialdaten
aufgelöst. Das ist eine Abweichung von der Soll-Vorgabe, siehe Abschnitt 10.
## 3. Nachrichtenübersicht
| Code | Richtung / Sender | Empfänger | Persistenz | Queue |
|---|---|---|---|---|
| 0 | Client an Broker | nur Broker; Bestätigung an den Client | nein | nein |
| 1 | Broker an Client | ein Client | nein | nein |
| 2 | Client an Broker | aktuell nur Dispatcher | nein | nein |
| 99 | Broker / Admin-API / Dispatcher-API | alle Rollen des Mandanten | nein | ja, speziell |
| 100 | Dispatcher, Gruppe, intern Administrator | Dispatcher, Beobachter, Gast und betroffene Gruppe(n) | DB-Änderung | ja |
| 200 | Dispatcher, Gruppe, intern Administrator | Dispatcher, Beobachter und betroffene Gruppe | DB-Änderung | ja |
| 300 | Gruppe, Dispatcher, intern Administrator | Dispatcher, Beobachter und betroffene Gruppe | DB-Änderung | ja |
| 1000 | Dispatcher (Soll) | Dispatcher, Beobachter, alle Gruppen | ja, 8 h | ja |
| 1100 | Dispatcher (Soll) | Dispatcher, Beobachter, adressierte Gruppe | ja, 8 h | ja |
| 2000 | Gruppen-Account (Soll) | Dispatcher, Beobachter, eigene Gruppe | ja, 8 h | ja |
Alle Codes unter 100 außer 0, 99 und 2 sind interne Codes. Unbekannte Codes
unter 100 werden vom Broker ignoriert. Unbekannte fachliche Codes ab 100 werden
aktuell an keinen Empfänger verteilt, weil `_get_recipients()` für sie eine
leere Menge liefert.
## 4. Interne Nachrichten
### Code 0: Authentifizierung
Code 0 wird ausschließlich in der WebSocket-Route verarbeitet. Er wird nicht an
fachliche Empfänger weitergeleitet. Der Broker prüft:
1. Existiert das Token für Mandant und Account?
2. Ist es noch nicht verwendet?
3. Ist es nicht abgelaufen?
4. Ist die Client-ID gültig und noch keinem anderen Account zugeordnet?
Danach wird das Token als verbraucht markiert, die Client-ID normalisiert und
die Verbindung als authentifiziert registriert. Ohne gültigen Code 0 werden
fachliche Nachrichten nicht akzeptiert; die Verbindung wird geschlossen. Da die
Registrierung erst mit Code 0 erfolgt, kennt der Broker vor dem Handshake noch
keine Client-ID.
### Code 1: Heartbeat
Der Broker sendet standardmäßig jede Minute eine Nachricht mit Code 1 an alle
authentifizierten Verbindungen:
```json
{"sender_id": 0, "receiver_id": null, "code": 1, "ts": 1793449907241, "seq": 17, "msg": "ping"}
```
Die Heartbeat-Routine läuft in einem Daemon-Timer. Sie räumt zusätzlich
abgelaufene Chat-Nachrichten und Client-Queues auf.
### Code 2: Pong / Lebenszeichen
Der Client antwortet auf Code 1 mit Code 2:
```json
{"code": 2, "msg": "pong"}
```
Der Broker
- aktualisiert `last_pong_at` der Verbindung,
- speichert für Gruppen-Accounts den Pong-Zeitpunkt,
- setzt eine Gruppe von `unterwegs` auf `online`,
- verteilt Code 2 aktuell nur an Accounts der Rolle `Dispatcher`.
Der Gruppenstatus wird zusätzlich durch einen 15-Sekunden-Prüftimer
überwacht. Bleibt ein Code-2-Pong länger als
`WS_GROUP_ONLINE_TIMEOUT_SECONDS` (Default 120 s) aus, wird die Gruppe auf
`unterwegs` gesetzt. Der automatische Wechsel wird als Code 200 mit
`automatic: true` verteilt.
### Code 99: Neuladen erzwingen
Code 99 ist eine Aufforderung an alle Clients, die Seite neu zu laden. Der
Broker verteilt ihn an alle Rollen des Mandanten.
Ausgelöst wird Code 99 derzeit serverseitig:
- durch die Admin-API nach Änderungen an Accounts, Gruppen, Straßen,
Zuordnungen und Importen,
- durch `notify_reload()` in `cmbnet/utils/helpers.py`.
Ein direkter Code-99-Frame eines WebSocket-Clients wird ignoriert
(`apply_business=True` in der WS-Route). Die Soll-Beschreibung nennt auch
Admin- und Dispatcher-Clients als mögliche Sender; diese lösen Code 99 aktuell
über die jeweilige HTTP-API aus, nicht über einen eigenen WS-Frame.
Queue-Verhalten:
- Ist ein Client nicht erreichbar, wird Code 99 in seiner Client-Queue
gespeichert.
- Eine gespeicherte Code-99-Nachricht leert alle älteren Queue-Nachrichten.
- Danach werden keine weiteren Nachrichten in dieser Queue gepuffert
(`code99_only`).
- Beim nächsten Reconnect mit derselben Client-ID wird ausschließlich diese
Code-99-Nachricht zugestellt. Late Entries werden in diesem Fall
unterdrückt.
- Ist die Queue wegen Überschreitung der Maximalzeit abgelaufen, erzeugt der
Broker eine Code-99-Nachricht mit Hinweis auf die zu lange Unterbrechung.
## 5. Fachliche Zustandsänderungen
### Code 100: Straßenstatus
Soll-Empfänger: alle Dispatcher, Beobachter, Gast-Accounts und die mit der
Straße verknüpfte Gruppe. Bei einem Gruppenwechsel werden sowohl die alte als
auch die neue Gruppe benachrichtigt.
Aktuelle Implementierung:
- Dispatcher und Administrator dürfen Code 100 senden.
- Gruppen-Accounts dürfen Code 100 senden, aber nur für Straßen, die aktuell
ihrer eigenen Gruppe zugewiesen sind.
- Eine Gruppe darf ihre eigene Straße auf `unbearbeitet` setzen (Freigabe),
aber nicht einer anderen Gruppe zuweisen.
- Der Broker validiert `street_id` beziehungsweise den Straßennamen, den
Zustand (`unbearbeitet`, `zugewiesen`, `erledigt`) und die Zielgruppe.
- Bei Änderungen werden `streets`, `street_state_history` und das
Transaktionslog aktualisiert.
- Das normalisierte Payload enthält `name`, `state`, `actor`, `street_id` und
`group_id`.
### Code 200: Gruppenstatus
Soll-Empfänger: alle Dispatcher, Beobachter und die betroffene Gruppe.
Aktuelle Implementierung:
- Dispatcher, Administrator und Gruppen-Accounts dürfen Code 200 senden.
- Ein Gruppen-Account darf nur den Zustand der eigenen Gruppe ändern.
- Erlaubte Zustände: `offen`, `unterwegs`, `online`, `pausierend`, `fertig`.
- Bei Änderungen werden `groups` und `group_state_history` aktualisiert.
- Der automatische Statuswechsel durch Code 2 erzeugt ebenfalls eine
Code-200-Nachricht mit `automatic: true`.
### Code 300: Gruppenposition
Soll-Empfänger: alle Dispatcher, Beobachter und die betroffene Gruppe.
Aktuelle Implementierung:
- Dispatcher, Administrator und Gruppen-Accounts dürfen Code 300 senden.
- Ein Gruppen-Account darf nur die Position der eigenen Gruppe melden.
- Der Server validiert Breiten- und Längengrad.
- Der Server setzt den Positionszeitstempel selbst; manipulierte Client-Zeiten
werden für Code 300 überschrieben.
- Automatische Positionsmeldungen aktualisieren die Live-Position, erzeugen
aber keinen Historieneintrag und keinen Transaktionseintrag.
- Das Payload enthält `group_id`, `lat`, `lon`, `ts` und `actor`.
### Anzeige in den Clients
Nach der Zustellung müssen die Clients ihren lokalen Zustand und ihre Oberfläche
aktualisieren. Der aktuelle Stand:
- **Mobile Clients**: Im Kopf der Gruppen- und Dispatcher-Mobil-Ansicht zeigt
ein Statusfeld den WebSocket-Zustand (`verbinde`, `verbunden`, `getrennt`,
`Fehler`). Die Anzeige wird bei Verbindungsaufbau, Code-0-Bestätigung,
Heartbeat, Trennung und Tokenfehler aktualisiert.
- **Dispatcher und Beobachter** (`dispatcher.js`): Code 100 aktualisiert den
Straßenzustand, färbt die Karte neu und synchronisiert ein offenes
Straßenfenster sowie die Straßenliste einer offenen Gruppe. Code 200
aktualisiert Status-Badge und Statusauswahl der Gruppe sowie die
Gruppensteuerung. Code 300 verschiebt den Gruppenmarker und aktualisiert
Positionsalter, Fortschrittsanzeige und Navigationsbutton.
- **Dispatcher Mobil** (`mobile.js`, `mobile_dispatcher`): Code 100
aktualisiert die Straßenliste, die aktuell gezeichnete Straße und ein
offenes Bearbeitungsfenster. Neu zugewiesene Straßen werden aufgenommen,
abgegebene Straßen entfernt. Code 200 aktualisiert den Gruppenstatus und den
Statustext im Gruppenauswahlfeld. Code 300 zeichnet alle Gruppenpositionen
neu und aktualisiert den Navigationsbutton.
- **Gruppen-View** (`mobile.js`, `mobile_group`): Code 100 aktualisiert die
ToDo-Liste und die Karte der eigenen Straßen. Code 200 aktualisiert den
Gruppenstatus im lokalen Zustand. Code 300 aktualisiert die Gruppendaten;
die eigene Position wird in dieser Ansicht weiterhin durch den lokalen
GPS-Marker dargestellt, deshalb wird kein zusätzlicher Gruppenmarker
gezeichnet.
- **Chat**: Eingehende Chat-Nachrichten werden im Chat-Verlauf ergänzt und
lösen Ton bzw. Benachrichtigung aus. Sie wechseln nicht mehr automatisch in
den Chat-Tab, damit die Kartenansicht während der Arbeit sichtbar bleibt.
- **Sequenzprüfung**: Mobile Clients, Dispatcher/Beobachter und der Admin-
Reload-Watcher vergleichen jede empfangene `seq` mit ihrer letzten Zählung.
Bei einer Lücke erscheint der Neulade-Dialog; die Nachricht wird trotzdem
verarbeitet.
## 6. Chat-Nachrichten ab Code 1000
Alle Nachrichten ab Code 1000 werden in `ws_messages_store` persistiert. Sie
werden standardmäßig acht Stunden vorgehalten
(`LATE_ENTRY_MAX_AGE_HOURS`). Der Broker normalisiert sie auf ein einheitliches
Payload:
```json
{
"text": "Hallo Dispatcher",
"sender": {
"account_id": 10,
"name": "gruppe",
"role": "Gruppe",
"group_id": 20,
"group_alias": "G1"
},
"receiver_id": 20
}
```
Bei Code 1000 wird stattdessen `broadcast: true` gesetzt. Der Chat-Client zeigt
die Nachricht als „Von -> An“ mit Zeitstempel und Text an.
### Code 1000: Broadcast
Soll-Sender: Dispatcher. Empfänger: alle Dispatcher, Beobachter und alle
Gruppen. Der Broker akzeptiert Code 1000 nur von Accounts mit der Rolle
`Dispatcher`; andere Rollen werden mit einer Warnung und einem Debug-Eintrag
abgewiesen.
### Code 1100: Nachricht an eine Gruppe
Soll-Sender: Dispatcher. Empfänger: alle Dispatcher, Beobachter und die
adressierte Gruppe. Der Broker ermittelt die Gruppen-ID aus `group_id`,
`receiver_id` oder dem Absender und akzeptiert Code 1100 nur von Accounts mit
der Rolle `Dispatcher`.
### Code 2000: Nachricht aus einer Gruppe
Soll-Sender: Gruppen-Account. Empfänger: alle Dispatcher, Beobachter und die
eigene Gruppe. Der Broker akzeptiert Code 2000 nur von Accounts mit der Rolle
`Gruppe`. Zusätzlich muss die aufgelöste Zielgruppe die eigene Gruppe des
Absenders sein; Nachrichten an eine fremde Gruppe werden abgewiesen.
## 7. Broker-Ablauf
### Verbindungsverwaltung
`WebSocketBroker.connections` ist ein prozesslokales, verschachteltes
Dictionary:
```text
connections[tenant_id][client_id] = {
ws, account_id, client_id, role, group_id,
last_ping, connected_at, last_pong_at, send_lock, seq
}
```
Es enthält nur die WebSocket-Objekte des aktuellen Workers. Eine Client-ID
gehört genau zu einer Webview. Ein Account kann daher mehrere Clients parallel
betreiben. Eine neue Verbindung mit derselben Client-ID ersetzt nur diese eine
Verbindung; andere Clients desselben Accounts bleiben erhalten.
Der workerübergreifende Zustand liegt in SQLite:
- `ws_clients[(tenant_id, client_id)]`: Account-ID, letzte Sequenznummer,
Verbindungsstatus, Worker-ID und Queue-Startzeit,
- `ws_client_queue`: persistente Zustellaufträge pro Client,
- `ws_group_presence[(tenant_id, group_id)]`: gemeinsame Pong-Zeitpunkte,
- `cache_state`: gemeinsame Cache-Revision je Mandant. Gruppen- und
Zuordnungsänderungen erhöhen die Revision; jeder Worker verwirft daraufhin
seinen lokalen `GroupsService`-Cache und lädt ihn neu.
Die Sequenznummer wird nach jedem erfolgreichen Versand in `ws_clients`
fortgeschrieben. Ein Reconnect auf einem anderen Worker setzt die Zählung dort
fort. `client_sequence_locks[(tenant_id, client_id)]` serialisiert
Sequenzvergabe und Versand innerhalb eines Workers.
`authenticated[tenant_id][client_id]` speichert den Authentifizierungsstatus
des aktuellen Workers. Zusätzlich wird er in `ws_clients.authenticated`
gespiegelt, damit der Admin-Status alle Worker sieht. Ohne erfolgreichen
Code-0-Handshake werden keine fachlichen Nachrichten zugestellt.
Die Client-Zuordnungen bleiben nach einem Verbindungsabbruch in der Datenbank
erhalten, damit kurzfristige Reconnects ihre Queue wiederfinden. Dauerhaft
verlassene Webviews werden nach `WS_CLIENT_RETENTION_MINUTES` (Default 60
Minuten) aufgeräumt.
### Empfängerermittlung
`_get_recipients()` entscheidet anhand des Codes und der Absenderrolle:
- Code 99: alle Rollen,
- Code 100: Dispatcher, Beobachter, Gast und betroffene Gruppe(n),
- Code 200/300: Dispatcher, Beobachter und betroffene Gruppe,
- Code 1000: Dispatcher, Beobachter und alle Gruppen,
- Code 1100: Dispatcher, Beobachter und adressierte Gruppe,
- Code 2000: Dispatcher, Beobachter und die eigene Gruppe,
- Code 2: nur Dispatcher.
Die fachlichen Empfänger werden weiterhin als Account-IDs ermittelt.
Gruppen-Accounts werden über `group_accounts` aufgelöst. Anschließend expandiert
`_client_ids_for_accounts()` jeden Empfänger-Account auf alle seine bekannten
Client-IDs. Damit erhalten auch mehrere Tabs/Webviews desselben Accounts die
Nachricht.
### Zustellung
`_deliver()` sendet die Nachricht an jeden ermittelten Client. `_send()` prüft
zuerst, ob der Client lokal verbunden und authentifiziert ist:
- lokal verbunden, authentifiziert und ohne wartende Queue: direkter Versand,
- sonst: Eintrag in die gemeinsame Queue `ws_client_queue`.
Jeder Worker betreibt eine Zustellschleife (`cmbnet/ws/delivery.py`), die die
gemeinsame Queue regelmäßig nach Aufträgen für seine lokal verbundenen Clients
durchsucht. Dadurch erreicht eine HTTP-ausgelöste Benachrichtigung auch
WebSockets, die an einem anderen WSGI-Worker hängen. Die Latenz entspricht
`WS_BUS_POLL_INTERVAL` (Default 0,5 s); lokal eingestellte Nachrichten wecken
die Schleife zusätzlich sofort.
Der direkte Versand erfolgt pro Verbindung über einen `send_lock`. Dadurch
werden Heartbeat, Route-Thread und HTTP-ausgelöste Broadcasts nicht gleichzeitig
in denselben Socket schreiben. Zusätzlich serialisiert ein pro Client-ID
geführtes `sequence_lock` die Sequenzvergabe und den Sendevorgang. Erst nach
erfolgreichem `send()` wird die Sequenznummer in `ws_clients` fortgeschrieben;
schlägt der Versand fehl, bleibt sie unverändert und die Nachricht wird
gepuffert.
### Client-Queues
Queues werden unter dem Schlüssel
```text
(tenant_id, client_id)
```
in der Tabelle `ws_client_queue` gespeichert. Die Account-Zuordnung liegt in
`ws_clients`. Sie bleibt auch ohne aktive Verbindung bestehen, damit weitere
Nachrichten für dieselbe Webview gepuffert werden können. Da die Queue
prozessübergreifend ist, findet ein Reconnect auf einem beliebigen Worker seine
Aufträge wieder.
Eigenschaften:
- gepuffert werden Code 99 und alle Codes ab 100,
- Code 2 wird nur für aktuell verbundene Clients kurzlebig gepuffert
(`WS_EPHEMERAL_TTL_SECONDS`, Default 30 s) und danach verworfen,
- Codes unter 100 werden nicht gepuffert,
- das maximale Alter beträgt `WS_QUEUE_MAX_AGE_MINUTES` (Default 15 Minuten),
- die Altersmessung beginnt mit dem Anlegen der Queue, im Regelfall beim
Verbindungsabbruch,
- abgelaufene Queues werden geleert und als „Tombstone“ für den
Code-99-Hinweis behalten,
- dauerhaft getrennte Clients werden nach `WS_CLIENT_RETENTION_MINUTES`
(Default 60 Minuten) samt Queue und Zuordnung entfernt,
- Queues überleben einen Worker-Neustart und einen Reconnect auf einem anderen
Worker,
- es gibt derzeit keine feste Obergrenze für die Anzahl gepufferter
Nachrichten.
Da die Client-ID bei jedem Neuladen neu erzeugt wird, erbt eine neu geladene
Webview keine Nachrichten-Queue der vorherigen Seite. Nicht persistierte
Code-100/200/300-Ereignisse werden in diesem Fall über den neu geladenen
Initialzustand abgedeckt; persistierte Chat-Nachrichten kommen als Late Entries.
### Late Entries
Nach erfolgreicher Authentifizierung sendet der Broker persistierte
Chat-Nachrichten der letzten acht Stunden, für die der Account berechtigt ist.
Bereits aus der Client-Queue zugestellte Nachrichten werden dabei übersprungen.
Die aktuelle Implementierung sendet Late Entries bei **jeder** erfolgreichen
Authentifizierung. Bei einem Reconnect mit derselben Client-ID können dadurch
Nachrichten erneut ankommen, die bereits live zugestellt wurden. Bei einer neu
geladenen Webview mit neuer Client-ID ist die Nachlieferung dagegen gewollt.
### Heartbeat und Gruppenpräsenz
Der `HeartbeatManager` startet beim Anlegen der Flask-App in jedem Worker. Er
sendet Code 1 an die lokal verbundenen Clients und prüft alle 15 Sekunden die
Gruppenpräsenz. Die Pong-Zeitpunkte liegen in `ws_group_presence`, damit ein
Worker eine Gruppe nicht zurücksetzt, obwohl ein anderer Worker gerade Pongs
empfängt. Bei fehlendem Pong wird eine `online`-Gruppe nach dem konfigurierten
Timeout auf `unterwegs` gesetzt.
## 8. Nebenläufigkeit
Berücksichtigt sind:
- `send_lock` pro Verbindung serialisiert alle ausgehenden Frames.
- `client_sequence_locks` und `client_delivery_locks` serialisieren
Sequenzvergabe, Queue-Zustellung und Reconnect innerhalb eines Workers.
- Die gemeinsame Queue liegt in SQLite. Schreibende Zugriffe werden durch
SQLite serialisiert; WAL und `busy_timeout` reduzieren die Blockierzeit.
- Timer und die Zustellschleife laufen als Daemon-Threads.
- SQLite-Zugriffe erfolgen pro Thread über die Flask-App-Kontexte.
- Jeder Worker besitzt eine eigene `DeliveryWorker`-Schleife. Nach einer lokal
eingestellten Nachricht wird sie über ein Event sofort geweckt; Nachrichten
aus anderen Workern werden über das Polling-Intervall übernommen.
Nicht vollständig abgesichert sind:
- `connections` und `authenticated` werden ohne eigenen Lock gelesen und
geschrieben. Einzelne Dictionary-Operationen sind durch den GIL atomar,
zusammengesetzte Prüfungen und Ersetzungen sind es nicht.
- Eine neue Verbindung mit derselben Client-ID ersetzt die alte Registrierung.
Der alte Socket wird dabei aktiv geschlossen; seine Route entfernt über den
`ws`-Vergleich nicht die neue Verbindung.
- Zwischen Auth-Prüfung und tatsächlichem Senden kann eine Verbindung ersetzt
werden. Dann kann eine Nachricht an die neue Verbindung gehen oder in der
Queue landen.
- Die Zustellung ist at-least-once. Bei einem Absturz zwischen erfolgreichem
Senden und dem Löschen des Queue-Eintrags kann eine Nachricht nach einem
Reconnect erneut zugestellt werden.
- Bei sehr vielen Clients oder sehr häufigen Code-300-Nachrichten kann SQLite
zum Flaschenhals werden. Dann ist ein Wechsel auf Redis oder PostgreSQL als
gemeinsamer Bus sinnvoll.
## 9. Debugausgabe
Für die Fehlersuche gibt es eine ausführliche Broker-Debugausgabe.
### Aktivierung
Standardmäßig ist sie aktiv. Abschalten:
```bash
CMBNET_WS_DEBUG_MESSAGES=0
```
Die Einstellung liegt in `CMBNet/config.py` als `WS_DEBUG_MESSAGES`.
### Ausgabedatei
Die Ausgabe wird unabhängig von der Flask-Logger-Konfiguration in eine
Tagesdatei geschrieben:
```text
CMBNet/logs/cmbnet-ws-YYYY-MM-DD.log
```
Beispiel:
```bash
tail -f CMBNet/logs/cmbnet-ws-$(date +%F).log
```
### Inhalt
Jede eingehende Nachricht wird mit folgenden Feldern protokolliert:
- `code`
- `sender` mit Account-ID, Client-ID, Name, Rolle, Gruppen-ID und Gruppenalias
- `receiver_id`
- `client_id` der Absender-Webview
- `ts`
- `msg` (bei Code 0 redigiert)
- `recipients`: ermittelte Clients mit Client-ID, Account-ID, Name, Rolle,
Gruppe, `connected` und `authenticated`
- `note`: Grund, falls die Nachricht ignoriert oder abgelehnt wurde
Beispielzeile (gekürzt):
```text
2026-11-01 10:03:55.247 [TENANT:1] WS-IN {"code": 100, "sender": {"account_id": 10, "account_name": "gruppe", "role": "Gruppe", "group_id": 20, "group_alias": "G1", "client_id": "group-page-1"}, "receiver_id": null, "client_id": "group-page-1", "ts": 1793449907246, "msg": "{\"name\": \"Weg\", \"state\": \"erledigt\", \"actor\": 10, \"street_id\": 30, \"group_id\": 20}", "recipients": [{"client_id": "disp-page-1", "account_id": 11, "account_name": "dispatcher", "role": "Dispatcher", "group_id": null, "group_alias": null, "connected": true, "authenticated": true}, {"client_id": "group-page-1", "account_id": 10, "account_name": "gruppe", "role": "Gruppe", "group_id": 20, "group_alias": "G1", "connected": true, "authenticated": true}], "note": null}
```
Die Debugausgabe dokumentiert den **Soll-Empfängerkreis**. Ob der einzelne
Versand tatsächlich erfolgreich war, ergibt sich erst aus dem anschließenden
`_send()`; nicht erreichbare Clients werden gegebenenfalls gepuffert.
## 10. Abweichungen zwischen Soll-Beschreibung und aktuellem Code
Die folgenden Punkte sind bei einer Weiterentwicklung zu beachten. Mit
„behoben“ markierte Punkte beschreiben den korrigierten Stand; die übrigen
Punkte sind weiterhin offen.
### 10.1 Code 2 erreicht den Admin nicht
Soll: Fehlende Pongs sollen im Admin-Dashboard sichtbar sein.
Ist: Code 2 wird nur an Accounts der Rolle `Dispatcher` verteilt. Das
Admin-Dashboard zeigt lediglich die aktuell verbundenen Accounts über den
HTTP-Endpoint `/admin/api/broker/status`; Pong-Zeitpunkte oder überfällige
Pongs werden dort nicht dargestellt.
### 10.2 Heartbeat-Timeout wird nicht durchgesetzt
`WS_HEARTBEAT_TIMEOUT` ist konfiguriert, wird aber nicht verwendet. Eine
Verbindung wird nicht allein deshalb geschlossen, weil ein Client nicht auf
Code 1 antwortet. Code 2 beeinflusst derzeit nur den Gruppenstatus.
### 10.3 Code 99 kann nicht direkt per WebSocket gesendet werden
Soll: Admin-Client oder Dispatcher können Code 99 auslösen.
Ist: Ein Code-99-Frame eines WebSocket-Clients wird ignoriert. Die Auslösung
erfolgt ausschließlich serverseitig über `notify_reload()` aus HTTP-Handlern.
Das Ergebnis ist für die Clients identisch, der Übertragungsweg weicht aber von
der Beschreibung ab.
### 10.4 Rollenprüfung bei Chat-Codes (behoben)
Soll:
- Code 1000 und 1100: nur Dispatcher,
- Code 2000: nur Gruppen-Account.
Der Broker prüft die Senderrolle jetzt in `_validate_chat_sender()`. Bei Code
2000 wird zusätzlich kontrolliert, dass die aufgelöste Zielgruppe die eigene
Gruppe des Absenders ist. Unberechtigte Nachrichten werden vor der Persistenz
und Zustellung mit einer Warnung und einem Debug-Eintrag abgewiesen.
### 10.5 Code-2000-Normalisierung (behoben)
`_normalize_chat_message()` setzt für Code 2000 jetzt sowohl
`message.receiver_id` als auch `group_id` im normalisierten Payload. Dadurch
können Dispatcher-Ansichten die Nachricht der Gruppe zuordnen, und Late Entries
werden nach einem Reconnect wieder an die eigene Gruppe zugestellt.
Weiterhin offen ist die clientseitige Anzeige:
- In der Dispatcher-Ansicht wird Code 2000 nicht als Infodialog angezeigt.
- Im Beobachter-Modus (`CMBNET_VIEW_MODE === 'observer'`) wird Code 2000
vollständig ignoriert, obwohl Beobachter zum Empfängerkreis gehören.
- Der mobile Gruppen-Client zeigt die Nachricht an; die neue `group_id` dient
dort der Filterung, während „An“ für Code 2000 weiterhin fest „Dispatcher“
lautet.
### 10.6 Code 1100: Alias-Präfix wird nicht angewendet
Der frühere Code-1100-Zweig in `_prepare_message()` war wegen des vorzeitigen
`code >= 1000`-Returns nicht erreichbar und wurde entfernt. Ein Alias-Präfix
(`"<Alias>: "`) wird daher weiterhin nicht gesetzt. Der Alias ist im
normalisierten `sender`-Objekt enthalten.
### 10.7 Fehlende Namen bei Code 100/200/300
Die Soll-Beschreibung verlangt, dass bei Verwendung von IDs auch Accountname
oder Aliasname mitgesendet wird. Bei Code 100/200/300 enthält das Payload
überwiegend nur `actor`, `group_id` und fachliche IDs. Die Clients lösen Namen
über die separat geladenen Initialdaten auf. Chat-Nachrichten enthalten
dagegen ein vollständiges `sender`-Objekt.
### 10.8 Client-Zeitstempel bei Code 100/200 und Chat
Code 300 setzt den Zeitstempel serverseitig. Bei Code 100, Code 200 und den
Chat-Codes wird der vom Client mitgelieferte `ts`-Wert verwendet, sofern
vorhanden. Ein manipulierter Client kann damit die Sortierung und die
Late-Entry-Grenze beeinflussen. Für eine serverseitig verlässliche Chronologie
sollte der Broker den Zeitstempel auch für diese Codes setzen.
### 10.9 Late Entries bei jedem Reconnect
`authenticate()` ruft `send_late_entries()` bei jeder erfolgreichen
Authentifizierung auf. Bei einem Reconnect mit derselben Client-ID werden damit
persistierte Chat-Nachrichten erneut gesendet, auch wenn sie vor dem
Verbindungsabbruch schon live zugestellt wurden. Die Clients haben teilweise
eigene Deduplizierungsschlüssel, die das abfangen; der Broker selbst
unterscheidet nicht zwischen „bekannte Client-ID“ und „neue Client-ID“.
### 10.10 Queue-Alter und Queue-Länge
Die Queue-Lebenszeit beginnt beim Anlegen der Queue. Das ist im Regelfall der
Verbindungsabbruch, kann aber bei einer Queue, die erst durch eine nicht
zustellbare Nachricht entsteht, etwas später liegen. Es gibt keine Obergrenze
für die Anzahl oder den Speicherbedarf der gepufferten Nachrichten.
### 10.11 Mehrere Verbindungen pro Account (behoben)
`connections[tenant_id][client_id]` enthält genau eine Client-Verbindung.
Mehrere Tabs bzw. Webviews desselben Accounts besitzen unterschiedliche
Client-IDs und damit getrennte Verbindungen und Queues. Eine neue Verbindung
mit derselben Client-ID ersetzt nur diese eine Verbindung; der alte Socket wird
dabei aktiv geschlossen.
### 10.12 Mehrere WSGI-Worker (behoben)
WebSocket-Objekte bleiben prozesslokal, weil ein Socket nur von dem Worker
bedient werden kann, der ihn geöffnet hat. Der Zustand ist jedoch
prozessübergreifend:
- `ws_clients` enthält Client-Zuordnung, Sequenznummer und Verbindungsstatus,
- `ws_client_queue` enthält persistente Zustellaufträge,
- `ws_group_presence` enthält die gemeinsamen Pong-Zeitpunkte,
- `cache_state` enthält die gemeinsame Gruppen-Cache-Revision,
- jeder Worker pollt die Queue für seine lokal verbundenen Clients.
Eine HTTP-ausgelöste Benachrichtigung wird damit an Clients aller Worker
zugestellt. Voraussetzung ist, dass jeder Worker seine eigene
`DeliveryWorker`-Schleife startet. Bei Gunicorn darf `preload_app` nicht
verwendet werden, weil die Schleife sonst im Master statt in den Workern
startet. Die Zustellung ist at-least-once; Duplikate sind bei einem Absturz
zwischen Senden und Quittieren möglich.
Wird ein Worker-Prozess hart beendet (z. B. `SIGKILL`), läuft sein
`remove_connection()` nicht mehr. Seine Clients bleiben dann in `ws_clients`
als verbunden markiert und können weiter Queue-Einträge ansammeln. Ein
Reconnect derselben Client-ID korrigiert den Eintrag; ein regulärer
Gunicorn-Reload schließt die Verbindungen und räumt sie über den
`finally`-Zweig der WebSocket-Route auf. Für harte Abstürze ist ein
Worker-Liveness-Check (eigene Heartbeat-Tabelle) ein möglicher nächster
Schritt.
### 10.13 Administrator als Sender fachlicher Änderungen
Die Soll-Beschreibung nennt für Code 100/200/300 Dispatcher und Gruppen. Die
Implementierung erlaubt zusätzlich die Rolle `Administrator`. Die Admin-API
nutzt dies intern, um nach bereits erfolgter DB-Änderung ein Code-100/200-Event
zu verteilen. Ein direkter WebSocket-Frame eines Administrators wird ebenfalls
akzeptiert.
### 10.14 Queues nur bei bekannter Client-ID
`_queue_undeliverable()` benötigt eine dem Broker bekannte Client-ID in
`ws_clients`. Vor dem Code-0-Handshake ist sie noch nicht vorhanden; Nachrichten
werden dann nicht gepuffert. Nach einem Serverneustart bleiben die Zuordnungen
dagegen in der Datenbank erhalten. Eine neu geladene Webview mit neuer Client-ID
erhält keinen alten Puffer, sondern den aktuellen Initialzustand und die
persistierten Late Entries.
### 10.15 Broadcasts ohne Empfänger-ID
Bei Code 99, Code 1000 und einigen internen Nachrichten ist `receiver_id`
`null`. Das ist für Broadcasts plausibel, erfüllt aber nicht die strenge
Formulierung, dass jede Nachricht Sender und Empfänger enthalten muss. Die
Empfänger ergeben sich aus dem Code und dem Empfängerkreis.
### 10.16 Fehlerbehandlung im Route-Thread
`route_message()` führt Datenbankänderungen und Persistenz ohne eigenen
Transaktionsrahmen für den gesamten Ablauf aus. Eine unerwartete Exception
führt in der WebSocket-Route zum Schließen der Verbindung. Die fachliche
Änderung kann dann bereits committet sein, während die Zustellung nicht mehr
erfolgt.
## 11. Empfohlene nächste Schritte
1. Late Entries nur für neue Client-IDs oder mit einem serverseitigen
„zuletzt gesehen“-Zeitpunkt senden.
2. Code 2 zusätzlich an Administratoren verteilen oder einen separaten
Status-Endpoint für Pong-Überfälligkeit bereitstellen.
3. Zeitstempel für Code 100/200 und Chat-Nachrichten serverseitig setzen.
4. Queue-Länge begrenzen und die Schreiblast der DB-Outbox beobachten.
5. Code 2000 im Beobachter-Modus und als Infodialog anzeigen.
6. Bei Bedarf Redis oder PostgreSQL als schnelleren gemeinsamen Bus einsetzen,
falls das SQLite-Polling bei vielen Clients nicht mehr ausreicht.
## 12. Debugausgabe und Tests
Die Debugausgabe ist so aufgebaut, dass sie auch bei abgelehnten Nachrichten
eine Zeile erzeugt. Damit lässt sich nachvollziehen, ob eine Nachricht
- den Broker erreicht hat,
- einem Absender zugeordnet wurde,
- fachlich akzeptiert wurde,
- welcher Empfängerkreis ermittelt wurde,
- und ob der Empfänger verbunden und authentifiziert war.
Für automatisierte Tests können `WS_DEBUG_MESSAGES=0` gesetzt und die
bestehenden Queue- und WebSocket-E2E-Tests verwendet werden. Die Tests decken
insbesondere zwei Clients desselben Accounts, die getrennte Zustellung von
Code 100/300, Reconnect mit derselben Client-ID sowie eine neue Client-ID nach
einem Reload ab.