@@ -0,0 +1,437 @@
# 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:
```json
{"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)` auf. Das ist ein
HTTPS-Aufruf an die FCM-HTTP-v1-API von Google.
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. |
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:
` ``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.