696 lines
27 KiB
Markdown
696 lines
27 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 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-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,
|
|
"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?
|
|
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, "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`.
|
|
|
|
## 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 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
|
|
}
|
|
```
|
|
|
|
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.
|
|
|
|
`authenticated[tenant_id][client_id]` speichert den Authentifizierungsstatus.
|
|
Ohne erfolgreichen Code-0-Handshake werden keine fachlichen Nachrichten
|
|
zugestellt.
|
|
|
|
Zusätzlich hält der Broker:
|
|
|
|
- `client_accounts[(tenant_id, client_id)] = account_id`,
|
|
- `account_clients[(tenant_id, account_id)] = {client_id, ...}`,
|
|
- `disconnected_clients[(tenant_id, client_id)] = Zeitpunkt`.
|
|
|
|
Diese Zuordnungen bleiben nach einem Verbindungsabbruch 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 die Authentifizierung:
|
|
|
|
- authentifiziert und Verbindung vorhanden: direkter Versand,
|
|
- nicht authentifiziert oder Versand fehlgeschlagen: Eintrag in die
|
|
Client-Queue, sofern die Client-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.
|
|
|
|
### Client-Queues
|
|
|
|
Queues werden unter dem Schlüssel
|
|
|
|
```text
|
|
(tenant_id, client_id)
|
|
```
|
|
|
|
gespeichert. Die Account-Zuordnung liegt in `client_accounts`. Sie bleibt auch
|
|
ohne aktive Verbindung bestehen, damit weitere Nachrichten für dieselbe Webview
|
|
gepuffert 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,
|
|
- dauerhaft getrennte Clients werden nach `WS_CLIENT_RETENTION_MINUTES`
|
|
(Default 60 Minuten) samt Queue und Zuordnung entfernt,
|
|
- Queues liegen ausschließlich im Arbeitsspeicher und überleben keinen
|
|
Serverneustart,
|
|
- 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. 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 `client_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`, `authenticated`, `client_accounts` und `account_clients`
|
|
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.
|
|
- `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.
|
|
Das ist die wichtigste verbleibende Einschränkung für den Mehrclient-Betrieb.
|
|
|
|
## 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 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 Client-ID
|
|
|
|
`_queue_undeliverable()` benötigt eine dem Broker bekannte Client-ID in
|
|
`client_accounts`. Vor dem Code-0-Handshake und nach einem Serverneustart sind
|
|
keine Client-Zuordnungen vorhanden; Nachrichten werden dann nicht gepuffert.
|
|
Eine neu geladene Webview erhält stattdessen 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 Queue-Verhalten bei mehreren Workern klären.
|
|
5. Code 2000 im Beobachter-Modus und als Infodialog anzeigen.
|
|
6. Den prozesslokalen Broker durch einen gemeinsamen Message-Bus oder einen
|
|
einzelnen WebSocket-Worker ersetzen, falls mehrere WSGI-Worker betrieben
|
|
werden.
|
|
|
|
## 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.
|