Files
Sternsinger/CMBNet/docs/FCM_PROTOKOLL.md
T

21 KiB
Raw Blame History

FCM-Protokoll und Reverse-Proxy-Anforderungen

Diese Datei beschreibt zwei Dinge:

  1. den vollständigen Ablauf vom Laden der PWA über die Token-Registrierung und den WebSocket-Handshake bis zum manuellen FCM-Wake und der Reaktion des Clients – mit den präzisen Funktionsnamen,
  2. die Anforderungen an einen vorgeschalteten Reverse Proxy, insbesondere zu CORS, Service Worker und WebSocket.

Teil A – Protokollablauf

Kurzsequenz

PWA-Seite (mobile.js)     Service Worker (sw.js)     Flask/API/Broker           Google FCM / APNs
        |                         |                        |                          |
        |-- registerServiceWorker() ---------------------->| sw.js, fcm-sw-config.js  |
        |-- initFirebasePush() --> fcmMessaging.getToken() |                          |
        |<-------------------------------------------------|------------------- Token |
        |-- POST /push/register -------------------------->| register_push_token()    |
        |-- GET /auth/ws-token --------------------------->| ws_token()               |
        |-- WS /ws, Code 0 ------------------------------->| register_connection()    |
        |<-- Code 0 "authenticated" -----------------------| authenticate()           |
        |                         |                        |                          |
        |                         |                        |-- send_wake() ---------->|
        |                         |<-- onBackgroundMessage -|   send_each_for_multicast|
        |<-- postMessage cmbnet-wake ---------------------|                          |
        |-- connectWebSocket(), Position ----------------->|                          |
        |                         |-- showNotification()   |                          |

Beteiligte

Komponente Datei / Modul Aufgabe
HTML-Grundgerüst templates/base.html erzeugt die Client-ID, bindet Skripte ein
Mobile View static/js/views/mobile.js Firebase-Client, Token-Registrierung, WebSocket, Wake-Reaktion
Service Worker static/js/sw.js empfängt Hintergrund-Pushes, weckt ein Fenster, zeigt ggf. eine Benachrichtigung
HTTP-API cmbnet/api/push.py, cmbnet/api/auth.py Token-Registrierung, Wake-Button, WS-Einmal-Token
WebSocket cmbnet/ws/routes.py, cmbnet/ws/broker.py Handshake, Verbindungsverwaltung, Queue, Wake-Auslösung
Persistenz cmbnet/ws/store.py ws_clients, ws_push_tokens, ws_worker, Queues
Firebase Admin cmbnet/services/fcm_service.py serverseitiger FCM-Versand über die HTTP-v1-API
Google FCM Firebase Cloud Messaging Zustellung an Browser/PWA, bei iOS über APNs

Phase 1 – Laden der PWA

  1. Der Browser lädt z. B. /<tenant>/mobil oder /<tenant>/dispatcher-mobil.
  2. Das Inline-Skript in templates/base.html führt die IIFE initClientId() aus und setzt:
    • window.CMBNET_CLIENT_ID
    • window.CMBNET_CLIENT_SESSION_ID (Kompatibilität)
  3. Das Template setzt weitere Globals, u. a.:
    • window.CMBNET_TENANT
    • window.CMBNET_VIEW_MODE
    • window.CMBNET_CLIENT_TYPE (group_view bzw. dispatcher_mobile)
    • window.CMBNET_SW_URL
    • window.CMBNET_FCM_CONFIG (Ergebnis von cmbnet/services/fcm_service.py:public_fcm_config())
  4. static/js/views/mobile.js registriert document.addEventListener('DOMContentLoaded', initMobile).
  5. initMobile() ruft u. a. auf:
    • loadSettings()
    • initMap()
    • registerServiceWorker()
    • initNotifications()
    • initPushWakeListener()
    • anschließend connectWebSocket()

