Files
Sternsinger/CMBNet/docs/FCM_ARCHITEKTUR.md
T
2026-11-09 12:04:51 +01:00

12 KiB
Raw Blame History

FCM-Aufwachsignale für mobile PWA-Clients

Zweck

Mobile Webviews sollen gezielt aus dem Hintergrund geholt werden, damit sie ihre WebSocket-Verbindung erneuern, die persistente Broker-Queue leeren und – bei aktivierter Positionsübertragung – mindestens ein Positionsupdate senden. Google Firebase Cloud Messaging (FCM) transportiert dabei nur ein Signal. Chat-Nachrichten, Positionsdaten, Mandanten, Rollen und URLs der Anwendung bleiben ausschließlich in der WebSocket-Kommunikation bzw. in der Datenbank.

Das Signal besteht aus einem Data-Payload mit den Feldern type und reason (z. B. queue, offline, manual). Diese Metadaten dienen nur der Protokollierung und der Entscheidung, ob ein sichtbarer Hinweis sinnvoll ist. Sie sind kein Anwendungsinhalt.

Beteiligte Komponenten

Komponente Aufgabe
cmbnet/ws/broker.py Erkennt nicht zustellbare Nachrichten, trennt Verbindungen ohne Lebenszeichen und fordert ein Wake-Signal an.
cmbnet/ws/heartbeat.py Sendet Code-1-Pings und prüft, ob Clients noch antworten.
cmbnet/ws/push.py Periodischer Worker für den Offline-Timeout.
cmbnet/services/fcm_service.py Firebase-Admin-Initialisierung und FCM-Versand.
cmbnet/api/push.py Token-Registrierung, Abmeldung und manueller Wake-Button.
static/js/sw.js Empfängt das FCM-Signal, weckt ein Fenster und zeigt ggf. eine Benachrichtigung.
static/js/views/mobile.js Registriert das Token, verbindet den WebSocket neu und sendet die Position.
templates/dispatcher*.html Radar-Button zum manuellen Wecken.

Ablauf

  1. Die mobile PWA fordert nach Erlaubnis für Benachrichtigungen ein FCM-Token an. Das Token wird über POST /<tenant>/api/push/register zusammen mit Client-ID, Client-Typ und der Einstellung auto_position gespeichert.
  2. Der Broker puffert eine Nachricht für einen getrennten mobilen Client wie bisher in ws_client_queue.
  3. Zusätzlich prüft er, ob ein gültiges FCM-Token vorliegt und ob der Client als getrennt gilt. Wenn ja, sendet er ein FCM-Aufwachsignal.
  4. Der Service Worker wird durch FCM geweckt. Er kann selbst keine WebSocket-Verbindung betreiben. Deshalb übergibt er den Impuls per postMessage an ein bereits geöffnetes PWA-Fenster.
  5. Die PWA baut den WebSocket neu auf. Der Broker liefert die Queue und die Late Entries aus. Neue Nachrichten lösen wie bisher den In-App-Dialog aus.
  6. Bei aktivierter automatischer Positionsübertragung sendet die PWA mindestens eine Position. Zuerst wird eine frische Geolocation angefordert; schlägt das im Hintergrund fehl, wird die letzte bekannte Position verwendet.
  7. Der Service Worker wartet über einen MessageChannel bis zu 20 Sekunden auf die Bestätigung der PWA. Erst danach beendet er den Push-Event. Ist kein Fenster erreichbar, zeigt er eine allgemeine Benachrichtigung an.
  8. Ein Klick auf diese Benachrichtigung öffnet /<prefix>/wake. Die Route leitet anhand der bestehenden Session in die passende mobile View. FCM selbst enthält keine Mandanten- oder Rollen-URL.

Trigger

Gequeuete Nachricht

Sobald eine Nachricht mit Code >= 99 für einen mobilen Client eingereiht oder direkt an ihn gesendet wird, versucht der Broker ein FCM-Signal. Das gilt bewusst auch dann, wenn der Client laut Broker noch als verbunden gilt: Auf iOS bleibt dieser Status oft veraltet, obwohl der WebSocket nicht mehr erreichbar ist. Mehrere Nachrichten innerhalb des Queue-Cooldowns lösen nur ein Signal aus. Mit CMBNET_FCM_WAKE_CONNECTED_CLIENTS=0 lässt sich das zusätzliche Wecken verbundener Clients abschalten.

Offline-Erkennung

