diff --git a/CMBNet/README_CMBNet.md b/CMBNet/README_CMBNet.md index 354fe17..716a606 100644 --- a/CMBNet/README_CMBNet.md +++ b/CMBNet/README_CMBNet.md @@ -61,6 +61,10 @@ Die beiden Zeitfenster lassen sich über Umgebungsvariablen konfigurieren: zugestellt. - `CMBNET_WS_GROUP_ONLINE_TIMEOUT_SECONDS` (Default `120`): Zeit ohne Code-2- Lebenszeichen, nach der eine Gruppe von `online` auf `unterwegs` wechselt. +- `CMBNET_WS_DEBUG_MESSAGES` (Default `1`): schreibt jede beim Broker + eingehende Nachricht inklusive Absender, Code und ermitteltem Empfängerkreis + nach `logs/cmbnet-ws-YYYY-MM-DD.log`. Mit `0` lässt sich die Ausgabe + abschalten. Die Sitzungs-Queues liegen im Arbeitsspeicher des Broker-Prozesses. Sie überstehen damit WebSocket-Unterbrechungen und Seiten-Reloads, nicht aber einen @@ -68,6 +72,10 @@ Neustart des Servers. Der mobile Client puffert zusätzlich ausgehende fachliche Nachrichten kurzzeitig lokal und sendet sie nach erfolgreicher Authentifizierung automatisch nach. +Eine ausführliche Beschreibung des Protokolls, der Brokerlogik, der +Nebenläufigkeit und der aktuellen Abweichungen steht in +[`../doc/broker.md`](../doc/broker.md). + ## Erste Einrichtung Nach der Initialisierung der Datenbank müssen noch Mandanten und ein Admin-Account angelegt werden. diff --git a/CMBNet/cmbnet/core/logging.py b/CMBNet/cmbnet/core/logging.py index e307f27..2eadee3 100644 --- a/CMBNet/cmbnet/core/logging.py +++ b/CMBNet/cmbnet/core/logging.py @@ -1,11 +1,15 @@ """ Transaktionslogging für CMBNet """ -import os +import json from datetime import datetime from pathlib import Path +from threading import Lock + from flask import current_app +_WS_DEBUG_LOCK = Lock() + def write_transaction_log(tenant_id, actor_id, actor_name, action, entity_type, entity_id, details=None): """ @@ -33,6 +37,33 @@ def write_transaction_log(tenant_id, actor_id, actor_name, action, entity_type, f.write(log_line) +def write_ws_debug_log(tenant_id, payload): + """Schreibt eine Broker-Debugzeile in ein separates Tageslog. + + Die Ausgabe enthält die eingehende Nachricht und den vom Broker + ermittelten Empfängerkreis. Sie ist bewusst unabhängig von der + Flask-Logger-Konfiguration, damit sie auch im Produktivbetrieb über + ``CMBNET_WS_DEBUG_MESSAGES`` gezielt verfügbar ist. + """ + if not current_app.config.get('WS_DEBUG_MESSAGES', True): + return + + log_dir = Path(current_app.config['LOG_DIR']) + log_dir.mkdir(parents=True, exist_ok=True) + + date_str = datetime.now().strftime('%Y-%m-%d') + log_file = log_dir / f'cmbnet-ws-{date_str}.log' + timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f')[:-3] + line = ( + f'{timestamp} [TENANT:{tenant_id}] WS-IN ' + f'{json.dumps(payload, ensure_ascii=False, default=str)}\n' + ) + + with _WS_DEBUG_LOCK: + with open(log_file, 'a', encoding='utf-8') as f: + f.write(line) + + def get_tenant_code(tenant_id): """Holt den Tenant-Code für die Logausgabe""" from cmbnet.db import get_db diff --git a/CMBNet/cmbnet/ws/broker.py b/CMBNet/cmbnet/ws/broker.py index 87b0fe0..1fa17f2 100644 --- a/CMBNet/cmbnet/ws/broker.py +++ b/CMBNet/cmbnet/ws/broker.py @@ -238,6 +238,81 @@ class WebSocketBroker: def _get_connection(self, tenant_id, account_id): return self.connections.get(tenant_id, {}).get(account_id) + def log_incoming(self, tenant_id, message, sender=None, recipients=None, note=None): + """Schreibt eine Debugzeile für eine beim Broker eingehende Nachricht. + + Erfasst werden Absender, Code, Empfänger-ID, Payload (bei Code 0 ohne + Token) und der ermittelte Empfängerkreis inklusive Verbindungsstatus. + Die Ausgabe ist unabhängig von der Flask-Logger-Konfiguration und kann + über ``WS_DEBUG_MESSAGES`` abgeschaltet werden. + """ + try: + if not current_app.config.get('WS_DEBUG_MESSAGES', True): + return + except RuntimeError: + return + + try: + db = get_db() + if sender is None and message.sender_id: + sender = db.execute( + 'SELECT * FROM accounts WHERE id = ? AND tenant_id = ?', + (message.sender_id, tenant_id) + ).fetchone() + + sender_info = None + if sender is not None: + sender_info = self._get_sender_info(tenant_id, sender) + + recipient_rows = [] + for recipient_id in sorted(set(recipients or [])): + account = db.execute( + 'SELECT * FROM accounts WHERE id = ? AND tenant_id = ?', + (recipient_id, tenant_id) + ).fetchone() + if account is None: + recipient_rows.append({ + 'account_id': recipient_id, + 'known': False, + 'connected': False, + 'authenticated': False + }) + continue + + info = self._get_sender_info(tenant_id, account) + info['connected'] = bool(self._get_connection(tenant_id, recipient_id)) + info['authenticated'] = self.is_authenticated(tenant_id, recipient_id) + recipient_rows.append(info) + + payload = message.msg + if message.code == 0: + payload = '' + elif not isinstance(payload, str): + payload = json.dumps(payload, ensure_ascii=False, default=str) + payload = str(payload) + if len(payload) > 1000: + payload = payload[:1000] + '…' + + entry = { + 'code': message.code, + 'sender': sender_info, + 'receiver_id': message.receiver_id, + 'session_id': getattr(message, 'session_id', None), + 'ts': message.ts, + 'msg': payload, + 'recipients': recipient_rows, + 'note': note + } + + from cmbnet.core.logging import write_ws_debug_log + write_ws_debug_log(tenant_id, entry) + except Exception as exc: + # Eine Debugausgabe darf den Nachrichtenfluss niemals stören. + try: + current_app.logger.warning('WS-Debugausgabe fehlgeschlagen: %s', exc) + except Exception: + pass + # ------------------------------------------------------------------ # Sitzungs-Queues # ------------------------------------------------------------------ @@ -533,6 +608,10 @@ class WebSocketBroker: (message.sender_id, tenant_id) ).fetchone() if not sender: + self.log_incoming( + tenant_id, message, sender=None, recipients=[], + note='Absender nicht im Mandanten gefunden' + ) return code = message.code @@ -540,11 +619,19 @@ class WebSocketBroker: # Code 0 wird ausschließlich in der WebSocket-Route (Handshake) # verarbeitet und niemals weitergeleitet. if code <= 0: + self.log_incoming( + tenant_id, message, sender, recipients=[], + note='interner Code, wird nicht über route_message verteilt' + ) return # Code 1 sendet ausschließlich der Server (Heartbeat-Routine). # Nachrichten dieses Typs von Clients werden ignoriert. if code == 1: + self.log_incoming( + tenant_id, message, sender, recipients=[], + note='Code 1 von Client ignoriert' + ) return # Code 2 ist die Antwort eines Clients auf den Heartbeat. Sie wird nur @@ -559,12 +646,20 @@ class WebSocketBroker: # dürfen diesen Code nicht selbst auslösen. if code == 99: if apply_business: + self.log_incoming( + tenant_id, message, sender, recipients=[], + note='Code 99 von Client ignoriert' + ) return self._deliver(tenant_id, message, sender) return # Sonstige interne Codes (< 100) werden nicht an die Oberfläche gegeben. if code < 100: + self.log_incoming( + tenant_id, message, sender, recipients=[], + note='interner Code < 100 ignoriert' + ) return # Ab hier: fachliche Nachrichten (>= 100). @@ -577,6 +672,10 @@ class WebSocketBroker: 'WebSocket-Nachricht abgelehnt: code=%s sender=%s tenant=%s msg=%s', code, sender['id'], tenant_id, str(message.msg)[:300] ) + self.log_incoming( + tenant_id, message, sender, recipients=[], + note='fachliche Änderung abgelehnt' + ) return message = self._prepare_message(tenant_id, message, sender) @@ -1126,7 +1225,9 @@ class WebSocketBroker: def _deliver(self, tenant_id, message, sender): """Stellt eine Nachricht an alle berechtigten, verbundenen Clients zu.""" - for recipient_id in self._get_recipients(tenant_id, message, sender): + recipients = sorted(self._get_recipients(tenant_id, message, sender)) + self.log_incoming(tenant_id, message, sender, recipients=recipients) + for recipient_id in recipients: self._send(tenant_id, recipient_id, message) def _send(self, tenant_id, account_id, message): diff --git a/CMBNet/cmbnet/ws/routes.py b/CMBNet/cmbnet/ws/routes.py index 118a118..e638011 100644 --- a/CMBNet/cmbnet/ws/routes.py +++ b/CMBNet/cmbnet/ws/routes.py @@ -65,6 +65,10 @@ def ws(ws, tenant): msg = WSMessage.from_json(data) if not msg: + current_app.logger.warning( + 'WebSocket-Nachricht ist kein gültiges JSON: tenant=%s account=%s length=%s', + tenant_id, account_id, len(data) + ) continue # Die Absender-ID stammt immer aus der Session und kann vom Client @@ -76,15 +80,25 @@ def ws(ws, tenant): token, session_id = _parse_auth_payload(msg.msg) if not session_id: session_id = getattr(msg, 'session_id', None) + if session_id: + msg.session_id = session_id if not token or not broker.authenticate( tenant_id, account_id, token, session_id ): + broker.log_incoming( + tenant_id, msg, recipients=[], + note='Code-0-Handshake fehlgeschlagen' + ) current_app.logger.warning( 'WebSocket-Authentifizierung fehlgeschlagen: tenant=%s account=%s', tenant_id, account_id ) ws.close() break + broker.log_incoming( + tenant_id, msg, recipients=[account_id], + note='Code-0-Handshake erfolgreich' + ) # Bestätigt dem Client den erfolgreichen Handshake. Erst jetzt # darf er gepufferte fachliche Nachrichten senden. broker.send_to_connection( @@ -97,6 +111,10 @@ def ws(ws, tenant): # Fachliche Nachrichten sind erst nach erfolgreicher # Authentifizierung erlaubt. if not broker.is_authenticated(tenant_id, account_id): + broker.log_incoming( + tenant_id, msg, recipients=[], + note='Nachricht vor Code-0-Authentifizierung' + ) ws.close() break diff --git a/CMBNet/config.py b/CMBNet/config.py index 66fc261..ec9282b 100644 --- a/CMBNet/config.py +++ b/CMBNet/config.py @@ -25,6 +25,12 @@ class Config: os.environ.get('CMBNET_WS_QUEUE_MAX_AGE_MINUTES', '15') ) LATE_ENTRY_MAX_AGE_HOURS = int(os.environ.get('CMBNET_LATE_ENTRY_MAX_AGE_HOURS', '8')) + # Ausführliche Broker-Debugausgabe für eingehende Nachrichten und den + # ermittelten Empfängerkreis. Kann im Betrieb über die Umgebungsvariable + # CMBNET_WS_DEBUG_MESSAGES=0 abgeschaltet werden. + WS_DEBUG_MESSAGES = os.environ.get( + 'CMBNET_WS_DEBUG_MESSAGES', '1' + ).strip().lower() not in ('0', 'false', 'no', 'off') LOG_DIR = BASE_DIR / 'logs' diff --git a/doc/broker.md b/doc/broker.md new file mode 100644 index 0000000..c2d125b --- /dev/null +++ b/doc/broker.md @@ -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):////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": "", + "session_id": "" +} +``` + +Das Token wird vorher über `GET //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": "", + "session_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 +(`": "`) 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. diff --git a/doc/prompt.txt b/doc/prompt.txt index deeacde..83e246e 100644 --- a/doc/prompt.txt +++ b/doc/prompt.txt @@ -204,3 +204,38 @@ Ein Klick in dieses Textfeld soll einen modalen Dialog starten, in dem alle Nach Entwickel für diese Views den Code für das Frontend und die notwendigen Anpassungen im Backend. ------8<----------------- + + +Die Logik des Brokers und das verwendete Protokoll soll auf korrekte Umsetzung untersucht werden. +Der Broker hat die Aufgabe, die Verbindung zu allen Clients (Websockets) zu verwalten, +Nachrichten entsprechend dem Protokoll von einem Client zu mehreren anderen Clients weiterzuleiten und +kurzzeitige Unterbrechungen in der Verbindung zu einem Client mit einer Nachrichten-Queue zu überbrücken. +Dabei muss Nebenläufigkeit berücksichtigt werden. +Welche Nachrichten konkret einem bestimmten Client weitergeleitet werden sollen, folgt aus der Rolle des jeweiligen Clients (also Account/View und eventuell Gruppenverknüpfung des Accounts) +Clients können über entsprechende Nachrichten Änderungen im State einer der Entitäten Gruppe oder Strasse in der Datenbank auslösen. +Gleichzeitig wird diese Zustandsänderung durch Weiterleitung an alle aktiven Clients kommuniziert. +Um neu hinzukommende Clients zu synchronisieren, werden unabhängig vom Broker die aktuellen Zustände per Web API übermittelt, +Die jeweiligen Websessions der Clients werden über Websocketverbindungsabbrüche hinweg anhand einer im Client generierten ID den entsprechenden Queues zugeordnet. +Bei neuen Websessions (d.h. dem Broker noch unbekannten Client-ID's) werden für diesen Client grundsätzlich bestimmte in der Datenbank historisierte Nachrichten initial übermittelt. + +Nachrichten werden im JSON-Format verschickt. Die Nachrichten müssen Sender und Empfänger enthalten. Sofern dazu ID's verwendet werden, müssen für die korrekte Darstellung im Client Accountname oder Aliasname mitgesendet werden. +Primäres Merkmal jeder Nachricht ist der Nachrichten-Code, anhand dessen der Broker über die Weiterleitung entscheidet. +Nachfolgend die Beschreibug der Nachrichtencodes soweit bekannt: +- Code=0: Sender ist jeder Client nach Neuladen, mit dem ein Zugriffstoken und die Client-ID zur Authentifizierung dem Broker mitgeteilt wird. Keine weiteren Empfänger. Nur intern für den Broker zur Verwendung. +- Code=1: Sender ist der Broker selbst, der zyklisch (1/Minute) jeden Client ein "ping" sendet und eine Antwort mit Code=2 vom Client erwartet. +- Code=2: Sender ist ein Client als unmittelbare Antwort auf Code=1. Bleibt diese Nachricht aus, kann dies auf den State einer Gruppe Einfluss haben. In der Übersicht im Dashboard ddes Admins wird dies angezeigt. +- Code=99: Sender ist der Broker selbst, ein Admin-Client oder bei Änderung der Account/Gruppen-Zuordnung ein Dispatcher. Die Nachricht wird immer an alle CLients gesendet und soll direkt oder indirekt einen Neustart des Clients auslösen (s.o.). Die Behandlung der Queues im Broker ist oben beschrieben. +- Ein Code < 100 dient nur zu internen Zwecken. +- Code=100: Sender kann ein Dispatcher oder eine Gruppe sein. Der State einer Straße hat sich geändert. Diese Nachricht wird an alle Accounts Dispatcher, Gast, Beobachter und die Gruppen verschickt, die mit dieser Straße verknüpft sind. +- Code=200: Sender ist ein Dispatcher oder eine Gruppe. Diese Nachricht wird an alle Accounts Dispatcher, Beobachter und an die betroffene Gruppe geschickt. +- Code=300: Sender ist eine Gruppe oder ein Dispatcher. Die geographische Position einer Gruppe hat sich geändert. Diese Nachricht wird an alle Accounts Dispatcher, Beobachter und an die betroffene Gruppe geschickt. Inhalt der Nachricht sind die neuen Geokoordinaten und dem auslösenden Account. +- Ein Code >= 1000 soll immer in einer Chatansicht mit "Von -> An", dem Zeitstempel der Nachricht und dem Chat-Text angezeigt werden und dem Nutzer des Clients über einen Infodialog angezigt werden. Diese Nachrichten werden historisiert für einen (konfigurierbaren) Zeitraum (Default 8 Studen). +- Code=1000: Sender ist ein Dispatcher. Die Nachricht wird an alle Accounts des Typs Dispatcher, Beobachter und alle Gruppen (Broadcast) übermittelt. +- Code=1100: Sender ist ein Dispatcher. Die Nachricht wird an alle Accounts des Typs Dispatcher, Beobachter und die eine addressierte Gruppe gesender. +- Code=2000: Sender ist en Client eines Gruppen-Accounts. Die Nachricht wird an alle Accounts des Typs Dispatcher und Beobachter und innerhalb der Gruppe übermittelt. + +Bitte erstelle eine Beschreibung des Protokolls und der Brokerlogik im Markdownformatm in der Datei doc/broker.md. Ergänze eventuell fehlende Nachrichtentypen. +Erläutere, an welchen Stellen die Beschreibung vom aktuellen Code-Stand abweicht. +Bau in die Software eine Debugausgabe für die beim Broker eingehenden Nachrichten ein einschließlich einer Ausgabe, an welche Clients diese weitergeleitet werden soll. + +------8<-----------------