Phase 2 – Service Worker und Firebase-SDK

  1. registerServiceWorker() registriert window.CMBNET_SW_URL über navigator.serviceWorker.register(swUrl).
  2. Nach load und nur bei Notification.permission === 'granted' ruft sie initFirebasePush(registration) auf.
  3. Der Service Worker static/js/sw.js lädt beim Start:
    • importScripts('fcm-sw-config.js') → serverseitig erzeugte öffentliche Konfiguration (cmbnet/__init__.py:fcm_service_worker_config())
    • importScripts('https://www.gstatic.com/firebasejs/<sdkVersion>/firebase-app-compat.js', '.../firebase-messaging-compat.js')
  4. Im Service Worker:
    • firebase.initializeApp(fcmConfig.firebase)
    • fcmMessaging = firebase.messaging()
    • fcmMessaging.onBackgroundMessage(payload => handleFcmWake(reason))

Phase 3 – Benachrichtigungsrecht und FCM-Token

  1. initNotifications() bindet den Dialog und ruft bei Bedarf requestNotifications() → Notification.requestPermission() auf.
  2. initFirebasePush(registration, force) prüft:
    • window.CMBNET_FCM_CONFIG.enabled
    • gültigen clientType
    • Notification.permission === 'granted'
    • auf iOS: isStandaloneMode() (installierte PWA)
  3. Danach:
    • loadScriptOnce() lädt firebase-app-compat.js und firebase-messaging-compat.js im Seitenkontext.
    • firebase.initializeApp(config.firebase)
    • messaging = firebase.messaging()
    • messaging.onMessage(payload => { showFirebaseDebugPopup(...); handlePushWake(reason); }) für den Vordergrund.
    • messaging.getToken({vapidKey: config.vapidKey, serviceWorkerRegistration: swRegistration})
  4. Der Token wird in state.fcmToken gespeichert.
  5. syncPushRegistration() sendet:
    • POST /<tenant>/api/push/register
    • Body: token, client_id (window.CMBNET_CLIENT_ID), client_type, platform, auto_position
  6. Serverseitig in cmbnet/api/push.py:register_push_token():
    • TOKEN_RE.fullmatch(token)
    • normalize_client_type(...) (cmbnet/ws/client_types.py)
    • broker.normalize_client_id(...) (cmbnet/ws/broker.py)
    • store.upsert_push_token(...) (cmbnet/ws/store.py)
  7. store.upsert_push_token():
    • legt bei Bedarf einen Platzhalter in ws_clients an (disconnected_at = now()), damit das Token als Wake-Kandidat existiert,
    • schreibt/aktualisiert ws_push_tokens (Token ist projektweit eindeutig),
    • entfernt ältere Tokens derselben Client-ID.
  8. Der Server loggt FCM-Token registriert: tenant=… client=… type=….

Phase 4 – WebSocket-Handshake

  1. connectWebSocket() ruft GET /<tenant>/api/auth/ws-token auf. Serverseitig: cmbnet/api/auth.py:ws_token() legt eine Zeile in ws_tokens an und liefert {token}.
  2. Der Client öffnet new WebSocket(wsUrl) gegen /<tenant>/ws.
  3. Bei open sendet er Code 0:
    {"code":0,"msg":{"token":"…","client_type":"group_view"},
     "client_id":"<window.CMBNET_CLIENT_ID>"}
    
  4. Serverseitig in cmbnet/ws/routes.py:ws():
    • _parse_auth_payload(msg.msg) liefert Token, Client-ID und Client-Typ.
    • broker.normalize_client_id(...)
    • broker.register_connection(...) → store.ensure_client(...) (INSERT/UPDATE ws_clients, disconnected_at = NULL) → store.touch_worker(...) (ws_workers)
    • broker.authenticate(...) prüft ws_tokens (used = 0, Ablauf), markiert das Token als benutzt, setzt conn['last_seen_at'] und store.mark_authenticated(...).
    • Bestätigung: broker.send_to_connection(..., WSMessage(code=0, msg='authenticated')).
  5. Clientseitig verarbeitet handleWsMessage() Code 0:
    • state.authenticated = true
    • flushWsOutbox()
    • resolveWsAuthentication()
    • syncPushRegistration() (Token-Aktualität)
  6. waitForWsAuthentication() wartet bei einem Wake bis zu PUSH_WAKE_AUTH_TIMEOUT_MS (25 s) auf diesen Schritt.

