Files
Sternsinger/doc/broker.md
T
2026-10-31 19:14:52 +01:00

25 KiB

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:

ws(s)://<host>/<tenant>/ws

Beispiel:

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:

{
  "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:

{
  "code": 0,
  "msg": {
    "token": "<token>",
    "session_id": "<client-sitzungs-id>"
  }
}

Nach erfolgreicher Prüfung antwortet der Server mit einer Code-0-Bestätigung:

{
  "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:

{
  "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:

{"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:

{"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:

{
  "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:

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

(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:

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:

CMBNet/logs/cmbnet-ws-YYYY-MM-DD.log

Beispiel:

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):

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.