# 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. `//mobil` oder `//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//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 => 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 //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 //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 `//ws`. 3. Bei `open` sendet er Code 0: ```json {"code":0,"msg":{"token":"…","client_type":"group_view"}, "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 //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= error=: ` - 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. | Die konkreten Fehler stehen in der Antwort (`errors[].error`) und im Serverlog (`FCM-Signal abgelehnt: token=… error=…`). Die Oberfläche zeigt den ersten Fehler direkt an. Zusätzlich schreibt die Anwendung **eine Zeile pro Wake** in `logs/cmbnet-fcm-YYYY-MM-DD.log`. Dort stehen auch dann Einträge, wenn der Flask-Logger nur nach stdout/journald schreibt: ```json {"event":"wake-manual","group_id":1,"valid_tokens":2,"connected":0, "candidates":2,"sent":2,"failed":0,"errors":[],"error":null} {"event":"wake-auto","client_id":"…","reason":"queue","tokens":1, "sent":1,"failed":0,"errors":[],"error":null} {"event":"wake-unavailable","valid_tokens":2,"connected":0, "error":"FCM ist deaktiviert."} ``` Einzelne abgelehnte Tokens erscheinen nicht als eigene Zeilen; sie sind im Feld `errors` der Wake-Zeile enthalten (Token nur als Fingerabdruck). Die Datei lässt sich mit `CMBNET_FCM_DEBUG_LOG=0` abschalten. Das WS-Debug-Log `logs/cmbnet-ws-*.log` enthält dagegen nur eingehende WebSocket-Nachrichten und Empfängerlisten, keine FCM-Versandereignisse. ### 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: - `//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: ```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.