Broker/Protocol Analyse
This commit is contained in:
1 parent
c477a05f03
commit
268e150f2b
7 files changed
+868
-2
No files matched your search
+667
@@ -0,0 +1,667 @@
|
||||
# Broker und WebSocket-Protokoll
|
||||
|
||||
Stand: 31.10.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 prozesslokale Vermittlungsinstanz zwischen allen aktiven
|
||||
WebSocket-Clients eines Mandanten. 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-Sitzung,
|
||||
- ü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 Sitzung
|
||||
|
||||
### 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>",
|
||||
"session_id": "<client-sitzungs-id>"
|
||||
}
|
||||
```
|
||||
|
||||
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 `session_id` wird pro Browser-Tab in `sessionStorage` erzeugt und bleibt
|
||||
über ein Neuladen der Seite erhalten. Sie ordnet die Verbindung einer
|
||||
Nachrichten-Queue zu.
|
||||
|
||||
Der Broker akzeptiert aus Kompatibilitätsgründen auch die ältere Objektform:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": {
|
||||
"token": "<token>",
|
||||
"session_id": "<client-sitzungs-id>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Nach erfolgreicher Prüfung antwortet der Server mit einer Code-0-Bestätigung:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"sender_id": 0,
|
||||
"receiver_id": null,
|
||||
"ts": 1793449907241,
|
||||
"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,
|
||||
"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.
|
||||
- `msg`: Text oder JSON-String mit dem fachlichen Inhalt.
|
||||
|
||||
`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?
|
||||
|
||||
Danach wird das Token als verbraucht markiert, die Sitzungs-ID normalisiert und
|
||||
der Account als authentifiziert registriert. Ohne gültigen Code 0 werden
|
||||
fachliche Nachrichten nicht akzeptiert; die Verbindung wird geschlossen.
|
||||
|
||||
### 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, "msg": "ping"}
|
||||
```
|
||||
|
||||
Die Heartbeat-Routine läuft in einem Daemon-Timer. Sie räumt zusätzlich
|
||||
abgelaufene Chat-Nachrichten und Sitzungs-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 Sitzungs-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 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`.
|
||||
|
||||
## 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. Die aktuelle Implementierung prüft die Senderrolle nicht.
|
||||
|
||||
### 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. Die aktuelle Implementierung prüft die
|
||||
Senderrolle nicht.
|
||||
|
||||
### Code 2000: Nachricht aus einer Gruppe
|
||||
|
||||
Soll-Sender: Gruppen-Account. Empfänger: alle Dispatcher, Beobachter und die
|
||||
eigene Gruppe. Die aktuelle Implementierung prüft die Senderrolle nicht.
|
||||
|
||||
## 7. Broker-Ablauf
|
||||
|
||||
### Verbindungsverwaltung
|
||||
|
||||
`WebSocketBroker.connections` ist ein verschachteltes Dictionary:
|
||||
|
||||
```text
|
||||
connections[tenant_id][account_id] = {
|
||||
ws, role, group_id, session_id,
|
||||
last_ping, connected_at, last_pong_at, send_lock
|
||||
}
|
||||
```
|
||||
|
||||
Pro Account wird derzeit genau eine Verbindung gespeichert. Eine neue
|
||||
Verbindung desselben Accounts überschreibt die alte Registrierung.
|
||||
|
||||
`authenticated[tenant_id][account_id]` speichert den Authentifizierungsstatus.
|
||||
Ohne erfolgreichen Code-0-Handshake werden keine fachlichen Nachrichten
|
||||
zugestellt.
|
||||
|
||||
### 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 Empfänger werden als Account-IDs ermittelt. Gruppen-Accounts werden über
|
||||
`group_accounts` aufgelöst.
|
||||
|
||||
### Zustellung
|
||||
|
||||
`_deliver()` sendet die Nachricht an jeden ermittelten Empfänger. `_send()`
|
||||
prüft zuerst die Authentifizierung:
|
||||
|
||||
- authentifiziert und Verbindung vorhanden: direkter Versand,
|
||||
- nicht authentifiziert oder Versand fehlgeschlagen: Eintrag in die
|
||||
Sitzungs-Queue, sofern eine Sitzungs-ID bekannt ist.
|
||||
|
||||
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.
|
||||
|
||||
### Sitzungs-Queues
|
||||
|
||||
Queues werden unter dem Schlüssel
|
||||
|
||||
```text
|
||||
(tenant_id, account_id, session_id)
|
||||
```
|
||||
|
||||
gespeichert. Die zuletzt bekannte Session-ID wird zusätzlich in
|
||||
`account_sessions` gehalten, damit Nachrichten auch ohne aktive Verbindung der
|
||||
richtigen Queue zugeordnet werden können.
|
||||
|
||||
Eigenschaften:
|
||||
|
||||
- gepuffert werden Code 99 und alle Codes ab 100,
|
||||
- Code 2 und 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,
|
||||
- Queues liegen ausschließlich im Arbeitsspeicher und überleben keinen
|
||||
Serverneustart,
|
||||
- es gibt derzeit keine feste Obergrenze für die Anzahl gepufferter
|
||||
Nachrichten.
|
||||
|
||||
### 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 Sitzungs-Queue zugestellte Nachrichten werden dabei
|
||||
übersprungen.
|
||||
|
||||
Die aktuelle Implementierung sendet Late Entries bei **jeder** erfolgreichen
|
||||
Authentifizierung, also auch bei einer bereits bekannten Sitzung. Die
|
||||
Soll-Beschreibung sieht eine initiale Historiennachlieferung für neue
|
||||
Websessions vor. Das kann bei Reconnects zu zusätzlichen Wiederholungen führen.
|
||||
|
||||
### Heartbeat und Gruppenpräsenz
|
||||
|
||||
Der `HeartbeatManager` startet beim Anlegen der Flask-App. Er sendet Code 1 und
|
||||
prüft alle 15 Sekunden die Gruppenpräsenz. Bei fehlendem Pong wird eine
|
||||
`online`-Gruppe nach dem konfigurierten Timeout auf `unterwegs` gesetzt.
|
||||
|
||||
## 8. Nebenläufigkeit
|
||||
|
||||
Berücksichtigt sind:
|
||||
|
||||
- `queue_lock` schützt `session_queues` und die Queue-Übergänge.
|
||||
- `send_lock` pro Verbindung serialisiert alle ausgehenden Frames.
|
||||
- Timer laufen als Daemon-Threads.
|
||||
- SQLite-Zugriffe erfolgen pro Thread über die Flask-App-Kontexte.
|
||||
|
||||
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 für denselben Account ersetzt die alte Registrierung,
|
||||
ohne den alten Socket aktiv zu schließen. Der alte Socket kann bis zum
|
||||
Client-seitigen Schließen weiter existieren; seine Route verwendet aber den
|
||||
Account-Kontext der neuen Verbindung.
|
||||
- `account_sessions`, `group_last_pong` und `group_online_since` werden ohne
|
||||
eigenen Lock aktualisiert.
|
||||
- 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.
|
||||
- Der Broker ist prozesslokal. Bei mehreren WSGI-Workern hat jeder Worker
|
||||
eigene Verbindungen und Queues. Eine HTTP-ausgelöste Benachrichtigung kann
|
||||
nur die Verbindungen des Workers erreichen, der den HTTP-Request bearbeitet.
|
||||
|
||||
## 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, Name, Rolle, Gruppen-ID und Gruppenalias
|
||||
- `receiver_id`
|
||||
- `session_id`
|
||||
- `ts`
|
||||
- `msg` (bei Code 0 redigiert)
|
||||
- `recipients`: ermittelte Empfänger mit Name, Rolle, Gruppe,
|
||||
`connected` und `authenticated`
|
||||
- `note`: Grund, falls die Nachricht ignoriert oder abgelehnt wurde
|
||||
|
||||
Beispielzeile (gekürzt):
|
||||
|
||||
```text
|
||||
2026-10-31 13:31:47.247 [TENANT:1] WS-IN {"code": 100, "sender": {"account_id": 10, "account_name": "gruppe", "role": "Gruppe", "group_id": 20, "group_alias": "G1"}, "receiver_id": null, "session_id": null, "ts": 1793449907246, "msg": "{\"name\": \"Weg\", \"state\": \"erledigt\", \"actor\": 10, \"street_id\": 30, \"group_id\": 20}", "recipients": [{"account_id": 10, "account_name": "gruppe", "role": "Gruppe", "group_id": 20, "group_alias": "G1", "connected": true, "authenticated": true}, {"account_id": 11, "account_name": "dispatcher", "role": "Dispatcher", "group_id": null, "group_alias": null, "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. Sie sind
|
||||
bewusst als Ist-Zustand dokumentiert und nicht alle in diesem Schritt
|
||||
funktional geändert.
|
||||
|
||||
### 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 Keine Rollenprüfung bei Chat-Codes
|
||||
|
||||
Soll:
|
||||
|
||||
- Code 1000 und 1100: nur Dispatcher,
|
||||
- Code 2000: nur Gruppen-Account.
|
||||
|
||||
Ist: Jeder authentifizierte Account kann Code 1000, 1100 oder 2000 senden. Die
|
||||
Empfängerermittlung ist korrekt, aber die Senderrolle wird nicht geprüft.
|
||||
|
||||
### 10.5 Code 2000 verliert Gruppen-ID und Empfänger-ID
|
||||
|
||||
In `_prepare_message()` werden Nachrichten ab Code 1000 vorzeitig an
|
||||
`_normalize_chat_message()` übergeben. Die anschließenden Zweige für Code 1100
|
||||
und 2000 sind dadurch nicht erreichbar.
|
||||
|
||||
Folge für Code 2000:
|
||||
|
||||
- `message.receiver_id` bleibt `null`.
|
||||
- Das normalisierte Payload enthält kein `group_id`.
|
||||
- Die Live-Zustellung an die Gruppe funktioniert nur, weil
|
||||
`_resolve_group_id()` als Fallback die Gruppe des Absenders verwendet.
|
||||
- Die Late-Entry-Prüfung `_is_allowed_for_client()` findet bei gespeicherten
|
||||
Code-2000-Nachrichten weder `group_id` noch `receiver_id` und liefert für
|
||||
Gruppen-Clients `False`. Code-2000-Nachrichten werden damit nach einem
|
||||
Reconnect nicht als Late Entry an die eigene Gruppe nachgeliefert.
|
||||
- Der Dispatcher-Client kann die Gruppenzuordnung nicht aus dem normalisierten
|
||||
Payload lesen. `handleGroupChatMessage()` in
|
||||
`static/js/views/dispatcher.js` ermittelt die Gruppe aus `payload.group_id`
|
||||
oder `message.receiver_id`; beide fehlen, deshalb wird die Nachricht dort
|
||||
verworfen.
|
||||
- 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, weil sein Filter eine
|
||||
fehlende Gruppen-ID als „eigene Gruppe“ behandelt. Die Anzeige „An“ kann
|
||||
dabei jedoch leer bleiben.
|
||||
|
||||
### 10.6 Code 1100: Alias-Präfix ist toter Code
|
||||
|
||||
Der Code-1100-Zweig in `_prepare_message()` ist wegen des vorzeitigen
|
||||
`code >= 1000`-Returns nicht erreichbar. Der dort vorgesehene Alias-Präfix
|
||||
(`"<Alias>: "`) wird daher nicht angewendet. Der Alias ist weiterhin 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 einer bereits bekannten Sitzung 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 „neue Sitzung“ und „bekannte Sitzung“.
|
||||
|
||||
### 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 Nur eine Verbindung pro Account
|
||||
|
||||
`connections[tenant_id][account_id]` enthält genau eine Verbindung. Öffnet
|
||||
derselbe Account mehrere Tabs, überschreibt der neue Tab die Registrierung.
|
||||
Der alte Socket wird nicht aktiv geschlossen. Die Sitzungs-Queue ist zwar pro
|
||||
Tab, aber die Verbindungsverwaltung und `account_sessions` kennen nur die
|
||||
zuletzt registrierte Sitzung.
|
||||
|
||||
### 10.12 Prozesslokaler Broker
|
||||
|
||||
Der Broker ist ein Singleton im Python-Prozess. Bei mehreren WSGI-Workern sind
|
||||
Verbindungen, Queues und Gruppenpräsenz nicht prozessübergreifend. Die
|
||||
HTTP-API eines Workers kann keine WebSocket-Verbindung eines anderen Workers
|
||||
direkt bedienen. Für einen zuverlässigen Betrieb ist entweder ein Worker
|
||||
erforderlich oder ein externer Broker/Message-Bus.
|
||||
|
||||
### 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 Sitzung
|
||||
|
||||
`_queue_undeliverable()` benötigt eine bekannte Sitzungs-ID in
|
||||
`account_sessions`. War ein Account in diesem Broker-Prozess noch nie
|
||||
authentifiziert, wird eine nicht zustellbare Nachricht nicht gepuffert. Nach
|
||||
einem Serverneustart sind alle Sitzungszuordnungen leer.
|
||||
|
||||
### 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. Code-2000-Normalisierung korrigieren: `receiver_id` und `group_id` vor dem
|
||||
Normalisieren setzen und in das gespeicherte Payload aufnehmen. Danach die
|
||||
Dispatcher- und Beobachter-Anzeige für Code 2000 prüfen.
|
||||
2. Rollenprüfung für Code 1000/1100/2000 ergänzen.
|
||||
3. Late Entries nur für neue Sitzungen oder mit einem serverseitigen
|
||||
„zuletzt gesehen“-Zeitpunkt senden.
|
||||
4. Code 2 zusätzlich an Administratoren verteilen oder einen separaten
|
||||
Status-Endpoint für Pong-Überfälligkeit bereitstellen.
|
||||
5. Zeitstempel für Code 100/200 und Chat-Nachrichten serverseitig setzen.
|
||||
6. Verbindungsverwaltung für mehrere Tabs oder explizites Schließen der alten
|
||||
Verbindung absichern.
|
||||
7. Queue-Länge begrenzen und Queue-Verhalten bei mehreren Workern klären.
|
||||
|
||||
## 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.
|
||||
Reference in new issue
Block a user