21 KiB
FCM-Protokoll und Reverse-Proxy-Anforderungen
Diese Datei beschreibt zwei Dinge:
- 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,
- 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
- Der Browser lädt z. B.
/<tenant>/mobiloder/<tenant>/dispatcher-mobil. - Das Inline-Skript in
templates/base.htmlführt die IIFEinitClientId()aus und setzt:window.CMBNET_CLIENT_IDwindow.CMBNET_CLIENT_SESSION_ID(Kompatibilität)
- Das Template setzt weitere Globals, u. a.:
window.CMBNET_TENANTwindow.CMBNET_VIEW_MODEwindow.CMBNET_CLIENT_TYPE(group_viewbzw.dispatcher_mobile)window.CMBNET_SW_URLwindow.CMBNET_FCM_CONFIG(Ergebnis voncmbnet/services/fcm_service.py:public_fcm_config())
static/js/views/mobile.jsregistriertdocument.addEventListener('DOMContentLoaded', initMobile).initMobile()ruft u. a. auf:loadSettings()initMap()registerServiceWorker()initNotifications()initPushWakeListener()- anschließend
connectWebSocket()
Phase 2 – Service Worker und Firebase-SDK
registerServiceWorker()registriertwindow.CMBNET_SW_URLübernavigator.serviceWorker.register(swUrl).- Nach
loadund nur beiNotification.permission === 'granted'ruft sieinitFirebasePush(registration)auf. - Der Service Worker
static/js/sw.jslä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')
- Im Service Worker:
firebase.initializeApp(fcmConfig.firebase)fcmMessaging = firebase.messaging()fcmMessaging.onBackgroundMessage(payload => handleFcmWake(reason))
Phase 3 – Benachrichtigungsrecht und FCM-Token
initNotifications()bindet den Dialog und ruft bei BedarfrequestNotifications()→Notification.requestPermission()auf.initFirebasePush(registration, force)prüft:window.CMBNET_FCM_CONFIG.enabled- gültigen
clientType Notification.permission === 'granted'- auf iOS:
isStandaloneMode()(installierte PWA)
- Danach:
loadScriptOnce()lädtfirebase-app-compat.jsundfirebase-messaging-compat.jsim Seitenkontext.firebase.initializeApp(config.firebase)messaging = firebase.messaging()messaging.onMessage(payload => handlePushWake(reason))für den Vordergrund.messaging.getToken({vapidKey: config.vapidKey, serviceWorkerRegistration: swRegistration})
- Der Token wird in
state.fcmTokengespeichert. syncPushRegistration()sendet:POST /<tenant>/api/push/register- Body:
token,client_id(window.CMBNET_CLIENT_ID),client_type,platform,auto_position
- 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)
store.upsert_push_token():- legt bei Bedarf einen Platzhalter in
ws_clientsan (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.
- legt bei Bedarf einen Platzhalter in
- Der Server loggt
FCM-Token registriert: tenant=… client=… type=….
Phase 4 – WebSocket-Handshake
connectWebSocket()ruftGET /<tenant>/api/auth/ws-tokenauf. Serverseitig:cmbnet/api/auth.py:ws_token()legt eine Zeile inws_tokensan und liefert{token}.- Der Client öffnet
new WebSocket(wsUrl)gegen/<tenant>/ws. - Bei
opensendet er Code 0:{"code":0,"msg":{"token":"…","client_type":"group_view"}, "client_id":"<window.CMBNET_CLIENT_ID>"} - 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/UPDATEws_clients,disconnected_at = NULL) →store.touch_worker(...)(ws_workers)broker.authenticate(...)prüftws_tokens(used = 0, Ablauf), markiert das Token als benutzt, setztconn['last_seen_at']undstore.mark_authenticated(...).- Bestätigung:
broker.send_to_connection(..., WSMessage(code=0, msg='authenticated')).
- Clientseitig verarbeitet
handleWsMessage()Code 0:state.authenticated = trueflushWsOutbox()resolveWsAuthentication()syncPushRegistration()(Token-Aktualität)
waitForWsAuthentication()wartet bei einem Wake bis zuPUSH_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 nachCMBNET_WS_CLIENT_OFFLINE_TIMEOUT_SECONDS(Default 180).store.touch_worker(),store.mark_orphan_clients_disconnected()undstore.cleanup_worker_registry()erkennen Clients aus beendeten Worker-Prozessen.
Phase 6 – Manueller Wake (Dispatcher-Button)
-
Desktop:
static/js/views/dispatcher.js:wakeMobileClients()Mobile Dispatcher:static/js/views/mobile.js:wakeMobileClientsFromUi() -
Beide senden
POST /<tenant>/api/push/wake(optional mitgroup_id). -
Serverseitig
cmbnet/api/push.py:wake_mobile_clients():public_fcm_config()prüft die öffentliche Web-Konfiguration.store.mobile_push_stats(tenant_id)liefertvalid_tokensundconnected.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 automatischelast_wake_at- Drosselung.fcm_service.send_wake(tokens, reason='manual')
-
send_wake():_ensure_app()initialisiertfirebase-admineinmalig mitcredentials.Certificate(...)undfirebase_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.
-
_send_batch()ruftmessaging.send_each_for_multicast(message, app=app)auf. Das ist ein HTTPS-Aufruf an die FCM-HTTP-v1-API von Google.Wichtig:
firebase-admininitialisiert hier eine benannte App (name='cmbnet'). Diemessaging-Funktionen verwenden ohneapp=...immer die Standard-App. Ohne die explizite Angabe schlägt der Versand mitValueError: The default Firebase app does not existfehl. -
Für jede Antwort:
- Erfolg →
sent_tokens - Fehler →
errorsmit Fehlerklasse und -text (Token nur als Fingerabdruck) und ggf.invalid_tokensbeiUnregisteredError,INVALID_ARGUMENToderSENDER_ID_MISMATCH.
- Erfolg →
-
Zurück in
wake_mobile_clients():store.set_client_wake_sent(...)für erfolgreiche Tokensstore.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
- 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.
- Ist die PWA im Hintergrund oder geschlossen, empfängt der Service Worker
die Nachricht über
fcmMessaging.onBackgroundMessage(...). - Ist die PWA im Vordergrund, empfängt die Seite die Nachricht über
messaging.onMessage(...)ininitFirebasePush().
Phase 8 – Reaktion des Clients
Hintergrund / Service Worker:
handleFcmWake(reason)wakeOpenClients(reason):self.clients.matchAll({type:'window', includeUncontrolled:true})client.postMessage({type:'cmbnet-wake', reason}, [channel.port2])- wartet über
MessageChannelbis zuFCM_WAKE_ACK_TIMEOUT_MS(20 s) auf die Antwort der Seite.
- Ist kein Fenster offen:
showWakeNotification(reason)→self.registration.showNotification(...)mitdata.url = fcmConfig.wakeUrl(/wake).
Seite:
initPushWakeListener()empfängt die Service-Worker-Nachricht.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:
notificationclickim Service Worker fokussiert ein bestehendes Fenster und sendet{type:'cmbnet-wake', reason:'notification'}oder öffnetfcmConfig.wakeUrl(/wake).cmbnet/__init__.py:wake()leitet aufviews.indexmit 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:
{"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:
- HTTPS,
- korrekt ausgelieferter Service Worker,
- WebSocket-Unterstützung,
- passende Content-Security-Policy,
- Ausgangszugriff des Servers zu Google.
HTTPS und Sicherheitskontext
- Service Worker, Web Push und
getToken()benötigen einen sicheren Kontext. Außerlocalhostist HTTPS Pflicht. - Das TLS-Zertifikat muss vom Client akzeptiert werden; ein selbstsigniertes Zertifikat verhindert die Service-Worker-Registrierung.
Service Worker
/sw.jsmuss unter der App-Wurzel erreichbar sein, damit der Scope die App abdeckt. Bei einem Prefix (z. B./cmbnet/) überSCRIPT_NAME/X-Forwarded-Prefixden Pfad unverändert weiterleiten.- MIME-Typ:
application/javascript(setzt die Anwendung bereits). Cache-Control: no-cachemuss erhalten bleiben. Ein CDN oder Proxy darfsw.jsnicht 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.jswird perimportScriptsgeladen. Auch diese Datei muss ohne langes Caching ausgeliefert werden (die Anwendung setztCache-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>/wsmuss 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.comworker-src 'self'(Service Worker)img-src 'self' data:(Benachrichtigungssymbol)frame-srcist für FCM nicht erforderlich.
Nicht empfohlen:
Cross-Origin-Embedder-Policy: require-corpkann Service Worker und Push-Registrierung behindern.Cross-Origin-Opener-Policysollte die PWA nicht isolieren, wenn Firebase-Installationen genutzt werden;same-origin-allow-popupsist unkritisch.Permissions-Policydarfgeolocationnicht 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-tokenund/wssind same-origin. CORS ist nicht nötig. - Server → Google:
firebase-adminsendet serverseitig anoauth2.googleapis.comundfcm.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-Originexakt,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.comundfcmregistrations.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/registerundPOST /push/wakenicht 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_requiredfehl. 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.