Broker unterstützt jetzt mehrere WSGI Worker
This commit is contained in:
1 parent
1e2a58e563
commit
f5b0c9509c
13 files changed
+1252
-327
No files matched your search
+115
-65
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user