Phase 5 – Heartbeat und Offline-Erkennung

  • cmbnet/ws/heartbeat.py:HeartbeatManager._send_heartbeat() sendet Code 1 an authentifizierte Verbindungen.
  • Der Client antwortet in handleWsMessage() mit Code 2 (pong).
  • HeartbeatManager._check_presence() bzw. broker.check_client_liveness(timeout) schließt Verbindungen ohne Lebenszeichen nach CMBNET_WS_CLIENT_OFFLINE_TIMEOUT_SECONDS (Default 180).
  • store.touch_worker(), store.mark_orphan_clients_disconnected() und store.cleanup_worker_registry() erkennen Clients aus beendeten Worker-Prozessen.

Phase 6 – Manueller Wake (Dispatcher-Button)

  1. Desktop: static/js/views/dispatcher.js:wakeMobileClients() Mobile Dispatcher: static/js/views/mobile.js:wakeMobileClientsFromUi()

  2. Beide senden POST /<tenant>/api/push/wake (optional mit group_id).

  3. Serverseitig cmbnet/api/push.py:wake_mobile_clients():

    • public_fcm_config() prüft die öffentliche Web-Konfiguration.
    • store.mobile_push_stats(tenant_id) liefert valid_tokens und connected.
    • fcm_service.server_status() prüft die tatsächliche Sendefähigkeit (_server_config() und _ensure_app()). Ist der Server nicht sendebereit, antwortet der Endpunkt mit HTTP 503 und einer konkreten Fehlermeldung.
    • store.offline_mobile_wake_candidates(..., include_connected=True, re_wake_before=None) wählt alle mobilen Clients mit gültigem Token. Ein ausdrücklicher Klick ignoriert die automatische last_wake_at- Drosselung.
    • fcm_service.send_wake(tokens, reason='manual')
  4. send_wake():

    • _ensure_app() initialisiert firebase-admin einmalig mit credentials.Certificate(...) und firebase_admin.initialize_app(..., name='cmbnet').
    • baut messaging.MulticastMessage(tokens=..., data={'type': 'cmbnet-wake','reason':...}, android=messaging.AndroidConfig(priority= 'high', ttl=...), webpush=messaging.WebpushConfig(headers={'Urgency': 'high','TTL':...})).
    • ruft _send_batch() auf.
  5. _send_batch() ruft messaging.send_each_for_multicast(message, app=app) auf. Das ist ein HTTPS-Aufruf an die FCM-HTTP-v1-API von Google.

    Wichtig: firebase-admin initialisiert hier eine benannte App (name='cmbnet'). Die messaging-Funktionen verwenden ohne app=... immer die Standard-App. Ohne die explizite Angabe schlägt der Versand mit ValueError: The default Firebase app does not exist fehl.

  6. Für jede Antwort:

    • Erfolg → sent_tokens
    • Fehler → errors mit Fehlerklasse und -text (Token nur als Fingerabdruck) und ggf. invalid_tokens bei UnregisteredError, INVALID_ARGUMENT oder SENDER_ID_MISMATCH.
  7. Zurück in wake_mobile_clients():

    • store.set_client_wake_sent(...) für erfolgreiche Tokens
    • store.mark_push_token_invalid(...) für von FCM abgelehnte Tokens
    • Logzeilen:
      • FCM-Wake manuell: tenant=… tokens=… verbunden=… candidates=… sent=… failed=…
      • FCM-Signal abgelehnt: token=<fingerprint> error=<Klasse>: <Text>
    • JSON-Antwort mit candidates, sent, failed, valid_tokens, connected, errors, error.

