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
+1246 -321

No files matched your search

+25 -5
View File
@@ -70,12 +70,32 @@ Die Zeitfenster lassen sich über Umgebungsvariablen konfigurieren:
eingehende Nachricht inklusive Absender, Client-ID, Code und ermitteltem
Empfängerkreis nach `logs/cmbnet-ws-YYYY-MM-DD.log`. Mit `0` lässt sich die
Ausgabe abschalten.
- `CMBNET_WS_BUS_POLL_INTERVAL` (Default `0.5`): Intervall in Sekunden, in dem
jeder Worker die gemeinsame Queue für seine lokal verbundenen Clients prüft.
- `CMBNET_WS_EPHEMERAL_TTL_SECONDS` (Default `30`): Lebensdauer kurzlebiger
Code-2-Zustellaufträge.
- `CMBNET_WS_WORKER_ID`: optionale feste Worker-ID; muss je Worker-Prozess
eindeutig sein. Standardmäßig wird `<hostname>:<pid>` verwendet.
Die Client-Queues liegen im Arbeitsspeicher des Broker-Prozesses. Sie
überstehen damit kurze WebSocket-Unterbrechungen, nicht aber einen
Seiten-Reload mit neuer Client-ID oder einen Neustart des Servers. Der mobile
Client puffert zusätzlich ausgehende fachliche Nachrichten kurzzeitig im
Speicher und sendet sie nach erfolgreicher Authentifizierung automatisch nach.
Die Client-Queues und Sequenznummern liegen in der gemeinsamen SQLite-Datenbank
(`ws_clients`, `ws_client_queue`). Dadurch überstehen sie einen Worker-Neustart
und einen Reconnect auf einem anderen WSGI-Worker. Jeder Worker betreibt eine
eigene Zustellschleife und liefert nur an seine lokal verbundenen Clients aus.
Die Latenz für workerübergreifende Nachrichten ergibt sich aus
`CMBNET_WS_BUS_POLL_INTERVAL` (Default `0.5` Sekunden). Der mobile Client
puffert zusätzlich ausgehende fachliche Nachrichten kurzzeitig im Speicher und
sendet sie nach erfolgreicher Authentifizierung automatisch nach.
Für den Betrieb mit mehreren Workern muss Gunicorn ohne `preload_app` laufen,
damit Heartbeat und Zustellschleife in jedem Worker-Prozess starten:
```bash
gunicorn --worker-class gevent --workers 4 --bind 127.0.0.1:5000 wsgi:app
```
SQLite läuft dabei im WAL-Modus mit einem `busy_timeout`. Bei sehr vielen
Clients oder hoher Schreiblast sollte statt SQLite ein Redis- oder
PostgreSQL-Bus verwendet werden.
Eine ausführliche Beschreibung des Protokolls, der Brokerlogik, der
Nebenläufigkeit und der aktuellen Abweichungen steht in
+16
View File
@@ -157,6 +157,12 @@ def create_app(config_name=None):
# WebSocket Routes laden
from cmbnet.ws import routes
# Optionale feste Worker-ID aus der Konfiguration übernehmen. Der Broker
# liest sonst CMBNET_WS_WORKER_ID bzw. bildet <hostname>:<pid>.
from cmbnet.ws import broker as ws_broker
if app.config.get('WS_WORKER_ID'):
ws_broker.worker_id = app.config['WS_WORKER_ID']
# Heartbeat starten (Code 1 jede Minute, Aufräumen alter Nachrichten)
from cmbnet.ws.heartbeat import heartbeat_manager
heartbeat_manager.start(
@@ -164,6 +170,16 @@ def create_app(config_name=None):
interval=app.config.get('WS_HEARTBEAT_INTERVAL', 60)
)
# Worker-lokale Schleife für die gemeinsame Zustell-Queue. Jeder
# Gunicorn-/WSGI-Worker muss eine eigene Instanz starten. Bei
# ``preload_app=True`` würde sie im Master starten und in den Workern
# fehlen; deshalb ist der Betrieb ohne Preload erforderlich.
from cmbnet.ws.delivery import delivery_worker
delivery_worker.start(
app,
interval=app.config.get('WS_BUS_POLL_INTERVAL', 0.5)
)
# Favicon explizit bedienen, damit /favicon.ico nicht als Tenant-Pfad
# interpretiert wird.
@app.route('/favicon.ico')
+17 -31
View File
@@ -356,38 +356,24 @@ def import_streets(**kwargs):
@admin_api_bp.route('/broker/status')
@role_required('Administrator')
def broker_status(**kwargs):
"""Status aktiver WebSocket-Verbindungen"""
connections = broker.connections.get(g.tenant_id, {}) if hasattr(broker, 'connections') else {}
"""Status aktiver WebSocket-Verbindungen aller Worker.
Die Verbindungsliste liegt in der gemeinsamen Tabelle ``ws_clients``.
Dadurch zeigt das Dashboard auch Clients, die an einem anderen
WSGI-Worker hängen.
"""
connections = broker.describe_connections(g.tenant_id)
result = []
for client_id, conn in connections.items():
account_id = conn.get('account_id')
account = get_db().execute(
'SELECT id, name, role FROM accounts WHERE id = ? AND tenant_id = ?',
(account_id, g.tenant_id)
).fetchone()
if not account:
continue
entry = {
'client_id': client_id,
'account_id': account['id'],
'account_name': account['name'],
'role': account['role'],
'authenticated': broker.is_authenticated(g.tenant_id, client_id),
'group_id': None,
'group_alias': None
}
if account['role'] == 'Gruppe':
group = get_db().execute(
'''SELECT g.id, g.aliasname FROM groups g
JOIN group_accounts ga
ON ga.group_id = g.id AND ga.tenant_id = g.tenant_id
WHERE ga.account_id = ? AND g.tenant_id = ?''',
(account['id'], g.tenant_id)
).fetchone()
if group:
entry['group_id'] = group['id']
entry['group_alias'] = group['aliasname']
result.append(entry)
for conn in connections:
result.append({
'client_id': conn['client_id'],
'account_id': conn['account_id'],
'account_name': conn['account_name'],
'role': conn['role'],
'authenticated': bool(conn['authenticated']),
'group_id': conn['group_id'],
'group_alias': conn['group_alias']
})
return jsonify({'connections': result})
+69 -1
View File
@@ -11,8 +11,16 @@ def get_db():
db_path = current_app.config['DATABASE_PATH']
# Stelle sicher, dass das instance Verzeichnis existiert
Path(db_path).parent.mkdir(parents=True, exist_ok=True)
g.db = sqlite3.connect(db_path)
g.db = sqlite3.connect(db_path, timeout=30)
g.db.row_factory = sqlite3.Row
# Mehrere WSGI-Worker schreiben gleichzeitig in dieselbe SQLite-Datei.
# busy_timeout zuerst setzen, damit auch das Umschalten auf WAL bei
# parallelen Verbindungen warten kann statt sofort zu scheitern.
# WAL erlaubt parallele Leser und reduziert die Blockierzeit bei
# Schreibern.
g.db.execute('PRAGMA busy_timeout = 30000')
g.db.execute('PRAGMA journal_mode = WAL')
g.db.execute('PRAGMA synchronous = NORMAL')
return g.db
@@ -23,6 +31,65 @@ def close_db(e=None):
db.close()
def ensure_ws_schema(db):
"""Legt die Tabellen für den prozessübergreifenden Broker-Zustand an."""
db.executescript('''
CREATE TABLE IF NOT EXISTS ws_clients (
tenant_id INTEGER NOT NULL,
client_id TEXT NOT NULL,
account_id INTEGER NOT NULL,
last_seq INTEGER NOT NULL DEFAULT 0,
worker_id TEXT,
authenticated INTEGER NOT NULL DEFAULT 0,
connected_at REAL,
disconnected_at REAL,
queue_started_at REAL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (tenant_id, client_id),
FOREIGN KEY (tenant_id) REFERENCES tenants(id),
FOREIGN KEY (account_id) REFERENCES accounts(id)
);
CREATE TABLE IF NOT EXISTS ws_client_queue (
id INTEGER PRIMARY KEY AUTOINCREMENT,
tenant_id INTEGER NOT NULL,
client_id TEXT NOT NULL,
code INTEGER NOT NULL,
payload TEXT NOT NULL,
code99_only INTEGER NOT NULL DEFAULT 0,
created_at REAL NOT NULL,
expires_at REAL,
FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);
CREATE TABLE IF NOT EXISTS ws_group_presence (
tenant_id INTEGER NOT NULL,
group_id INTEGER NOT NULL,
last_pong_at REAL,
online_since REAL,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (tenant_id, group_id),
FOREIGN KEY (tenant_id) REFERENCES tenants(id),
FOREIGN KEY (group_id) REFERENCES groups(id)
);
CREATE TABLE IF NOT EXISTS cache_state (
key TEXT PRIMARY KEY,
revision INTEGER NOT NULL DEFAULT 0,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX IF NOT EXISTS idx_ws_clients_account
ON ws_clients(tenant_id, account_id);
CREATE INDEX IF NOT EXISTS idx_ws_client_queue_client
ON ws_client_queue(tenant_id, client_id, id);
CREATE INDEX IF NOT EXISTS idx_ws_client_queue_expires
ON ws_client_queue(expires_at);
''')
db.commit()
def ensure_schema():
"""Ergänzt bestehende Datenbanken um das Gruppen-Account-Zuordnungsmodell.
@@ -32,6 +99,7 @@ def ensure_schema():
und die alte Spalte durch einen Tabellen-Neubau entfernt.
"""
db = get_db()
ensure_ws_schema(db)
groups_table = db.execute(
"SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'groups'"
).fetchone()
+79 -7
View File
@@ -10,10 +10,61 @@ from cmbnet.db import get_db
class GroupsService:
# In-Memory Cache: groups_cache[tenant_id][group_id] = group_dict
_cache = {}
# Gemeinsame Cache-Revision je Mandant. Sie liegt in der Tabelle
# ``cache_state`` und wird bei jeder schreibenden Änderung erhöht. Dadurch
# verwirft jeder Worker seinen lokalen Cache, sobald ein anderer Worker
# Gruppen- oder Zuordnungsdaten geändert hat.
_cache_revision = {}
@classmethod
def _revision_key(cls, tenant_id):
return f'groups:{tenant_id}'
@classmethod
def _current_revision(cls, tenant_id):
db = get_db()
key = cls._revision_key(tenant_id)
row = db.execute(
'SELECT revision FROM cache_state WHERE key = ?', (key,)
).fetchone()
if row is None:
db.execute(
'INSERT OR IGNORE INTO cache_state (key, revision) VALUES (?, 0)',
(key,)
)
db.commit()
return 0
return int(row['revision'] or 0)
@classmethod
def _bump_revision(cls, tenant_id):
"""Erhöht die gemeinsame Revision und gibt den neuen Wert zurück."""
db = get_db()
key = cls._revision_key(tenant_id)
db.execute(
'INSERT OR IGNORE INTO cache_state (key, revision) VALUES (?, 0)',
(key,)
)
db.execute(
'UPDATE cache_state SET revision = revision + 1, '
'updated_at = CURRENT_TIMESTAMP WHERE key = ?',
(key,)
)
row = db.execute(
'SELECT revision FROM cache_state WHERE key = ?', (key,)
).fetchone()
db.commit()
return int(row['revision'] or 0)
@classmethod
def load_from_db(cls, tenant_id):
"""Lädt alle Gruppen eines Mandanten aus der Datenbank in den Cache"""
# Revision vor dem Lesen der Daten ermitteln. Schreibt ein anderer
# Worker währenddessen, bleibt die gespeicherte Revision älter als die
# gemeinsame Revision und der Cache wird beim nächsten Zugriff erneut
# geladen. Die umgekehrte Reihenfolge könnte dagegen veraltete Daten
# dauerhaft mit einer aktuellen Revision verknüpfen.
revision = cls._current_revision(tenant_id)
groups = GroupModel.get_all_by_tenant(tenant_id)
memberships = GroupModel.get_account_ids_by_group(tenant_id)
# Vollständig neu aufbauen, damit gelöschte Gruppen nicht im Cache
@@ -33,32 +84,47 @@ class GroupsService:
'created_at': group['created_at'],
'updated_at': group['updated_at']
}
cls._cache_revision[tenant_id] = revision
return cls._cache[tenant_id]
@classmethod
def get_all(cls, tenant_id, force_reload=False):
"""Gibt alle Gruppen für einen Mandanten zurück (aus Cache)"""
if force_reload or tenant_id not in cls._cache or not cls._cache[tenant_id]:
revision = cls._current_revision(tenant_id)
if (
force_reload
or tenant_id not in cls._cache
or not cls._cache[tenant_id]
or cls._cache_revision.get(tenant_id) != revision
):
cls.load_from_db(tenant_id)
return cls._cache.get(tenant_id, {})
@classmethod
def get_by_id(cls, tenant_id, group_id):
"""Gibt eine spezifische Gruppe aus dem Cache zurück"""
if tenant_id not in cls._cache or not cls._cache[tenant_id]:
revision = cls._current_revision(tenant_id)
if (
tenant_id not in cls._cache
or not cls._cache[tenant_id]
or cls._cache_revision.get(tenant_id) != revision
):
cls.load_from_db(tenant_id)
return cls._cache.get(tenant_id, {}).get(group_id)
@classmethod
def invalidate(cls, tenant_id):
"""Invalidiert den Cache für einen Mandanten (erzwingt Neuladen)"""
"""Invalidiert den Cache für einen Mandanten (erzwingt Neuladen)."""
if tenant_id in cls._cache:
cls._cache[tenant_id] = {}
cls._cache_revision.pop(tenant_id, None)
cls._bump_revision(tenant_id)
@classmethod
def invalidate_all(cls):
"""Invalidiert den gesamten Cache"""
"""Invalidiert den gesamten Cache."""
cls._cache = {}
cls._cache_revision = {}
@classmethod
def is_account_linked(cls, account_id, group_id, tenant_id):
@@ -87,14 +153,20 @@ class GroupsService:
@classmethod
def update_cache_entry(cls, tenant_id, group_id, data):
"""Aktualisiert einen Eintrag im Cache.
"""Aktualisiert einen Eintrag im Cache und invalidiert andere Worker.
Der Cache wird vor dem Aktualisieren vollständig geladen, damit ein
gezieltes Update (z. B. nach Code 200/300) keinen Teil-Cache erzeugt,
der anschließend beim Initialload unvollständige Gruppendaten liefert.
Anschließend wird die gemeinsame Revision erhöht, damit andere Worker
ihre lokalen Caches verwerfen. Der lokale Cache wird bewusst nicht auf
die neue Revision gesetzt: Beim nächsten Zugriff wird er neu geladen
und kann so keine Änderungen verpassen, die ein anderer Worker zwischen
dem Laden und dem Erhöhen der Revision geschrieben hat.
"""
if tenant_id not in cls._cache or not cls._cache[tenant_id]:
cls.load_from_db(tenant_id)
cls.get_all(tenant_id)
if group_id not in cls._cache[tenant_id]:
cls._cache[tenant_id][group_id] = {}
cls._cache[tenant_id][group_id].update(data)
cls._bump_revision(tenant_id)
cls._cache_revision.pop(tenant_id, None)
+223 -206
View File
@@ -23,14 +23,17 @@ Wichtige Regeln aus der Spezifikation:
Zeitfenster wieder zurück auf "unterwegs".
"""
import json
import os
import re
import socket
import time
import uuid
from datetime import datetime, timedelta, timezone
from threading import Lock
from threading import Event, Lock
from flask import current_app
from cmbnet.db import get_db
from cmbnet.services.groups_service import GroupsService
from cmbnet.ws import store
from cmbnet.ws.protocol import WSMessage
@@ -43,41 +46,35 @@ class WebSocketBroker:
# 'group_id': <verknüpfte Gruppe oder None>,
# }
# Eine Client-ID gehört genau zu einer Webview. Mehrere Clients
# desselben Accounts besitzen daher getrennte Einträge.
# desselben Accounts besitzen daher getrennte Einträge. Dieses Dict
# enthält bewusst nur die Verbindungen des aktuellen Worker-Prozesses.
self.connections = {}
# authenticated[tenant_id][client_id] = True
# Erst nach erfolgreichem Code-0-Handshake darf ein Client Nachrichten
# über die Verbindung senden.
# über die Verbindung senden. Auch dieser Status ist prozesslokal.
self.authenticated = {}
# Nicht zustellbare Nachrichten werden pro Client gepuffert.
# Schlüssel: (tenant_id, client_id).
self.client_queues = {}
# client_accounts[(tenant_id, client_id)] = account_id
# Bleibt auch nach einem Verbindungsabbruch erhalten, damit weitere
# Nachrichten für denselben Client gepuffert werden können.
self.client_accounts = {}
# account_clients[(tenant_id, account_id)] = {client_id, ...}
# Wird für die Empfängerermittlung benötigt: Ein Account kann mehrere
# Clients gleichzeitig betreiben.
self.account_clients = {}
# disconnected_clients[(tenant_id, client_id)] = monotonic Zeitpunkt.
# Dient dem Aufräumen dauerhaft verlassener Webviews.
self.disconnected_clients = {}
self.queue_lock = Lock()
# Gemeinsamer Zustand liegt in SQLite (siehe cmbnet/ws/store.py):
# ws_clients, ws_client_queue und ws_group_presence. Dadurch finden
# Reconnects auf einem anderen Worker ihre Queue und Sequenznummer.
self.worker_id = os.environ.get('CMBNET_WS_WORKER_ID') or ''
if not self.worker_id:
self.worker_id = f'{socket.gethostname()}:{os.getpid()}'
# Sequenznummern werden pro Client-ID vergeben und bleiben über einen
# WebSocket-Reconnect derselben Webview hinweg erhalten. Dadurch kann
# der Client nach einem Reconnect erkennen, ob ihm Frames fehlen.
# client_sequences[(tenant_id, client_id)] = zuletzt zugestellte Sequenz
# Sequenznummern werden pro Client-ID vergeben. Der lokale Cache wird
# beim Registrieren aus der Datenbank geladen; nach jedem erfolgreichen
# Versand wird die gemeinsame Zählung fortgeschrieben.
self.client_sequences = {}
# Ein Lock pro Client-ID serialisiert Sequenzvergabe und Sendevorgang
# auch dann, wenn die Verbindung während eines Reconnects ersetzt wird.
self.client_sequence_locks = {}
# Zeitpunkt des letzten Code-2-Pongs je Gruppe (monotonic).
self.group_last_pong = {}
self.group_online_since = {}
# Serialisiert das Ausliefern der gemeinsamen Queue pro Client, damit
# Authentifizierung und Polling-Schleife nicht parallel dieselben
# Aufträge versenden.
self.client_delivery_locks = {}
# Weckt die lokale Polling-Schleife nach einer neu eingestellten
# Nachricht. Workerübergreifend übernimmt das reguläre Polling.
self.delivery_wakeup = Event()
# ------------------------------------------------------------------
# Verbindungen und Authentifizierung
@@ -102,10 +99,15 @@ class WebSocketBroker:
# Eine Client-ID ist an den Account gebunden, der sie im Handshake
# verwendet hat. Ein Wechsel des Accounts unter derselben ID wäre ein
# Hinweis auf eine falsche bzw. manipulierte Zuordnung.
existing_account = self.client_accounts.get((tenant_id, client_id))
# Hinweis auf eine falsche bzw. manipulierte Zuordnung. Die Zuordnung
# liegt prozessübergreifend in ws_clients.
existing_account = store.get_client_account(tenant_id, client_id)
if existing_account is not None and existing_account != account_id:
return False
if not store.ensure_client(
tenant_id, client_id, account_id, worker_id=self.worker_id
):
return False
if role is None:
role = account['role']
@@ -123,6 +125,7 @@ class WebSocketBroker:
group_id = group['id'] if group else None
connections = self.connections.setdefault(tenant_id, {})
key = (tenant_id, client_id)
# Eine neue Verbindung mit derselben Client-ID ersetzt eine eventuell
# noch registrierte alte Verbindung (z. B. nach einem schnellen
@@ -148,9 +151,9 @@ class WebSocketBroker:
'connected_at': time.monotonic(),
'last_pong_at': None,
# Zuletzt an diese Client-ID zugestellte Sequenznummer. Die
# maßgebliche Zählung liegt in self.client_sequences, damit sie
# einen Reconnect überlebt.
'seq': self.client_sequences.get((tenant_id, client_id), 0),
# maßgebliche Zählung liegt in ws_clients und überlebt damit einen
# Worker-Wechsel.
'seq': store.get_last_seq(tenant_id, client_id),
# Ob diese Client-ID bereits vor diesem Handshake bekannt war.
# Nur dann bleibt ihre Queue auch bei einem fehlgeschlagenen
# erneuten Handshake erhalten.
@@ -163,9 +166,8 @@ class WebSocketBroker:
'send_lock': Lock()
}
self.client_accounts[(tenant_id, client_id)] = account_id
self.account_clients.setdefault((tenant_id, account_id), set()).add(client_id)
self.disconnected_clients.pop((tenant_id, client_id), None)
self.client_sequences[key] = store.get_last_seq(tenant_id, client_id)
self.client_delivery_locks.setdefault(key, Lock())
return True
def send_to_connection(self, tenant_id, client_id, data):
@@ -191,7 +193,7 @@ class WebSocketBroker:
last_seq = self.client_sequences.get(key)
if last_seq is None:
last_seq = int(conn.get('seq') or 0)
last_seq = store.get_last_seq(tenant_id, client_id)
next_seq = last_seq + 1
payload['seq'] = next_seq
framed = json.dumps(payload, ensure_ascii=False)
@@ -205,6 +207,12 @@ class WebSocketBroker:
self.client_sequences[key] = next_seq
conn['seq'] = next_seq
# Die Sequenz wird erst nach erfolgreichem Senden persistiert,
# damit ein fehlgeschlagener Versand keine Lücke erzeugt.
store.set_last_seq(
tenant_id, client_id, next_seq,
account_id=conn.get('account_id')
)
return True
except Exception:
# Eine fehlerhafte Verbindung darf den Versand an andere Clients
@@ -216,6 +224,10 @@ class WebSocketBroker:
"""Prüft, ob ein Client den Code-0-Handshake erfolgreich absolviert hat."""
return self.authenticated.get(tenant_id, {}).get(client_id, False)
def describe_connections(self, tenant_id):
"""Liefert alle verbundenen Clients des Mandanten aus der gemeinsamen DB."""
return store.describe_connections(tenant_id)
def authenticate(self, tenant_id, account_id, client_id, token):
"""Authentifiziert eine Client-Verbindung anhand des Einmal-Tokens (Code 0).
@@ -257,13 +269,15 @@ class WebSocketBroker:
if conn.get('role') == 'Gruppe' and conn.get('group_id'):
# Ein frisch verbundener Gruppen-Client erhält eine
# Zwei-Minuten-Kulanz, bis der erste Code-2-Pong eintrifft.
key = (tenant_id, conn['group_id'])
self.group_online_since[key] = time.monotonic()
store.set_group_online_since(tenant_id, conn['group_id'])
self.authenticated.setdefault(tenant_id, {})[client_id] = True
self.client_accounts[(tenant_id, client_id)] = account_id
self.account_clients.setdefault((tenant_id, account_id), set()).add(client_id)
self.disconnected_clients.pop((tenant_id, client_id), None)
store.mark_authenticated(
tenant_id, client_id, True, worker_id=self.worker_id
)
self.client_sequences[(tenant_id, client_id)] = store.get_last_seq(
tenant_id, client_id
)
# Zuerst die für diesen Client gepufferten Nachrichten ausliefern.
# Wurde die Queue wegen Überschreitung der Maximalzeit verworfen, wird
@@ -313,23 +327,26 @@ class WebSocketBroker:
if not authenticated:
self.authenticated.pop(tenant_id, None)
key = (tenant_id, client_id)
self.client_sequences.pop(key, None)
self.client_sequence_locks.pop(key, None)
if not was_authenticated and not was_known_client:
# Ein nie erfolgreich authentifizierter neuer Client hinterlässt
# keine Zuordnung, Queue oder Empfängerregistrierung.
account_id = self.client_accounts.pop((tenant_id, client_id), None)
self.client_queues.pop((tenant_id, client_id), None)
self.disconnected_clients.pop((tenant_id, client_id), None)
self.client_sequences.pop((tenant_id, client_id), None)
self.client_sequence_locks.pop((tenant_id, client_id), None)
if account_id is not None:
clients = self.account_clients.get((tenant_id, account_id))
if clients is not None:
clients.discard(client_id)
if not clients:
self.account_clients.pop((tenant_id, account_id), None)
store.delete_client(
tenant_id, client_id, worker_id=self.worker_id
)
self.client_delivery_locks.pop(key, None)
return
self.disconnected_clients[(tenant_id, client_id)] = time.monotonic()
# Die Client-ID bleibt samt Queue bekannt. Ein Reconnect kann auf
# einem beliebigen Worker landen und findet den Zustand dort wieder.
# Das Delivery-Lock bleibt bestehen, damit eine laufende Zustellung
# nicht mit einer neuen Verbindung derselben Client-ID kollidiert.
store.mark_disconnected(
tenant_id, client_id, worker_id=self.worker_id
)
def _get_connection(self, tenant_id, client_id):
return self.connections.get(tenant_id, {}).get(client_id)
@@ -369,7 +386,8 @@ class WebSocketBroker:
recipient_rows = []
for recipient_id in sorted(set(recipients or [])):
account_id = self.client_accounts.get((tenant_id, recipient_id))
client_row = store.get_client(tenant_id, recipient_id)
account_id = client_row['account_id'] if client_row else None
account = None
if account_id is not None:
account = db.execute(
@@ -388,8 +406,12 @@ class WebSocketBroker:
info = self._get_sender_info(tenant_id, account)
info['client_id'] = recipient_id
info['connected'] = bool(self._get_connection(tenant_id, recipient_id))
info['authenticated'] = self.is_authenticated(tenant_id, recipient_id)
info['connected'] = bool(
client_row and client_row['disconnected_at'] is None
)
info['authenticated'] = bool(
client_row and client_row['authenticated']
)
recipient_rows.append(info)
payload = message.msg
@@ -454,95 +476,62 @@ class WebSocketBroker:
minutes = 60
return max(self._client_queue_max_age_seconds(), minutes * 60)
def _ensure_client_queue(self, tenant_id, client_id, now=None):
"""Liefert die Queue eines Clients und legt sie bei Bedarf an."""
key = (tenant_id, client_id)
queue = self.client_queues.get(key)
if queue is None:
queue = {
'messages': [],
'created_at': now if now is not None else time.monotonic(),
'expired': False,
'code99_only': False,
'code99_message': None,
'account_id': self.client_accounts.get(key),
}
self.client_queues[key] = queue
return queue
def _expire_client_queue(self, queue, now=None):
"""Verwirft zu alte Nachrichten und hinterlässt einen Code-99-Hinweis."""
if not queue or queue.get('code99_only') or queue.get('expired'):
return
now = now if now is not None else time.monotonic()
if now - queue.get('created_at', now) < self._client_queue_max_age_seconds():
return
queue['messages'].clear()
queue['expired'] = True
def _ephemeral_ttl_seconds(self):
try:
return max(1.0, float(current_app.config.get(
'WS_EPHEMERAL_TTL_SECONDS', 30
)))
except (TypeError, ValueError):
return 30.0
def _queue_undeliverable(self, tenant_id, client_id, message):
"""Puffert eine nicht zustellbare Nachricht für einen Client."""
if message.code < 100 and message.code != 99:
return
"""Puffert eine nicht zustellbare Nachricht für einen Client.
if (tenant_id, client_id) not in self.client_accounts:
return
Bei Code 2 handelt es sich um ein kurzlebiges Lebenszeichen. Es wird
nur für aktuell verbundene Clients gepuffert, damit ein späterer
Reconnect kein veraltetes Pong erhält.
"""
if message.code == 2:
if not store.client_is_connected(tenant_id, client_id):
return False
elif message.code < 100 and message.code != 99:
return False
with self.queue_lock:
queue = self._ensure_client_queue(tenant_id, client_id)
now = time.monotonic()
if not store.client_exists(tenant_id, client_id):
return False
if message.code == 99:
# Eine nicht zustellbare Reload-Aufforderung verdrängt alle
# älteren Nachrichten. Danach wird nichts weiter gepuffert.
queue['messages'].clear()
queue['code99_only'] = True
queue['code99_message'] = message.to_json()
queue['expired'] = False
return
self._expire_client_queue(queue, now)
if queue.get('expired') or queue.get('code99_only'):
return
queue['messages'].append(message.to_json())
queued = store.enqueue_message(
tenant_id,
client_id,
message.code,
message.to_json(),
self._client_queue_max_age_seconds(),
timeout_payload=self._client_queue_timeout_message(),
ephemeral_seconds=(
self._ephemeral_ttl_seconds() if message.code == 2 else None
)
)
if queued:
self.delivery_wakeup.set()
return queued
def cleanup_client_queues(self):
"""Räumt abgelaufene Client-Queues und verwaiste Webviews auf."""
now = time.monotonic()
retention = self._client_retention_seconds()
with self.queue_lock:
for queue in self.client_queues.values():
self._expire_client_queue(queue, now)
"""Räumt abgelaufene Queues und verwaiste Clients in der DB auf."""
store.purge_expired_queue_rows()
store.expire_queues(
self._client_queue_max_age_seconds(),
self._client_queue_timeout_message()
)
store.cleanup_clients(self._client_retention_seconds())
for key, disconnected_at in list(self.disconnected_clients.items()):
tenant_id, client_id = key
if self._get_connection(tenant_id, client_id):
self.disconnected_clients.pop(key, None)
continue
if now - disconnected_at < retention:
continue
queue = self.client_queues.get(key)
# Solange noch zustellbare Nachrichten warten, bleibt der
# Client registriert. Danach darf die verwaiste Webview
# inklusive Code-99-Tombstone verworfen werden.
if queue and not queue.get('expired') and not queue.get('code99_only'):
continue
account_id = self.client_accounts.pop(key, None)
self.client_queues.pop(key, None)
self.disconnected_clients.pop(key, None)
# Lokale Caches für inzwischen entfernte Clients bereinigen.
for key in list(self.client_sequences):
if not store.client_exists(*key):
self.client_sequences.pop(key, None)
self.client_sequence_locks.pop(key, None)
if account_id is not None:
clients = self.account_clients.get((tenant_id, account_id))
if clients is not None:
clients.discard(client_id)
if not clients:
self.account_clients.pop((tenant_id, account_id), None)
for key in list(self.client_delivery_locks):
if not store.client_exists(*key):
self.client_delivery_locks.pop(key, None)
def _client_queue_timeout_message(self):
minutes = current_app.config.get('WS_QUEUE_MAX_AGE_MINUTES', 15)
@@ -556,8 +545,13 @@ class WebSocketBroker:
)
).to_json()
def _client_delivery_lock(self, tenant_id, client_id):
return self.client_delivery_locks.setdefault(
(tenant_id, client_id), Lock()
)
def restore_client_queue(self, tenant_id, client_id):
"""Liefert gepufferte Nachrichten eines wiedererkannten Clients aus.
"""Liefert persistierte Nachrichten eines wiedererkannten Clients aus.
Rückgabe: (Menge der Roh-Nachrichten aus der Queue, Late-Entry-Sperre).
Die Menge dient dazu, dieselben Nachrichten nicht zusätzlich als
@@ -565,57 +559,66 @@ class WebSocketBroker:
war oder nur noch eine Code-99-Nachricht enthielt. In diesem Fall darf
keine zusätzliche Late-Entry-Historie mehr gesendet werden.
"""
key = (tenant_id, client_id)
now = time.monotonic()
with self.queue_lock:
queue = self.client_queues.get(key)
if not queue:
with self._client_delivery_lock(tenant_id, client_id):
rows = store.fetch_queue(tenant_id, client_id)
if not rows:
return set(), False
self._expire_client_queue(queue, now)
if queue.get('code99_only'):
raw_message = queue.get('code99_message') or self._client_queue_timeout_message()
self.client_queues.pop(key, None)
send_only = True
messages = []
elif queue.get('expired'):
raw_message = self._client_queue_timeout_message()
self.client_queues.pop(key, None)
send_only = True
messages = []
started_at = store.get_queue_started_at(tenant_id, client_id)
max_age = self._client_queue_max_age_seconds()
if started_at is not None and store.now() - started_at >= max_age:
store.replace_queue_with_timeout(
tenant_id, client_id, self._client_queue_timeout_message()
)
rows = store.fetch_queue(tenant_id, client_id)
suppress_late_entries = True
else:
raw_message = None
send_only = False
messages = list(queue.get('messages', []))
queue['messages'] = []
suppress_late_entries = any(
row['code99_only'] for row in rows
)
if send_only:
if raw_message and not self.send_to_connection(tenant_id, client_id, raw_message):
# Verbindung ist bereits wieder weg: Queue für den nächsten
# Versuch erhalten.
with self.queue_lock:
self.client_queues.setdefault(key, queue)
return set(), True
unsent = []
for index, raw_message in enumerate(messages):
raw_messages = set()
for row in rows:
raw_message = row['payload']
if not self.send_to_connection(tenant_id, client_id, raw_message):
unsent = messages[index:]
# Verbindung ist bereits wieder weg. Noch nicht
# zugestellte Aufträge bleiben in der Queue.
break
if not row['code99_only']:
raw_messages.add(raw_message)
store.delete_queue_row(row['id'])
with self.queue_lock:
current = self.client_queues.get(key)
if current is not None:
if unsent:
current['messages'] = unsent + current.get('messages', [])
if not current.get('messages'):
self.client_queues.pop(key, None)
return raw_messages, suppress_late_entries
# Auch nicht zugestellte Queue-Nachrichten von den Late Entries
# ausnehmen. Sie bleiben in der Queue und werden beim nächsten
# Reconnect erneut versucht, statt doppelt gepuffert zu werden.
return set(messages), False
def drain_client_queue(self, tenant_id, client_id):
"""Stellt die gemeinsame Queue eines lokal verbundenen Clients zu."""
self.restore_client_queue(tenant_id, client_id)
def drain_local_clients(self):
"""Zustellrunde für alle lokal verbundenen, authentifizierten Clients."""
local_clients = set()
for tenant_id, connections in list(self.connections.items()):
for client_id in list(connections):
if self.is_authenticated(tenant_id, client_id):
local_clients.add((tenant_id, client_id))
if not local_clients:
return
# Nur Clients mit tatsächlich wartenden Aufträgen öffnen eine
# Transaktion. Das hält die Polling-Schleife bei vielen verbundenen
# Clients günstig.
for tenant_id, client_id in store.clients_with_queue(local_clients):
try:
self.drain_client_queue(tenant_id, client_id)
except Exception as exc:
try:
current_app.logger.warning(
'WS-Queue-Zustellung fehlgeschlagen: tenant=%s client=%s error=%s',
tenant_id, client_id, exc
)
except Exception:
pass
# ------------------------------------------------------------------
# Late Entry
@@ -881,7 +884,7 @@ class WebSocketBroker:
"""Wertet ein Code-2-Lebenszeichen eines Clients aus."""
conn = self._get_connection(tenant_id, client_id) if client_id else None
if conn and conn.get('account_id') == account_id:
conn['last_pong_at'] = time.monotonic()
conn['last_pong_at'] = time.time()
if not sender or sender['role'] != 'Gruppe':
return
@@ -897,9 +900,8 @@ class WebSocketBroker:
if not group:
return
now = time.monotonic()
group_id = group['id']
self.group_last_pong[(tenant_id, group_id)] = now
store.record_group_pong(tenant_id, group_id)
if group['state'] == 'unterwegs':
self._set_group_state_internal(
@@ -917,11 +919,16 @@ class WebSocketBroker:
return False
old_state = group['state']
db.execute(
# Der Vergleich im UPDATE verhindert, dass zwei Worker denselben
# automatischen Statuswechsel gleichzeitig in die Historie schreiben.
cursor = db.execute(
'UPDATE groups SET state = ?, updated_at = CURRENT_TIMESTAMP '
'WHERE id = ? AND tenant_id = ?',
(new_state, group_id, tenant_id)
'WHERE id = ? AND tenant_id = ? AND state = ?',
(new_state, group_id, tenant_id, old_state)
)
if cursor.rowcount == 0:
db.rollback()
return False
db.execute(
'''INSERT INTO group_state_history
(tenant_id, group_id, from_state, to_state, last_lat, last_lon,
@@ -937,7 +944,7 @@ class WebSocketBroker:
)
if new_state == 'online':
self.group_online_since[(tenant_id, group_id)] = time.monotonic()
store.set_group_online_since(tenant_id, group_id)
message = WSMessage(
sender_id=actor_account_id or 0,
@@ -972,20 +979,24 @@ class WebSocketBroker:
except (TypeError, ValueError):
timeout = 120.0
now = time.monotonic()
current = store.now()
for row in rows:
key = (row['tenant_id'], row['id'])
reference = self.group_last_pong.get(key)
online_since = self.group_online_since.get(key)
presence = store.get_group_presence(row['tenant_id'], row['id'])
last_pong = presence['last_pong_at'] if presence else None
online_since = presence['online_since'] if presence else None
reference = last_pong
if online_since is not None:
reference = max(reference, online_since) if reference else online_since
reference = (
max(reference, online_since)
if reference is not None else online_since
)
if reference is None:
# Zustand war bereits vor dem Start des Trackings "online".
# Ab jetzt läuft die Kulanzfrist.
self.group_online_since[key] = now
store.set_group_online_since(row['tenant_id'], row['id'], current)
continue
if now - reference > timeout:
if current - reference > timeout:
self._set_group_state_internal(
row['tenant_id'], row['id'], 'unterwegs'
)
@@ -1158,7 +1169,7 @@ class WebSocketBroker:
db.commit()
GroupsService.update_cache_entry(tenant_id, group_id, {'state': new_state})
if new_state == 'online':
self.group_online_since[(tenant_id, group_id)] = time.monotonic()
store.set_group_online_since(tenant_id, group_id)
self._log_business(tenant_id, sender['id'], 'group.state_change', 'group',
group_id, {'from': group['state'], 'to': new_state})
@@ -1402,20 +1413,27 @@ class WebSocketBroker:
return message
def _deliver(self, tenant_id, message, sender):
"""Stellt eine Nachricht an alle berechtigten Clients zu."""
"""Stellt eine Nachricht an alle berechtigten Clients zu.
Lokal verbundene Clients erhalten den Frame direkt. Für alle anderen
Clients wird ein persistenter Auftrag in der gemeinsamen Queue
angelegt. Jeder Worker pollt diese Queue für seine eigenen Clients.
"""
recipients = sorted(self._get_recipients(tenant_id, message, sender))
self.log_incoming(tenant_id, message, sender, recipients=recipients)
for client_id in recipients:
self._send(tenant_id, client_id, message)
self.delivery_wakeup.set()
def _send(self, tenant_id, client_id, message):
"""Sendet eine Nachricht an einen Client oder puffert sie für ihn."""
# Erst nach erfolgreicher Token-Authentifizierung dürfen Nachrichten
# an einen Client zugestellt werden.
if not self.is_authenticated(tenant_id, client_id):
self._queue_undeliverable(tenant_id, client_id, message)
return False
conn = self._get_connection(tenant_id, client_id)
authenticated = self.is_authenticated(tenant_id, client_id)
# Ein lokal verbundener Client ohne wartende Queue wird direkt
# bedient. Existiert bereits eine Queue, wird auch diese Nachricht
# eingereiht, damit die Reihenfolge erhalten bleibt.
if conn and authenticated and not store.client_has_queue(tenant_id, client_id):
if self.send_to_connection(tenant_id, client_id, message.to_json()):
return True
@@ -1423,13 +1441,12 @@ class WebSocketBroker:
return False
def _client_ids_for_accounts(self, tenant_id, account_ids):
"""Expandiert Empfänger-Accounts auf alle bekannten Client-IDs."""
client_ids = set()
for account_id in account_ids:
client_ids.update(
self.account_clients.get((tenant_id, account_id), ())
)
return client_ids
"""Expandiert Empfänger-Accounts auf alle bekannten Client-IDs.
Die Zuordnung liegt in ws_clients und umfasst damit auch Clients, die
an anderen Workern verbunden oder momentan getrennt sind.
"""
return store.client_ids_for_accounts(tenant_id, account_ids)
def _get_recipients(self, tenant_id, message, sender):
"""Bestimmt den Empfängerkreis abhängig vom Nachrichtencode.
+75
View File
@@ -0,0 +1,75 @@
"""Worker-lokale Zustellschleife für die gemeinsame WebSocket-Queue.
Jeder WSGI-Worker besitzt eigene WebSocket-Objekte. Die persistente Queue in
``ws_client_queue`` ist dagegen gemeinsam. Diese Schleife prüft regelmäßig, ob
für die lokal verbundenen Clients Aufträge eingegangen sind, und stellt sie
über den lokalen Broker zu.
"""
import threading
from cmbnet.ws import broker
class DeliveryWorker:
def __init__(self, interval=0.5):
self.interval = interval
self.app = None
self.running = False
self._thread = None
self._stop = threading.Event()
def start(self, app=None, interval=None):
if app is not None:
self.app = app
if interval is not None:
self.interval = interval
if self.running:
return
if self.app is None:
return
self.running = True
self._stop.clear()
self._thread = threading.Thread(
target=self._run,
name='cmbnet-ws-delivery',
daemon=True
)
self._thread.start()
def stop(self):
self.running = False
self._stop.set()
broker.delivery_wakeup.set()
# Der Thread ist ein Daemon. Ein Join mit Timeout verhindert, dass
# ein laufender Datenbankzugriff den Shutdown blockiert.
if self._thread is not None:
self._thread.join(timeout=2.0)
self._thread = None
def wake(self):
broker.delivery_wakeup.set()
def _run(self):
# Ein App-Kontext für die gesamte Lebensdauer der Schleife hält die
# SQLite-Verbindung dieses Threads offen. Bei einem Polling-Intervall
# von 0,5 s wäre ein Verbindungsaufbau pro Runde unnötig teuer.
with self.app.app_context():
while not self._stop.is_set() and self.running:
try:
broker.drain_local_clients()
except Exception as exc:
try:
self.app.logger.warning(
'WS-Zustellschleife fehlgeschlagen: %s', exc
)
except Exception:
pass
# Neue lokale Nachrichten wecken die Schleife sofort. Für
# Nachrichten aus anderen Workern greift der reguläre Timeout.
broker.delivery_wakeup.wait(self.interval)
broker.delivery_wakeup.clear()
delivery_worker = DeliveryWorker()
+13 -6
View File
@@ -69,17 +69,24 @@ class HeartbeatManager:
msg = WSMessage(sender_id=0, code=1, msg='ping')
# Nur authentifizierte Verbindungen erhalten einen Heartbeat.
if self.app is not None:
try:
# Auch der Versand braucht einen App-Kontext: Die
# Sequenznummern liegen inzwischen in der gemeinsamen
# SQLite-Datenbank und werden beim Senden fortgeschrieben.
with self.app.app_context():
# Nur authentifizierte Verbindungen erhalten einen
# Heartbeat.
for tenant_id, connections in list(broker.connections.items()):
for client_id in list(connections):
if not broker.is_authenticated(tenant_id, client_id):
continue
broker.send_to_connection(tenant_id, client_id, msg.to_json())
broker.send_to_connection(
tenant_id, client_id, msg.to_json()
)
# Abgelaufene persistierte Nachrichten und Client-Queues löschen.
if self.app is not None:
try:
with self.app.app_context():
# Abgelaufene persistierte Nachrichten und Client-Queues
# löschen.
broker.cleanup_client_queues()
broker.cleanup_old_messages()
except Exception as exc:
+535
View File
@@ -0,0 +1,535 @@
"""Prozessübergreifender Zustand des WebSocket-Brokers.
Der Broker hält weiterhin nur die WebSocket-Objekte im eigenen Prozess.
Alles, was ein Reconnect auf einem anderen WSGI-Worker wiederfinden muss,
liegt in SQLite:
- ``ws_clients``: bekannte Client-IDs, Account, letzte Sequenznummer und
Verbindungsstatus,
- ``ws_client_queue``: persistente Zustellaufträge pro Client,
- ``ws_group_presence``: gemeinsame Pong-Zeitpunkte der Gruppen.
Die Tabellen werden über ``ensure_schema()`` angelegt. Die Funktionen hier
erwarten einen aktiven Flask-App-Kontext, weil sie ``get_db()`` verwenden.
"""
import time
from cmbnet.db import get_db
# Kleine Hilfsfunktion, damit alle Zeitstempel dieselbe Basis haben.
def now():
return time.time()
# ----------------------------------------------------------------------
# Clients
# ----------------------------------------------------------------------
def get_client(tenant_id, client_id):
"""Liefert die Zeile eines bekannten Clients oder ``None``."""
return get_db().execute(
'SELECT * FROM ws_clients WHERE tenant_id = ? AND client_id = ?',
(tenant_id, client_id)
).fetchone()
def get_client_account(tenant_id, client_id):
"""Liefert die Account-ID, die zu einer Client-ID gehört."""
row = get_client(tenant_id, client_id)
return row['account_id'] if row else None
def client_exists(tenant_id, client_id):
return get_client(tenant_id, client_id) is not None
def client_is_connected(tenant_id, client_id):
row = get_client(tenant_id, client_id)
return bool(row and row['disconnected_at'] is None)
def ensure_client(tenant_id, client_id, account_id, worker_id=None):
"""Registriert eine Client-ID bzw. aktualisiert ihren Verbindungsstatus.
Gibt ``False`` zurück, wenn die Client-ID bereits einem anderen Account
gehört. Ein solcher Wechsel wäre ein Hinweis auf eine manipulierte
Zuordnung und wird vom Broker abgelehnt.
"""
db = get_db()
row = get_client(tenant_id, client_id)
current = now()
if row is not None:
if row['account_id'] != account_id:
return False
db.execute(
'UPDATE ws_clients SET worker_id = ?, connected_at = ?, '
'disconnected_at = NULL, authenticated = 0 '
'WHERE tenant_id = ? AND client_id = ?',
(worker_id, current, tenant_id, client_id)
)
db.commit()
return True
db.execute(
'INSERT INTO ws_clients '
'(tenant_id, client_id, account_id, worker_id, connected_at, '
' authenticated, last_seq) '
'VALUES (?, ?, ?, ?, ?, 0, 0)',
(tenant_id, client_id, account_id, worker_id, current)
)
db.commit()
return True
def mark_authenticated(tenant_id, client_id, authenticated=True, worker_id=None):
db = get_db()
if worker_id is None:
db.execute(
'UPDATE ws_clients SET authenticated = ? '
'WHERE tenant_id = ? AND client_id = ?',
(1 if authenticated else 0, tenant_id, client_id)
)
else:
# Nur der Worker, dem die Client-ID aktuell zugeordnet ist, darf den
# Authentifizierungsstatus setzen. So überschreibt ein verspäteter
# Handshake eines alten Workers keinen Reconnect auf einem anderen
# Worker.
db.execute(
'UPDATE ws_clients SET authenticated = ? '
'WHERE tenant_id = ? AND client_id = ? '
'AND (worker_id IS NULL OR worker_id = ?)',
(1 if authenticated else 0, tenant_id, client_id, worker_id)
)
db.commit()
def mark_disconnected(tenant_id, client_id, worker_id=None):
"""Markiert eine Client-ID als getrennt, ohne ihre Queue zu löschen.
Mit ``worker_id`` wird nur die Zuordnung dieses Workers getrennt. Hat
inzwischen ein anderer Worker dieselbe Client-ID übernommen, bleibt dessen
Verbindungsstatus unberührt.
"""
db = get_db()
if worker_id is None:
db.execute(
'UPDATE ws_clients SET worker_id = NULL, disconnected_at = ?, '
'authenticated = 0 WHERE tenant_id = ? AND client_id = ?',
(now(), tenant_id, client_id)
)
else:
db.execute(
'UPDATE ws_clients SET worker_id = NULL, disconnected_at = ?, '
'authenticated = 0 WHERE tenant_id = ? AND client_id = ? '
'AND (worker_id IS NULL OR worker_id = ?)',
(now(), tenant_id, client_id, worker_id)
)
db.commit()
def delete_client(tenant_id, client_id, worker_id=None):
"""Entfernt eine Client-ID samt Queue und Sequenzzustand.
Mit ``worker_id`` wird nur gelöscht, solange die Client-ID noch diesem
Worker gehört. Das verhindert, dass ein scheidender Worker einen
zwischenzeitlichen Reconnect auf einem anderen Worker entfernt.
"""
db = get_db()
if worker_id is None:
cursor = db.execute(
'DELETE FROM ws_clients WHERE tenant_id = ? AND client_id = ?',
(tenant_id, client_id)
)
else:
cursor = db.execute(
'DELETE FROM ws_clients WHERE tenant_id = ? AND client_id = ? '
'AND (worker_id IS NULL OR worker_id = ?)',
(tenant_id, client_id, worker_id)
)
if cursor.rowcount:
db.execute(
'DELETE FROM ws_client_queue WHERE tenant_id = ? AND client_id = ?',
(tenant_id, client_id)
)
db.commit()
def get_last_seq(tenant_id, client_id):
row = get_client(tenant_id, client_id)
return int(row['last_seq'] or 0) if row else 0
def set_last_seq(tenant_id, client_id, seq, account_id=None):
db = get_db()
cursor = db.execute(
'UPDATE ws_clients SET last_seq = ? WHERE tenant_id = ? AND client_id = ?',
(seq, tenant_id, client_id)
)
if cursor.rowcount:
db.commit()
return
# Die Client-Zeile kann durch einen Cleanup verschwunden sein. In diesem
# Fall wird sie mit der bekannten Account-ID neu angelegt, damit der
# Sequenzstand nicht verloren geht.
if account_id is not None:
db.execute(
'INSERT OR IGNORE INTO ws_clients '
'(tenant_id, client_id, account_id, last_seq) VALUES (?, ?, ?, ?)',
(tenant_id, client_id, account_id, seq)
)
db.commit()
def client_ids_for_accounts(tenant_id, account_ids):
"""Expandiert Empfänger-Accounts auf alle bekannten Client-IDs.
Anders als früher werden auch Clients berücksichtigt, die an einem
anderen Worker verbunden oder momentan getrennt sind. Nur so können
Nachrichten für einen Reconnect auf einem beliebigen Worker gepuffert
werden.
"""
account_ids = list(dict.fromkeys(account_ids))
if not account_ids:
return set()
db = get_db()
result = set()
chunk_size = 400
for start in range(0, len(account_ids), chunk_size):
chunk = account_ids[start:start + chunk_size]
placeholders = ','.join('?' for _ in chunk)
rows = db.execute(
f'SELECT client_id FROM ws_clients '
f'WHERE tenant_id = ? AND account_id IN ({placeholders})',
(tenant_id, *chunk)
).fetchall()
result.update(row['client_id'] for row in rows)
return result
def describe_connections(tenant_id):
"""Liefert alle aktuell verbundenen Clients inklusive Account und Gruppe."""
rows = get_db().execute(
'''SELECT c.client_id, c.account_id, c.authenticated,
a.name AS account_name, a.role,
g.id AS group_id, g.aliasname AS group_alias
FROM ws_clients c
JOIN accounts a
ON a.id = c.account_id AND a.tenant_id = c.tenant_id
LEFT JOIN group_accounts ga
ON ga.tenant_id = c.tenant_id AND ga.account_id = c.account_id
LEFT JOIN groups g
ON g.id = ga.group_id AND g.tenant_id = c.tenant_id
WHERE c.tenant_id = ? AND c.disconnected_at IS NULL
ORDER BY c.client_id''',
(tenant_id,)
).fetchall()
return [dict(row) for row in rows]
# ----------------------------------------------------------------------
# Client-Queues
# ----------------------------------------------------------------------
def get_queue_started_at(tenant_id, client_id):
row = get_client(tenant_id, client_id)
return row['queue_started_at'] if row else None
def _set_queue_started_at(db, tenant_id, client_id, started_at):
db.execute(
'UPDATE ws_clients SET queue_started_at = ? '
'WHERE tenant_id = ? AND client_id = ?',
(started_at, tenant_id, client_id)
)
def client_has_queue(tenant_id, client_id):
"""Prüft, ob für einen Client noch zustellbare Aufträge warten."""
row = get_db().execute(
'SELECT 1 FROM ws_client_queue '
'WHERE tenant_id = ? AND client_id = ? '
'AND (expires_at IS NULL OR expires_at > ?) LIMIT 1',
(tenant_id, client_id, now())
).fetchone()
return row is not None
def enqueue_message(tenant_id, client_id, code, payload, max_age_seconds,
timeout_payload=None, ephemeral_seconds=None):
"""Legt einen Zustellauftrag für einen Client an.
``max_age_seconds`` steuert die Lebensdauer einer normalen Queue.
``timeout_payload`` wird als Code-99-Tombstone eingesetzt, wenn die Queue
zu alt ist oder eine Code-99-Nachricht alle älteren Aufträge verdrängt.
``ephemeral_seconds`` gilt für Code 2: Der Auftrag verfällt schnell und
wird nicht für getrennte Clients vorgehalten.
"""
db = get_db()
current = now()
row = db.execute(
'SELECT queue_started_at FROM ws_clients '
'WHERE tenant_id = ? AND client_id = ?',
(tenant_id, client_id)
).fetchone()
if row is None:
# Unbekannte Client-IDs werden nicht gepuffert. Der Broker legt die
# Zeile beim Code-0-Handshake an.
return False
started_at = row['queue_started_at']
if started_at is None:
started_at = current
# Eine Code-99-Nachricht verdrängt alle älteren Aufträge und blockiert
# weitere Nachrichten, bis sie zugestellt wurde.
if code != 99:
tombstone = db.execute(
'SELECT 1 FROM ws_client_queue '
'WHERE tenant_id = ? AND client_id = ? AND code99_only = 1 LIMIT 1',
(tenant_id, client_id)
).fetchone()
if tombstone:
return False
# Abgelaufene Queue: Inhalt verwerfen und einen Code-99-Hinweis hinterlassen.
if current - started_at >= max_age_seconds:
db.execute(
'DELETE FROM ws_client_queue WHERE tenant_id = ? AND client_id = ?',
(tenant_id, client_id)
)
if timeout_payload is not None:
db.execute(
'INSERT INTO ws_client_queue '
'(tenant_id, client_id, code, payload, code99_only, created_at) '
'VALUES (?, ?, 99, ?, 1, ?)',
(tenant_id, client_id, timeout_payload, current)
)
_set_queue_started_at(db, tenant_id, client_id, current)
else:
_set_queue_started_at(db, tenant_id, client_id, None)
db.commit()
return True
if code == 99:
db.execute(
'DELETE FROM ws_client_queue WHERE tenant_id = ? AND client_id = ?',
(tenant_id, client_id)
)
db.execute(
'INSERT INTO ws_client_queue '
'(tenant_id, client_id, code, payload, code99_only, created_at) '
'VALUES (?, ?, 99, ?, 1, ?)',
(tenant_id, client_id, payload, current)
)
_set_queue_started_at(db, tenant_id, client_id, current)
db.commit()
return True
expires_at = None
if ephemeral_seconds is not None:
expires_at = current + ephemeral_seconds
db.execute(
'INSERT INTO ws_client_queue '
'(tenant_id, client_id, code, payload, code99_only, created_at, expires_at) '
'VALUES (?, ?, ?, ?, 0, ?, ?)',
(tenant_id, client_id, code, payload, current, expires_at)
)
_set_queue_started_at(db, tenant_id, client_id, started_at)
db.commit()
return True
def fetch_queue(tenant_id, client_id):
"""Liefert alle noch gültigen Aufträge eines Clients in Reihenfolge."""
return get_db().execute(
'SELECT * FROM ws_client_queue '
'WHERE tenant_id = ? AND client_id = ? '
'AND (expires_at IS NULL OR expires_at > ?) '
'ORDER BY id ASC',
(tenant_id, client_id, now())
).fetchall()
def clients_with_queue(pairs):
"""Liefert diejenigen ``(tenant_id, client_id)``, die Aufträge haben."""
if not pairs:
return set()
db = get_db()
by_tenant = {}
for tenant_id, client_id in pairs:
by_tenant.setdefault(tenant_id, set()).add(client_id)
result = set()
chunk_size = 400
for tenant_id, client_ids in by_tenant.items():
ids = list(client_ids)
for start in range(0, len(ids), chunk_size):
chunk = ids[start:start + chunk_size]
placeholders = ','.join('?' for _ in chunk)
rows = db.execute(
f'SELECT DISTINCT client_id FROM ws_client_queue '
f'WHERE tenant_id = ? AND client_id IN ({placeholders}) '
f'AND (expires_at IS NULL OR expires_at > ?)',
(tenant_id, *chunk, now())
).fetchall()
result.update((tenant_id, row['client_id']) for row in rows)
return result
def delete_queue_row(row_id):
"""Löscht einen zugestellten Auftrag und räumt den Queue-Start auf."""
db = get_db()
row = db.execute(
'SELECT tenant_id, client_id FROM ws_client_queue WHERE id = ?',
(row_id,)
).fetchone()
if row is None:
return
db.execute('DELETE FROM ws_client_queue WHERE id = ?', (row_id,))
remaining = db.execute(
'SELECT 1 FROM ws_client_queue '
'WHERE tenant_id = ? AND client_id = ? '
'AND (expires_at IS NULL OR expires_at > ?) LIMIT 1',
(row['tenant_id'], row['client_id'], now())
).fetchone()
if remaining is None:
_set_queue_started_at(db, row['tenant_id'], row['client_id'], None)
db.commit()
def replace_queue_with_timeout(tenant_id, client_id, payload):
"""Ersetzt eine abgelaufene Queue durch einen Code-99-Hinweis."""
db = get_db()
current = now()
db.execute(
'DELETE FROM ws_client_queue WHERE tenant_id = ? AND client_id = ?',
(tenant_id, client_id)
)
db.execute(
'INSERT INTO ws_client_queue '
'(tenant_id, client_id, code, payload, code99_only, created_at) '
'VALUES (?, ?, 99, ?, 1, ?)',
(tenant_id, client_id, payload, current)
)
_set_queue_started_at(db, tenant_id, client_id, current)
db.commit()
def expire_queues(max_age_seconds, timeout_payload):
"""Wandelt zu alte Queues in Code-99-Tombstones um.
Die Funktion ist idempotent und kann von jedem Worker regelmäßig
aufgerufen werden. Nach dem ersten Lauf ist ``queue_started_at``
aktualisiert, sodass weitere Worker die Queue nicht erneut umwandeln.
"""
db = get_db()
cutoff = now() - max_age_seconds
rows = db.execute(
'SELECT tenant_id, client_id FROM ws_clients '
'WHERE queue_started_at IS NOT NULL AND queue_started_at <= ?',
(cutoff,)
).fetchall()
current = now()
for row in rows:
tenant_id = row['tenant_id']
client_id = row['client_id']
db.execute(
'DELETE FROM ws_client_queue WHERE tenant_id = ? AND client_id = ?',
(tenant_id, client_id)
)
db.execute(
'INSERT INTO ws_client_queue '
'(tenant_id, client_id, code, payload, code99_only, created_at) '
'VALUES (?, ?, 99, ?, 1, ?)',
(tenant_id, client_id, timeout_payload, current)
)
_set_queue_started_at(db, tenant_id, client_id, current)
if rows:
db.commit()
def cleanup_clients(retention_seconds):
"""Entfernt dauerhaft getrennte Clients ohne zustellbare Restnachrichten."""
db = get_db()
cutoff = now() - retention_seconds
rows = db.execute(
'SELECT tenant_id, client_id FROM ws_clients '
'WHERE disconnected_at IS NOT NULL AND disconnected_at < ?',
(cutoff,)
).fetchall()
for row in rows:
tenant_id = row['tenant_id']
client_id = row['client_id']
pending = db.execute(
'SELECT 1 FROM ws_client_queue '
'WHERE tenant_id = ? AND client_id = ? AND code99_only = 0 '
'AND (expires_at IS NULL OR expires_at > ?) LIMIT 1',
(tenant_id, client_id, now())
).fetchone()
if pending is not None:
# Noch zustellbare Nachrichten halten den Client am Leben.
continue
db.execute(
'DELETE FROM ws_client_queue WHERE tenant_id = ? AND client_id = ?',
(tenant_id, client_id)
)
db.execute(
'DELETE FROM ws_clients WHERE tenant_id = ? AND client_id = ?',
(tenant_id, client_id)
)
if rows:
db.commit()
def purge_expired_queue_rows():
"""Löscht abgelaufene ephemere Aufträge (z. B. Code 2)."""
db = get_db()
db.execute(
'DELETE FROM ws_client_queue WHERE expires_at IS NOT NULL AND expires_at <= ?',
(now(),)
)
db.commit()
# ----------------------------------------------------------------------
# Gruppenpräsenz
# ----------------------------------------------------------------------
def get_group_presence(tenant_id, group_id):
return get_db().execute(
'SELECT * FROM ws_group_presence WHERE tenant_id = ? AND group_id = ?',
(tenant_id, group_id)
).fetchone()
def record_group_pong(tenant_id, group_id, timestamp=None):
db = get_db()
current = timestamp if timestamp is not None else now()
db.execute(
'INSERT OR IGNORE INTO ws_group_presence (tenant_id, group_id) VALUES (?, ?)',
(tenant_id, group_id)
)
db.execute(
'UPDATE ws_group_presence SET last_pong_at = ?, updated_at = CURRENT_TIMESTAMP '
'WHERE tenant_id = ? AND group_id = ?',
(current, tenant_id, group_id)
)
db.commit()
def set_group_online_since(tenant_id, group_id, timestamp=None):
db = get_db()
current = timestamp if timestamp is not None else now()
db.execute(
'INSERT OR IGNORE INTO ws_group_presence (tenant_id, group_id) VALUES (?, ?)',
(tenant_id, group_id)
)
db.execute(
'UPDATE ws_group_presence SET online_since = ?, updated_at = CURRENT_TIMESTAMP '
'WHERE tenant_id = ? AND group_id = ?',
(current, tenant_id, group_id)
)
db.commit()
+14
View File
@@ -31,6 +31,20 @@ class Config:
WS_CLIENT_RETENTION_MINUTES = int(
os.environ.get('CMBNET_WS_CLIENT_RETENTION_MINUTES', '60')
)
# Intervall, in dem jeder Worker die gemeinsame Zustell-Queue nach
# Nachrichten für seine lokal verbundenen Clients prüft. Kleine Werte
# senken die Latenz, erzeugen aber mehr Datenbankzugriffe.
WS_BUS_POLL_INTERVAL = float(
os.environ.get('CMBNET_WS_BUS_POLL_INTERVAL', '0.5')
)
# Kurzlebige Zustellaufträge (Code 2) verfallen nach dieser Zeit, damit
# sie nicht bei einem späteren Reconnect zugestellt werden.
WS_EPHEMERAL_TTL_SECONDS = int(
os.environ.get('CMBNET_WS_EPHEMERAL_TTL_SECONDS', '30')
)
# Optionale feste Worker-ID. Standardmäßig setzt der Broker
# ``<hostname>:<pid>`` ein.
WS_WORKER_ID = os.environ.get('CMBNET_WS_WORKER_ID', '')
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
+61
View File
@@ -126,6 +126,61 @@ CREATE TABLE IF NOT EXISTS ws_tokens (
FOREIGN KEY (account_id) REFERENCES accounts(id)
);
-- Prozessübergreifender WebSocket-Zustand
-- Bekannte Client-IDs, Account-Zuordnung, letzte Sequenznummer und
-- Verbindungsstatus. Die Tabelle überlebt Reconnects auf anderen Workern.
CREATE TABLE IF NOT EXISTS ws_clients (
tenant_id INTEGER NOT NULL,
client_id TEXT NOT NULL,
account_id INTEGER NOT NULL,
last_seq INTEGER NOT NULL DEFAULT 0,
worker_id TEXT,
authenticated INTEGER NOT NULL DEFAULT 0,
connected_at REAL,
disconnected_at REAL,
queue_started_at REAL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (tenant_id, client_id),
FOREIGN KEY (tenant_id) REFERENCES tenants(id),
FOREIGN KEY (account_id) REFERENCES accounts(id)
);
-- Persistente Zustellaufträge pro Client. Jeder Worker liefert nur die
-- Aufträge seiner eigenen, lokal verbundenen Clients aus.
CREATE TABLE IF NOT EXISTS ws_client_queue (
id INTEGER PRIMARY KEY AUTOINCREMENT,
tenant_id INTEGER NOT NULL,
client_id TEXT NOT NULL,
code INTEGER NOT NULL,
payload TEXT NOT NULL,
code99_only INTEGER NOT NULL DEFAULT 0,
created_at REAL NOT NULL,
expires_at REAL,
FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);
-- Gemeinsame Gruppenpräsenz. last_pong_at und online_since werden von allen
-- Workern gelesen und geschrieben.
CREATE TABLE IF NOT EXISTS ws_group_presence (
tenant_id INTEGER NOT NULL,
group_id INTEGER NOT NULL,
last_pong_at REAL,
online_since REAL,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (tenant_id, group_id),
FOREIGN KEY (tenant_id) REFERENCES tenants(id),
FOREIGN KEY (group_id) REFERENCES groups(id)
);
-- Workerübergreifende Cache-Revisionen. Jeder Worker vergleicht die Revision
-- seines In-Memory-Caches mit diesem Wert und lädt bei Abweichung neu.
CREATE TABLE IF NOT EXISTS cache_state (
key TEXT PRIMARY KEY,
revision INTEGER NOT NULL DEFAULT 0,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- Persistierte WebSocket Nachrichten für Code >= 1000
CREATE TABLE IF NOT EXISTS ws_messages_store (
id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -164,3 +219,9 @@ CREATE INDEX IF NOT EXISTS idx_street_house_numbers_lookup
ON street_house_numbers(tenant_id, street_name, house_number);
CREATE INDEX IF NOT EXISTS idx_ws_tokens_token ON ws_tokens(token);
CREATE INDEX IF NOT EXISTS idx_ws_messages_ts ON ws_messages_store(ts);
CREATE INDEX IF NOT EXISTS idx_ws_clients_account
ON ws_clients(tenant_id, account_id);
CREATE INDEX IF NOT EXISTS idx_ws_client_queue_client
ON ws_client_queue(tenant_id, client_id, id);
CREATE INDEX IF NOT EXISTS idx_ws_client_queue_expires
ON ws_client_queue(expires_at);
+4
View File
@@ -3,3 +3,7 @@ Werkzeug>=3.0.0
flask-sock>=0.7.0
simple-websocket>=1.0.0
python-dateutil>=2.9.0
packaging>=26.3
gevent>=26.9.0
greenlet>=3.5.6
gunicorn>=26.2.0
+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