Broker/Protocol Analyse

This commit is contained in:
concierge committed 2026-10-31 19:14:52 +01:00
1 parent c477a05f03
commit 268e150f2b
7 files changed
+868 -2

No files matched your search

+8
View File
@@ -61,6 +61,10 @@ Die beiden Zeitfenster lassen sich über Umgebungsvariablen konfigurieren:
zugestellt.
- `CMBNET_WS_GROUP_ONLINE_TIMEOUT_SECONDS` (Default `120`): Zeit ohne Code-2-
Lebenszeichen, nach der eine Gruppe von `online` auf `unterwegs` wechselt.
- `CMBNET_WS_DEBUG_MESSAGES` (Default `1`): schreibt jede beim Broker
eingehende Nachricht inklusive Absender, Code und ermitteltem Empfängerkreis
nach `logs/cmbnet-ws-YYYY-MM-DD.log`. Mit `0` lässt sich die Ausgabe
abschalten.
Die Sitzungs-Queues liegen im Arbeitsspeicher des Broker-Prozesses. Sie
überstehen damit WebSocket-Unterbrechungen und Seiten-Reloads, nicht aber einen
@@ -68,6 +72,10 @@ Neustart des Servers. Der mobile Client puffert zusätzlich ausgehende
fachliche Nachrichten kurzzeitig lokal und sendet sie nach erfolgreicher
Authentifizierung automatisch nach.
Eine ausführliche Beschreibung des Protokolls, der Brokerlogik, der
Nebenläufigkeit und der aktuellen Abweichungen steht in
[`../doc/broker.md`](../doc/broker.md).
## Erste Einrichtung
Nach der Initialisierung der Datenbank müssen noch Mandanten und ein Admin-Account angelegt werden.
+32 -1
View File
@@ -1,11 +1,15 @@
"""
Transaktionslogging für CMBNet
"""
import os
import json
from datetime import datetime
from pathlib import Path
from threading import Lock
from flask import current_app
_WS_DEBUG_LOCK = Lock()
def write_transaction_log(tenant_id, actor_id, actor_name, action, entity_type, entity_id, details=None):
"""
@@ -33,6 +37,33 @@ def write_transaction_log(tenant_id, actor_id, actor_name, action, entity_type,
f.write(log_line)
def write_ws_debug_log(tenant_id, payload):
"""Schreibt eine Broker-Debugzeile in ein separates Tageslog.
Die Ausgabe enthält die eingehende Nachricht und den vom Broker
ermittelten Empfängerkreis. Sie ist bewusst unabhängig von der
Flask-Logger-Konfiguration, damit sie auch im Produktivbetrieb über
``CMBNET_WS_DEBUG_MESSAGES`` gezielt verfügbar ist.
"""
if not current_app.config.get('WS_DEBUG_MESSAGES', True):
return
log_dir = Path(current_app.config['LOG_DIR'])
log_dir.mkdir(parents=True, exist_ok=True)
date_str = datetime.now().strftime('%Y-%m-%d')
log_file = log_dir / f'cmbnet-ws-{date_str}.log'
timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f')[:-3]
line = (
f'{timestamp} [TENANT:{tenant_id}] WS-IN '
f'{json.dumps(payload, ensure_ascii=False, default=str)}\n'
)
with _WS_DEBUG_LOCK:
with open(log_file, 'a', encoding='utf-8') as f:
f.write(line)
def get_tenant_code(tenant_id):
"""Holt den Tenant-Code für die Logausgabe"""
from cmbnet.db import get_db
+102 -1
View File
@@ -238,6 +238,81 @@ class WebSocketBroker:
def _get_connection(self, tenant_id, account_id):
return self.connections.get(tenant_id, {}).get(account_id)
def log_incoming(self, tenant_id, message, sender=None, recipients=None, note=None):
"""Schreibt eine Debugzeile für eine beim Broker eingehende Nachricht.
Erfasst werden Absender, Code, Empfänger-ID, Payload (bei Code 0 ohne
Token) und der ermittelte Empfängerkreis inklusive Verbindungsstatus.
Die Ausgabe ist unabhängig von der Flask-Logger-Konfiguration und kann
über ``WS_DEBUG_MESSAGES`` abgeschaltet werden.
"""
try:
if not current_app.config.get('WS_DEBUG_MESSAGES', True):
return
except RuntimeError:
return
try:
db = get_db()
if sender is None and message.sender_id:
sender = db.execute(
'SELECT * FROM accounts WHERE id = ? AND tenant_id = ?',
(message.sender_id, tenant_id)
).fetchone()
sender_info = None
if sender is not None:
sender_info = self._get_sender_info(tenant_id, sender)
recipient_rows = []
for recipient_id in sorted(set(recipients or [])):
account = db.execute(
'SELECT * FROM accounts WHERE id = ? AND tenant_id = ?',
(recipient_id, tenant_id)
).fetchone()
if account is None:
recipient_rows.append({
'account_id': recipient_id,
'known': False,
'connected': False,
'authenticated': False
})
continue
info = self._get_sender_info(tenant_id, account)
info['connected'] = bool(self._get_connection(tenant_id, recipient_id))
info['authenticated'] = self.is_authenticated(tenant_id, recipient_id)
recipient_rows.append(info)
payload = message.msg
if message.code == 0:
payload = '<redacted>'
elif not isinstance(payload, str):
payload = json.dumps(payload, ensure_ascii=False, default=str)
payload = str(payload)
if len(payload) > 1000:
payload = payload[:1000] + '…'
entry = {
'code': message.code,
'sender': sender_info,
'receiver_id': message.receiver_id,
'session_id': getattr(message, 'session_id', None),
'ts': message.ts,
'msg': payload,
'recipients': recipient_rows,
'note': note
}
from cmbnet.core.logging import write_ws_debug_log
write_ws_debug_log(tenant_id, entry)
except Exception as exc:
# Eine Debugausgabe darf den Nachrichtenfluss niemals stören.
try:
current_app.logger.warning('WS-Debugausgabe fehlgeschlagen: %s', exc)
except Exception:
pass
# ------------------------------------------------------------------
# Sitzungs-Queues
# ------------------------------------------------------------------
@@ -533,6 +608,10 @@ class WebSocketBroker:
(message.sender_id, tenant_id)
).fetchone()
if not sender:
self.log_incoming(
tenant_id, message, sender=None, recipients=[],
note='Absender nicht im Mandanten gefunden'
)
return
code = message.code
@@ -540,11 +619,19 @@ class WebSocketBroker:
# Code 0 wird ausschließlich in der WebSocket-Route (Handshake)
# verarbeitet und niemals weitergeleitet.
if code <= 0:
self.log_incoming(
tenant_id, message, sender, recipients=[],
note='interner Code, wird nicht über route_message verteilt'
)
return
# Code 1 sendet ausschließlich der Server (Heartbeat-Routine).
# Nachrichten dieses Typs von Clients werden ignoriert.
if code == 1:
self.log_incoming(
tenant_id, message, sender, recipients=[],
note='Code 1 von Client ignoriert'
)
return
# Code 2 ist die Antwort eines Clients auf den Heartbeat. Sie wird nur
@@ -559,12 +646,20 @@ class WebSocketBroker:
# dürfen diesen Code nicht selbst auslösen.
if code == 99:
if apply_business:
self.log_incoming(
tenant_id, message, sender, recipients=[],
note='Code 99 von Client ignoriert'
)
return
self._deliver(tenant_id, message, sender)
return
# Sonstige interne Codes (< 100) werden nicht an die Oberfläche gegeben.
if code < 100:
self.log_incoming(
tenant_id, message, sender, recipients=[],
note='interner Code < 100 ignoriert'
)
return
# Ab hier: fachliche Nachrichten (>= 100).
@@ -577,6 +672,10 @@ class WebSocketBroker:
'WebSocket-Nachricht abgelehnt: code=%s sender=%s tenant=%s msg=%s',
code, sender['id'], tenant_id, str(message.msg)[:300]
)
self.log_incoming(
tenant_id, message, sender, recipients=[],
note='fachliche Änderung abgelehnt'
)
return
message = self._prepare_message(tenant_id, message, sender)
@@ -1126,7 +1225,9 @@ class WebSocketBroker:
def _deliver(self, tenant_id, message, sender):
"""Stellt eine Nachricht an alle berechtigten, verbundenen Clients zu."""
for recipient_id in self._get_recipients(tenant_id, message, sender):
recipients = sorted(self._get_recipients(tenant_id, message, sender))
self.log_incoming(tenant_id, message, sender, recipients=recipients)
for recipient_id in recipients:
self._send(tenant_id, recipient_id, message)
def _send(self, tenant_id, account_id, message):
+18
View File
@@ -65,6 +65,10 @@ def ws(ws, tenant):
msg = WSMessage.from_json(data)
if not msg:
current_app.logger.warning(
'WebSocket-Nachricht ist kein gültiges JSON: tenant=%s account=%s length=%s',
tenant_id, account_id, len(data)
)
continue
# Die Absender-ID stammt immer aus der Session und kann vom Client
@@ -76,15 +80,25 @@ def ws(ws, tenant):
token, session_id = _parse_auth_payload(msg.msg)
if not session_id:
session_id = getattr(msg, 'session_id', None)
if session_id:
msg.session_id = session_id
if not token or not broker.authenticate(
tenant_id, account_id, token, session_id
):
broker.log_incoming(
tenant_id, msg, recipients=[],
note='Code-0-Handshake fehlgeschlagen'
)
current_app.logger.warning(
'WebSocket-Authentifizierung fehlgeschlagen: tenant=%s account=%s',
tenant_id, account_id
)
ws.close()
break
broker.log_incoming(
tenant_id, msg, recipients=[account_id],
note='Code-0-Handshake erfolgreich'
)
# Bestätigt dem Client den erfolgreichen Handshake. Erst jetzt
# darf er gepufferte fachliche Nachrichten senden.
broker.send_to_connection(
@@ -97,6 +111,10 @@ def ws(ws, tenant):
# Fachliche Nachrichten sind erst nach erfolgreicher
# Authentifizierung erlaubt.
if not broker.is_authenticated(tenant_id, account_id):
broker.log_incoming(
tenant_id, msg, recipients=[],
note='Nachricht vor Code-0-Authentifizierung'
)
ws.close()
break
+6
View File
@@ -25,6 +25,12 @@ class Config:
os.environ.get('CMBNET_WS_QUEUE_MAX_AGE_MINUTES', '15')
)
LATE_ENTRY_MAX_AGE_HOURS = int(os.environ.get('CMBNET_LATE_ENTRY_MAX_AGE_HOURS', '8'))
# Ausführliche Broker-Debugausgabe für eingehende Nachrichten und den
# ermittelten Empfängerkreis. Kann im Betrieb über die Umgebungsvariable
# CMBNET_WS_DEBUG_MESSAGES=0 abgeschaltet werden.
WS_DEBUG_MESSAGES = os.environ.get(
'CMBNET_WS_DEBUG_MESSAGES', '1'
).strip().lower() not in ('0', 'false', 'no', 'off')
LOG_DIR = BASE_DIR / 'logs'