Ein Client gilt nur dann als offline, wenn der Broker seine WebSocket- Verbindung als beendet markiert hat (ws_clients.disconnected_at). Dafür gibt es drei Wege:

  1. Ein sauber geschlossener Socket wird in der WS-Route unmittelbar erkannt.
  2. Die mobile View schließt ihren Socket beim Wechsel in den Hintergrund (visibilitychange) bzw. beim Verlassen der Seite (pagehide). Damit ist sie sofort offline, ohne auf einen Timeout warten zu müssen. Beim Sichtbarwerden verbindet sie sich neu und frischt ihr FCM-Token auf.
  3. Halb offene Verbindungen, bei denen das Gerät einschläft, ohne FIN/RST zu senden, werden vom Heartbeat nach CMBNET_WS_CLIENT_OFFLINE_TIMEOUT_SECONDS (Default 180) ohne Lebenszeichen geschlossen. Als Lebenszeichen zählt ein Code-2-Pong oder jede andere eingehende WebSocket-Nachricht des Clients.
  4. Jeder WSGI-Worker hinterlässt ein Lebenszeichen in ws_workers. Clients eines nicht mehr laufenden Workers – etwa nach einem Neustart – werden automatisch als getrennt markiert. Das verhindert dauerhaft „verbundene“ Karteileichen in der Datenbank.

Ohne Schritt 3 und 4 blieben schlafende Geräte bzw. Clients aus einem alten Prozess dauerhaft als „verbunden“ markiert und würden nie als Wake-Kandidaten erscheinen. ws_clients-Einträge mit gültigem FCM-Token werden beim normalen Client-Aufräumen nicht entfernt; das Token hat eine eigene, großzügigere Aufbewahrungsfrist.

Offline-Timeout

Ein periodischer Worker prüft getrennte Clients. Nach CMBNET_FCM_OFFLINE_WAKE_MINUTES (Default 5 Minuten) wird ein Signal gesendet, auch wenn keine Nachricht in der Queue liegt. Damit erhält die Gruppen-View die Gelegenheit, ein Positionsupdate zu senden. Für die Gruppen-View gilt das nur, wenn auto_position aktiviert ist; Dispatcher-Mobil-Clients werden ebenfalls berücksichtigt, haben aber keine automatische Positionsübertragung.

Manuell

Der Radar-Button im Desktop-Dispatcher und im mobilen Dispatcher ruft POST /<tenant>/api/push/wake auf. Der mobile Dispatcher schränkt den Aufruf auf die aktuell ausgewählte Gruppe ein, sofern eine Gruppe gewählt ist. Der Desktop-Dispatcher weckt alle mobilen Clients mit gültigem Token – auch solche, die der Broker noch als verbunden führt. Ein kurzer Cooldown verhindert versehentliche Doppelklicks.

Client-Typen

Nur diese Werte sind zugelassen:

  • group_view für Accounts der Rolle Gruppe
  • dispatcher_mobile für Accounts der Rolle Dispatcher oder Administrator

Der Typ wird beim Code-0-Handshake vom Client mitgesendet und serverseitig gegen die Session-Rolle geprüft. Ohne gültigen Typ werden keine FCM-Tokens angenommen und keine Wake-Signale versendet. Der Observer-View und der Desktop-Dispatcher erhalten keine FCM-Behandlung.

Datenbank

ws_clients wurde ergänzt um:

  • client_type: Client-Typ für das FCM-Routing
  • last_wake_at, last_wake_reason: Drosselung und Nachvollziehbarkeit

Neue Tabelle ws_workers:

  • Lebenszeichen je WSGI-Worker (started_at, heartbeat_at)
  • dient der Erkennung verwaister Clients nach einem Worker-Neustart

Neue Tabelle ws_push_tokens:

  • ein FCM-Token ist projektweit eindeutig
  • Zuordnung zu Mandant, Account, Client-ID und Client-Typ
  • auto_position für die periodische Positionsweckung
  • invalid für von FCM abgelehnte Tokens

Die Registrierung wird bei einem Reload mit neuer Client-ID auf die neue Client-ID verschoben. Nach einer Token-Rotation wird das alte Token derselben Webview entfernt. Verwaiste Tokens werden mit einer eigenen Frist aufgeräumt; der zugehörige ws_clients-Eintrag bleibt so lange erhalten. Die Client-Queues werden weiterhin nach der kürzeren Queue-Frist bereinigt.

Mehrere Worker

Jeder WSGI-Worker besitzt einen eigenen Push-Worker. Die Kandidatenauswahl erfolgt deshalb in einer SQLite-Transaktion (BEGIN IMMEDIATE). Der erste Worker reserviert die Clients über last_wake_at; alle anderen sehen sie in diesem Lauf nicht mehr. Der eigentliche FCM-Versand findet nach dem Commit statt. Das verhindert doppelte Signale bei mehreren Gunicorn-Workern.

Konfiguration

Alle Werte sind optional; ohne CMBNET_FCM_ENABLED=1 bleibt FCM vollständig inaktiv:

Variable Default Bedeutung
CMBNET_FCM_ENABLED 0 FCM aktivieren
CMBNET_FCM_SERVICE_ACCOUNT_FILE – Pfad zum Service-Account-JSON
CMBNET_FCM_SERVICE_ACCOUNT_JSON – Service Account als JSON-String
CMBNET_FCM_PROJECT_ID aus Credentials Firebase-Projekt
CMBNET_FCM_WEB_API_KEY – Öffentlicher Web-API-Key
CMBNET_FCM_WEB_AUTH_DOMAIN <projekt>.firebaseapp.com Auth-Domain
CMBNET_FCM_WEB_PROJECT_ID CMBNET_FCM_PROJECT_ID Web-Projekt-ID
CMBNET_FCM_WEB_STORAGE_BUCKET <projekt>.appspot.com Storage-Bucket
CMBNET_FCM_WEB_MESSAGING_SENDER_ID – Sender-ID
CMBNET_FCM_WEB_APP_ID – Firebase-Web-App-ID
CMBNET_FCM_VAPID_KEY – Web-Push-Zertifikat
CMBNET_FCM_WEB_SDK_VERSION 10.14.1 Firebase-JS-Version
CMBNET_FCM_OFFLINE_WAKE_MINUTES 5 Offline-Timeout
CMBNET_FCM_QUEUE_WAKE_COOLDOWN_SECONDS 60 Cooldown je Queue-Wake
CMBNET_FCM_MANUAL_WAKE_COOLDOWN_SECONDS 15 Cooldown für den Button
CMBNET_FCM_SIGNAL_TTL_SECONDS 600 FCM-TTL
CMBNET_FCM_WAKE_CONNECTED_CLIENTS 1 Auch als verbunden geltende mobile Clients wecken (iOS)
CMBNET_FCM_WAKE_POLL_INTERVAL_SECONDS 30 Prüfintervall des Workers
CMBNET_FCM_PUSH_TOKEN_RETENTION_MINUTES 43200 Aufbewahrung nicht verbundener Tokens (30 Tage)
CMBNET_WS_CLIENT_OFFLINE_TIMEOUT_SECONDS 180 Zeit ohne Lebenszeichen bis zur Offline-Markierung

Beschränkungen und Konsequenzen bei PWAs

Allgemein

  • Ein Service Worker kann keine dauerhafte WebSocket-Verbindung halten und keine Seite im Hintergrund starten. Das eigentliche Reconnecten und Senden übernimmt immer ein PWA-Fenster.
  • Ist die PWA vollständig geschlossen, kann FCM den Service Worker wecken, aber nicht zuverlässig ein Fenster öffnen. Dann bleibt nur eine sichtbare Benachrichtigung; der Nutzer muss sie antippen. Das ist eine Plattform- und keine Implementierungsgrenze.
  • Ein Wake-Signal ist eine Aufforderung, keine Garantie. Zustellung kann durch Netz, Energiesparmodus, Firebase oder das Betriebssystem verzögert oder zusammengefasst werden.
  • Ein Positionsupdate ist nur möglich, wenn die Seite tatsächlich läuft und der Browser Geolocation im Hintergrund erlaubt. Andernfalls wird die letzte bekannte Position verwendet oder das Update entfällt.
  • Die PWA muss über HTTPS ausgeliefert werden. Das Token ist ein installationsbezogenes Geheimnis und sollte nicht geloggt werden.
  • FCM ist ein Google-Dienst. Verfügbarkeit, Datenschutz und Netzwerkzugriffe müssen betrieblich bewertet werden.

Android (Chrome/Edge)

  • Web Push funktioniert in der installierten PWA und im Browser, sofern Benachrichtigungen erlaubt sind.
  • Chrome kann Hintergrundtabs einfrieren. Der Service Worker bleibt für Push-Events zuständig; die Seite wird beim postMessage möglicherweise erst verzögert aktiv.
  • Hersteller-Energiesparfunktionen und „App beenden“ verhindern Zustellungen.
  • clients.openWindow ist aus einem Push-Event nicht zuverlässig erlaubt; deshalb der Benachrichtigungs-Fallback.

iOS/iPadOS (Safari)

  • Web Push ist erst ab iOS/iPadOS 16.4 und nur für zum Home-Bildschirm hinzugefügte PWAs verfügbar. In einem normalen Safari-Tab wird kein FCM-Token registriert.
  • Benachrichtigungen müssen ausdrücklich erlaubt werden. Ohne Erlaubnis bleibt die App offline, bis sie manuell geöffnet wird.
  • iOS kann Hintergrund-Pushes stark drosseln oder zusammenfassen. Ein stilles Data-Push ist nicht garantiert; der sichtbare Benachrichtigungs- Fallback ist Teil des Designs.
  • Hintergrund-Geolocation ist stark eingeschränkt. Das garantierte „mindestens ein Positionsupdate“ gilt deshalb nur, solange die Seite nach dem Wake tatsächlich ausgeführt wird.
  • APNs/FCM können die Zustellung verweigern, wenn die PWA vom Nutzer entfernt oder die Benachrichtigungserlaubnis entzogen wurde.

Konsequenz für die Bedienung

Die Funktion ist eine beschleunigte Synchronisierung, kein Ersatz für das Öffnen der App. Disponenten sollten bei zeitkritischen Lagen weiterhin den manuellen Radar-Button nutzen und die mobile Gruppe bei Bedarf zusätzlich telefonisch erreichen.