Phase 7 – Zustellung über Firebase

  1. Google FCM nimmt die Nachricht an und stellt sie an das Gerät zu.
    • Android/Desktop-Browser: direkt über den FCM-Web-Push-Endpunkt.
    • iOS/iPadOS: über APNs; Voraussetzung ist eine installierte PWA (Home-Bildschirm), iOS/iPadOS 16.4+ und die in der Firebase-Konsole hinterlegte APNs-Konfiguration.
  2. Ist die PWA im Hintergrund oder geschlossen, empfängt der Service Worker die Nachricht über fcmMessaging.onBackgroundMessage(...).
  3. Ist die PWA im Vordergrund, empfängt die Seite die Nachricht über messaging.onMessage(...) in initFirebasePush().

Phase 8 – Reaktion des Clients

Hintergrund / Service Worker:

  1. handleFcmWake(reason)
  2. wakeOpenClients(reason):
    • self.clients.matchAll({type:'window', includeUncontrolled:true})
    • client.postMessage({type:'cmbnet-wake', reason}, [channel.port2])
    • wartet über MessageChannel bis zu FCM_WAKE_ACK_TIMEOUT_MS (20 s) auf die Antwort der Seite.
  3. Ist kein Fenster offen: showWakeNotification(reason) → self.registration.showNotification(...) mit data.url = fcmConfig.wakeUrl (/wake).

Seite:

  1. initPushWakeListener() empfängt die Service-Worker-Nachricht.
  2. handlePushWake(reason, port):
    • connectWebSocket()
    • waitForWsAuthentication()
    • bei Gruppen-View und aktivierter Positionsübertragung: sendWakePosition() → navigator.geolocation.getCurrentPosition(...) bzw. sendAutomaticPosition(true) → sendOwnPosition(...)
    • port.postMessage({ok, positionSent, reason})

Klick auf die Benachrichtigung:

  • notificationclick im Service Worker fokussiert ein bestehendes Fenster und sendet {type:'cmbnet-wake', reason:'notification'} oder öffnet fcmConfig.wakeUrl (/wake).
  • cmbnet/__init__.py:wake() leitet auf views.index mit dem Mandanten aus der Session um.

Fehlerbild „2 Fehler bei 2 Empfängern“

Das bedeutet: Es wurden 2 gültige Tokens als Empfänger gefunden, aber FCM hat beide Sendungen abgelehnt (sent = 0, failed = 2). Es fehlen also keine Tokens. Typische Ursachen:

Fehlertext (Auszug) Bedeutung
SenderIdMismatchError / SENDER_ID_MISMATCH Token gehört zu einem anderen Firebase-Projekt als der Service-Account.
UnregisteredError / UNREGISTERED Token ist nicht mehr gültig (App gelöscht, Token rotiert, Projekt gewechselt).
InvalidArgumentError / INVALID_ARGUMENT Tokenformat, VAPID-Schlüssel oder Web-Push-Konfiguration passt nicht.
ThirdPartyAuthError, PermissionDenied Service-Account darf nicht senden, FCM-API im Projekt nicht aktiviert oder Projekt-ID falsch.
QuotaExceededError, InternalError, Unavailable temporäres FCM-/Netzwerkproblem; später erneut versuchen.
FirebaseError: … credential … Service-Account ungültig, abgelaufen oder falsche Datei.
ValueError: The default Firebase app does not exist Die benannte App cmbnet wurde initialisiert, aber send_each_for_multicast() ohne app=... aufgerufen. Beim Versand muss die benannte App explizit übergeben werden.

Seit der erweiterten Diagnose stehen die konkreten Fehler in der Antwort (errors[].error) und im Serverlog (FCM-Signal abgelehnt: token=… error=…). Die Oberfläche zeigt den ersten Fehler direkt an.

