Broker unterstützt jetzt mehrere WSGI Worker

This commit is contained in:
concierge committed 2026-11-03 16:47:20 +01:00
1 parent 1e2a58e563
commit f5b0c9509c
13 files changed
+1252 -327

No files matched your search

+115 -65
View File
@@ -15,8 +15,9 @@ Die zentrale Implementierung liegt in:
## 1. Grundidee
Der Broker ist eine prozesslokale Vermittlungsinstanz zwischen allen aktiven
WebSocket-Clients eines Mandanten. Er
Der Broker ist eine Vermittlungsinstanz zwischen allen aktiven WebSocket-Clients
eines Mandanten. Die Socket-Objekte sind prozesslokal, der Client-Zustand und
die Zustell-Queue liegen gemeinsam in SQLite. Er
- verwaltet die WebSocket-Verbindungen und deren Authentifizierungsstatus,
- ordnet Nachrichten anhand ihres Codes einem Empfängerkreis zu,
@@ -140,9 +141,11 @@ Zählung ab 1.
Clients merken sich die zuletzt empfangene Sequenznummer. Trifft nach einem
Reconnect eine andere Nummer als `zuletzt + 1` ein, zeigt der Client einen
Code-99-ähnlichen Neulade-Dialog an. Die Sequenzzählung liegt bewusst nur im
Broker-Prozess und nicht in der Datenbank; nach einem Broker-Neustart beginnt
sie neu und löst bei bereits geöffneten Clients den Neulade-Hinweis aus.
Code-99-ähnlichen Neulade-Dialog an. Die Sequenzzählung liegt in
`ws_clients.last_seq` und bleibt damit auch bei einem Worker-Wechsel oder
Neustart eines Workers erhalten. Nach einem vollständigen Verlust der
Datenbank beginnt sie neu und löst bei bereits geöffneten Clients den
Neulade-Hinweis aus.
`sender_id` und `receiver_id` werden nicht in jedem Fall mit lesbaren Namen
ergänzt. Chat-Nachrichten enthalten zusätzlich ein `sender`-Objekt mit
@@ -384,7 +387,8 @@ Absenders sein; Nachrichten an eine fremde Gruppe werden abgewiesen.
### Verbindungsverwaltung
`WebSocketBroker.connections` ist ein verschachteltes Dictionary:
`WebSocketBroker.connections` ist ein prozesslokales, verschachteltes
Dictionary:
```text
connections[tenant_id][client_id] = {
@@ -393,28 +397,35 @@ connections[tenant_id][client_id] = {
}
```
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.
Die zuletzt zugestellte Sequenznummer wird zusätzlich in
`client_sequences[(tenant_id, client_id)]` geführt, damit sie einen Reconnect
überlebt. `client_sequence_locks[(tenant_id, client_id)]` serialisiert
Sequenzvergabe und Versand pro Client.
Es enthält nur die WebSocket-Objekte des aktuellen Workers. Eine Client-ID
gehört genau zu einer Webview. Ein Account kann daher mehrere Clients parallel
betreiben. Eine neue Verbindung mit derselben Client-ID ersetzt nur diese eine
Verbindung; andere Clients desselben Accounts bleiben erhalten.
`authenticated[tenant_id][client_id]` speichert den Authentifizierungsstatus.
Ohne erfolgreichen Code-0-Handshake werden keine fachlichen Nachrichten
zugestellt.
Der workerübergreifende Zustand liegt in SQLite:
Zusätzlich hält der Broker:
- `ws_clients[(tenant_id, client_id)]`: Account-ID, letzte Sequenznummer,
Verbindungsstatus, Worker-ID und Queue-Startzeit,
- `ws_client_queue`: persistente Zustellaufträge pro Client,
- `ws_group_presence[(tenant_id, group_id)]`: gemeinsame Pong-Zeitpunkte,
- `cache_state`: gemeinsame Cache-Revision je Mandant. Gruppen- und
Zuordnungsänderungen erhöhen die Revision; jeder Worker verwirft daraufhin
seinen lokalen `GroupsService`-Cache und lädt ihn neu.
- `client_accounts[(tenant_id, client_id)] = account_id`,
- `account_clients[(tenant_id, account_id)] = {client_id, ...}`,
- `disconnected_clients[(tenant_id, client_id)] = Zeitpunkt`,
- `client_sequences[(tenant_id, client_id)] = letzte Sequenznummer`.
Die Sequenznummer wird nach jedem erfolgreichen Versand in `ws_clients`
fortgeschrieben. Ein Reconnect auf einem anderen Worker setzt die Zählung dort
fort. `client_sequence_locks[(tenant_id, client_id)]` serialisiert
Sequenzvergabe und Versand innerhalb eines Workers.
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.
`authenticated[tenant_id][client_id]` speichert den Authentifizierungsstatus
des aktuellen Workers. Zusätzlich wird er in `ws_clients.authenticated`
gespiegelt, damit der Admin-Status alle Worker sieht. Ohne erfolgreichen
Code-0-Handshake werden keine fachlichen Nachrichten zugestellt.
Die Client-Zuordnungen bleiben nach einem Verbindungsabbruch in der Datenbank
erhalten, damit kurzfristige Reconnects ihre Queue wiederfinden. Dauerhaft
verlassene Webviews werden nach `WS_CLIENT_RETENTION_MINUTES` (Default 60
Minuten) aufgeräumt.
### Empfängerermittlung
@@ -437,18 +448,25 @@ Nachricht.
### Zustellung
`_deliver()` sendet die Nachricht an jeden ermittelten Client. `_send()` prüft
zuerst die Authentifizierung:
zuerst, ob der Client lokal verbunden und authentifiziert ist:
- authentifiziert und Verbindung vorhanden: direkter Versand,
- nicht authentifiziert oder Versand fehlgeschlagen: Eintrag in die
Client-Queue, sofern die Client-ID bekannt ist.
- lokal verbunden, authentifiziert und ohne wartende Queue: direkter Versand,
- sonst: Eintrag in die gemeinsame Queue `ws_client_queue`.
Jeder Worker betreibt eine Zustellschleife (`cmbnet/ws/delivery.py`), die die
gemeinsame Queue regelmäßig nach Aufträgen für seine lokal verbundenen Clients
durchsucht. Dadurch erreicht eine HTTP-ausgelöste Benachrichtigung auch
WebSockets, die an einem anderen WSGI-Worker hängen. Die Latenz entspricht
`WS_BUS_POLL_INTERVAL` (Default 0,5 s); lokal eingestellte Nachrichten wecken
die Schleife zusätzlich sofort.
Der direkte Versand erfolgt pro Verbindung über einen `send_lock`. Dadurch
werden Heartbeat, Route-Thread und HTTP-ausgelöste Broadcasts nicht gleichzeitig
in denselben Socket schreiben. Zusätzlich serialisiert ein pro Client-ID
geführtes `sequence_lock` die Sequenzvergabe und den Sendevorgang. Erst nach
erfolgreichem `send()` wird die Sequenznummer fortgeschrieben; schlägt der
Versand fehl, bleibt sie unverändert und die Nachricht wird gepuffert.
erfolgreichem `send()` wird die Sequenznummer in `ws_clients` fortgeschrieben;
schlägt der Versand fehl, bleibt sie unverändert und die Nachricht wird
gepuffert.
### Client-Queues
@@ -458,14 +476,18 @@ Queues werden unter dem Schlüssel
(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.
in der Tabelle `ws_client_queue` gespeichert. Die Account-Zuordnung liegt in
`ws_clients`. Sie bleibt auch ohne aktive Verbindung bestehen, damit weitere
Nachrichten für dieselbe Webview gepuffert werden können. Da die Queue
prozessübergreifend ist, findet ein Reconnect auf einem beliebigen Worker seine
Aufträge wieder.
Eigenschaften:
- gepuffert werden Code 99 und alle Codes ab 100,
- Code 2 und Codes unter 100 werden nicht gepuffert,
- Code 2 wird nur für aktuell verbundene Clients kurzlebig gepuffert
(`WS_EPHEMERAL_TTL_SECONDS`, Default 30 s) und danach verworfen,
- Codes unter 100 werden nicht gepuffert,
- das maximale Alter beträgt `WS_QUEUE_MAX_AGE_MINUTES` (Default 15 Minuten),
- die Altersmessung beginnt mit dem Anlegen der Queue, im Regelfall beim
Verbindungsabbruch,
@@ -473,8 +495,8 @@ Eigenschaften:
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,
- Queues überleben einen Worker-Neustart und einen Reconnect auf einem anderen
Worker,
- es gibt derzeit keine feste Obergrenze für die Anzahl gepufferter
Nachrichten.
@@ -496,37 +518,45 @@ 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.
Der `HeartbeatManager` startet beim Anlegen der Flask-App in jedem Worker. Er
sendet Code 1 an die lokal verbundenen Clients und prüft alle 15 Sekunden die
Gruppenpräsenz. Die Pong-Zeitpunkte liegen in `ws_group_presence`, damit ein
Worker eine Gruppe nicht zurücksetzt, obwohl ein anderer Worker gerade Pongs
empfängt. Bei fehlendem Pong wird eine `online`-Gruppe nach dem konfigurierten
Timeout auf `unterwegs` gesetzt.
## 8. Nebenläufigkeit
Berücksichtigt sind:
- `queue_lock` schützt `client_queues` und die Queue-Übergänge.
- `send_lock` pro Verbindung serialisiert alle ausgehenden Frames.
- Timer laufen als Daemon-Threads.
- `client_sequence_locks` und `client_delivery_locks` serialisieren
Sequenzvergabe, Queue-Zustellung und Reconnect innerhalb eines Workers.
- Die gemeinsame Queue liegt in SQLite. Schreibende Zugriffe werden durch
SQLite serialisiert; WAL und `busy_timeout` reduzieren die Blockierzeit.
- Timer und die Zustellschleife laufen als Daemon-Threads.
- SQLite-Zugriffe erfolgen pro Thread über die Flask-App-Kontexte.
- Jeder Worker besitzt eine eigene `DeliveryWorker`-Schleife. Nach einer lokal
eingestellten Nachricht wird sie über ein Event sofort geweckt; Nachrichten
aus anderen Workern werden über das Polling-Intervall übernommen.
Nicht vollständig abgesichert sind:
- `connections`, `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.
- `connections` und `authenticated` werden ohne eigenen Lock gelesen und
geschrieben. Einzelne Dictionary-Operationen sind durch den GIL atomar,
zusammengesetzte Prüfungen und Ersetzungen sind es nicht.
- Eine neue Verbindung mit derselben Client-ID ersetzt die alte Registrierung.
Der alte Socket wird dabei aktiv geschlossen; seine Route entfernt über den
`ws`-Vergleich nicht die neue Verbindung.
- `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.
- Die Zustellung ist at-least-once. Bei einem Absturz zwischen erfolgreichem
Senden und dem Löschen des Queue-Eintrags kann eine Nachricht nach einem
Reconnect erneut zugestellt werden.
- Bei sehr vielen Clients oder sehr häufigen Code-300-Nachrichten kann SQLite
zum Flaschenhals werden. Dann ist ein Wechsel auf Redis oder PostgreSQL als
gemeinsamer Bus sinnvoll.
## 9. Debugausgabe
@@ -686,13 +716,33 @@ 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
### 10.12 Mehrere WSGI-Worker (behoben)
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.
WebSocket-Objekte bleiben prozesslokal, weil ein Socket nur von dem Worker
bedient werden kann, der ihn geöffnet hat. Der Zustand ist jedoch
prozessübergreifend:
- `ws_clients` enthält Client-Zuordnung, Sequenznummer und Verbindungsstatus,
- `ws_client_queue` enthält persistente Zustellaufträge,
- `ws_group_presence` enthält die gemeinsamen Pong-Zeitpunkte,
- `cache_state` enthält die gemeinsame Gruppen-Cache-Revision,
- jeder Worker pollt die Queue für seine lokal verbundenen Clients.
Eine HTTP-ausgelöste Benachrichtigung wird damit an Clients aller Worker
zugestellt. Voraussetzung ist, dass jeder Worker seine eigene
`DeliveryWorker`-Schleife startet. Bei Gunicorn darf `preload_app` nicht
verwendet werden, weil die Schleife sonst im Master statt in den Workern
startet. Die Zustellung ist at-least-once; Duplikate sind bei einem Absturz
zwischen Senden und Quittieren möglich.
Wird ein Worker-Prozess hart beendet (z. B. `SIGKILL`), läuft sein
`remove_connection()` nicht mehr. Seine Clients bleiben dann in `ws_clients`
als verbunden markiert und können weiter Queue-Einträge ansammeln. Ein
Reconnect derselben Client-ID korrigiert den Eintrag; ein regulärer
Gunicorn-Reload schließt die Verbindungen und räumt sie über den
`finally`-Zweig der WebSocket-Route auf. Für harte Abstürze ist ein
Worker-Liveness-Check (eigene Heartbeat-Tabelle) ein möglicher nächster
Schritt.
### 10.13 Administrator als Sender fachlicher Änderungen
@@ -705,10 +755,11 @@ 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.
`ws_clients`. Vor dem Code-0-Handshake ist sie noch nicht vorhanden; Nachrichten
werden dann nicht gepuffert. Nach einem Serverneustart bleiben die Zuordnungen
dagegen in der Datenbank erhalten. Eine neu geladene Webview mit neuer Client-ID
erhält keinen alten Puffer, sondern den aktuellen Initialzustand und die
persistierten Late Entries.
### 10.15 Broadcasts ohne Empfänger-ID
@@ -732,11 +783,10 @@ erfolgt.
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.
4. Queue-Länge begrenzen und die Schreiblast der DB-Outbox beobachten.
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.
6. Bei Bedarf Redis oder PostgreSQL als schnelleren gemeinsamen Bus einsetzen,
falls das SQLite-Polling bei vielen Clients nicht mehr ausreicht.
## 12. Debugausgabe und Tests