Files
Sternsinger/CMBNet/docs/FCM_PROTOKOLL.md
T

438 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.