Datenbankbezug

  • ws_clients: client_id, account_id, client_type, worker_id, connected_at, disconnected_at, authenticated, last_wake_at, last_wake_reason.
  • ws_push_tokens: tenant_id, client_id, account_id, token, client_type, platform, auto_position, invalid, updated_at.
  • ws_workers: worker_id, started_at, heartbeat_at.
  • ws_tokens: Einmal-Token für den Code-0-Handshake.
  • ws_client_queue: persistente Nachrichtenqueue je Client.

Teil B – Reverse Proxy und CORS

Kurzfassung

Für Firebase ist keine besondere CORS-Konfiguration am Reverse Proxy erforderlich. Der Browser spricht direkt mit den Google-Endpunkten; der Reverse Proxy liefert nur die eigene Anwendung aus. CORS wäre nur relevant, wenn die PWA und die API auf unterschiedlichen Origins liegen oder wenn Firebase-Aufrufe über den eigenen Proxy geleitet werden – beides ist nicht vorgesehen.

Wichtig sind dagegen:

  1. HTTPS,
  2. korrekt ausgelieferter Service Worker,
  3. WebSocket-Unterstützung,
  4. passende Content-Security-Policy,
  5. Ausgangszugriff des Servers zu Google.

HTTPS und Sicherheitskontext

  • Service Worker, Web Push und getToken() benötigen einen sicheren Kontext. Außer localhost ist HTTPS Pflicht.
  • Das TLS-Zertifikat muss vom Client akzeptiert werden; ein selbstsigniertes Zertifikat verhindert die Service-Worker-Registrierung.

Service Worker

  • /sw.js muss unter der App-Wurzel erreichbar sein, damit der Scope die App abdeckt. Bei einem Prefix (z. B. /cmbnet/) über SCRIPT_NAME/X-Forwarded-Prefix den Pfad unverändert weiterleiten.
  • MIME-Typ: application/javascript (setzt die Anwendung bereits).
  • Cache-Control: no-cache muss erhalten bleiben. Ein CDN oder Proxy darf sw.js nicht lange cachen, sonst bleiben alte Client-Versionen aktiv.
  • Wird der Scope über ein Unterverzeichnis hinaus benötigt, kann der Header Service-Worker-Allowed: / gesetzt werden. Die Anwendung liefert den Worker bereits an der Wurzel aus; normalerweise ist das nicht nötig.
  • /fcm-sw-config.js wird per importScripts geladen. Auch diese Datei muss ohne langes Caching ausgeliefert werden (die Anwendung setzt Cache-Control: no-cache).
  • Der Service Worker lädt Skripte von https://www.gstatic.com. Ein Proxy muss das nicht übernehmen; der Browser lädt sie direkt. Eine CSP muss diese Quelle erlauben (siehe unten).

WebSocket

Der WebSocket ist zwar nicht Teil von FCM, aber Voraussetzung für die Wake-Reaktion:

  • /<tenant>/ws muss als WebSocket durchgereicht werden: Upgrade: websocket, Connection: Upgrade.
  • Buffering im Proxy muss für diese Route deaktiviert sein.
  • Lese-/Idle-Timeouts müssen über dem Heartbeat-Intervall liegen (CMBNET_WS_HEARTBEAT_INTERVAL, Default 60 s). Ein zu kurzer Proxy-Timeout trennt die Verbindung ständig neu.
  • HTTP/1.1 für den Upgrade; HTTP/2 zum Backend ist für WebSocket nicht erforderlich.

Beispiel nginx:

location /cmbnet/ws {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Prefix /cmbnet;
    proxy_buffering off;
    proxy_read_timeout 3600s;
}

location = /cmbnet/sw.js {
    proxy_pass http://127.0.0.1:8000;
    add_header Cache-Control "no-cache";
}

location = /cmbnet/fcm-sw-config.js {
    proxy_pass http://127.0.0.1:8000;
    add_header Cache-Control "no-cache";
}

Content-Security-Policy

Falls eine CSP gesetzt wird, müssen mindestens erlaubt sein:

  • script-src 'self' https://www.gstatic.com (Firebase-Compat-SDK im Seitenkontext und im Service Worker)
  • connect-src 'self' https://*.googleapis.com https://*.google.com https://fcmregistrations.googleapis.com https://firebaseinstallations.googleapis.com https://www.gstatic.com
  • worker-src 'self' (Service Worker)
  • img-src 'self' data: (Benachrichtigungssymbol)
  • frame-src ist für FCM nicht erforderlich.

Nicht empfohlen:

  • Cross-Origin-Embedder-Policy: require-corp kann Service Worker und Push-Registrierung behindern.
  • Cross-Origin-Opener-Policy sollte die PWA nicht isolieren, wenn Firebase-Installationen genutzt werden; same-origin-allow-popups ist unkritisch.
  • Permissions-Policy darf geolocation nicht sperren, wenn die mobile View beim Wake ein Positionsupdate senden soll.

CORS im Detail

  • Browser → Google: Die Firebase-JS-SDK-Aufrufe (getToken, Installation, Token-Registrierung) gehen direkt an Google. Google liefert die passenden CORS-Header. Der eigene Reverse Proxy ist daran nicht beteiligt und muss keine CORS-Header setzen.
  • Browser → eigene API: /push/register, /push/wake, /auth/ws-token und /ws sind same-origin. CORS ist nicht nötig.
  • Server → Google: firebase-admin sendet serverseitig an oauth2.googleapis.com und fcm.googleapis.com. Das ist kein Browser-CORS, sondern ein normaler HTTPS-Aufruf. Der Server braucht Ausgangszugriff (Firewall/Proxy) zu diesen Hosts.
  • Wenn die PWA und die API bewusst auf getrennten Origins laufen, müssen Credentials-CORS (Access-Control-Allow-Origin exakt, Vary: Origin, Access-Control-Allow-Credentials: true) und Cookie-Attribute (SameSite=None; Secure) konfiguriert werden. Das ist nicht der Standardaufbau dieses Projekts.
  • Firebase-Aufrufe sollten nicht über den eigenen Reverse Proxy geleitet werden. Das würde CORS, Authorization-Header und Zertifikatsvertrauen unnötig verkomplizieren.

Ausgangsverbindungen des Servers

Der Server muss per HTTPS erreichen können:

  • fcm.googleapis.com (Nachrichtenversand)
  • oauth2.googleapis.com (Service-Account-Token)
  • firebaseinstallations.googleapis.com und fcmregistrations.googleapis.com (nur Browser, nicht Server)
  • www.gstatic.com (nur Browser)

Wenn der Server einen HTTP-Proxy für ausgehende Verbindungen benötigt, müssen HTTPS_PROXY/HTTP_PROXY (und ggf. NO_PROXY) für den WSGI-Prozess gesetzt sein. Die CA des ausgehenden Proxys muss im Zertifikatsspeicher des Servers liegen. Eine falsche Systemzeit (JWT- Signatur) führt ebenfalls zu Authentifizierungsfehlern.

Weitere Hinweise

  • POST /push/register und POST /push/wake nicht durch ein zu strenges Rate-Limit blockieren; der Wake-Button ist eine bewusste Benutzeraktion.
  • Cookies der Session müssen durch den Proxy unverändert weitergegeben werden, sonst schlägt login_required fehl.
  • Vary-Header und Kompression sind für FCM unkritisch; die Service-Worker-Dateien sollten aber nicht komprimiert/umgeschrieben werden.
  • Für iOS muss in der Firebase-Konsole ein APNs-Schlüssel hinterlegt sein. Das ist keine Reverse-Proxy-Einstellung, sondern eine Firebase-Projektvoraussetzung.