From 572a881f7228378fc6c465f4b014619aab8975a8 Mon Sep 17 00:00:00 2001 From: Thomas Date: Wed, 11 Nov 2026 07:50:00 +0100 Subject: [PATCH] 4. Versuch mit mehr Debug ausgeben --- CMBNet/README_CMBNet.md | 5 +- CMBNet/cmbnet/api/push.py | 7 + CMBNet/cmbnet/services/fcm_service.py | 45 ++- CMBNet/docs/.~lock.FCM_PROTOKOLL.md# | 1 + CMBNet/docs/FCM_ARCHITEKTUR.md | 5 + CMBNet/docs/FCM_PROTOKOLL.md | 437 ++++++++++++++++++++++++++ CMBNet/static/js/views/dispatcher.js | 10 +- CMBNet/static/js/views/mobile.js | 10 +- 8 files changed, 516 insertions(+), 4 deletions(-) create mode 100644 CMBNet/docs/.~lock.FCM_PROTOKOLL.md# create mode 100644 CMBNet/docs/FCM_PROTOKOLL.md diff --git a/CMBNet/README_CMBNet.md b/CMBNet/README_CMBNet.md index bdeb3b8..fe72396 100644 --- a/CMBNet/README_CMBNet.md +++ b/CMBNet/README_CMBNet.md @@ -182,7 +182,10 @@ lässt sich dieses zusätzliche Wecken abschalten. Die Architektur, Trigger, Grenzen auf Android/iOS und alle Konfigurationsvariablen stehen in -[`docs/FCM_ARCHITEKTUR.md`](docs/FCM_ARCHITEKTUR.md). Die praktische +[`docs/FCM_ARCHITEKTUR.md`](docs/FCM_ARCHITEKTUR.md). Der vollständige +Protokollablauf inklusive Funktionsnamen sowie die Anforderungen an Reverse +Proxy und CORS sind in +[`docs/FCM_PROTOKOLL.md`](docs/FCM_PROTOKOLL.md) beschrieben. Die praktische Einrichtung von Firebase-Projekt, Web-App, VAPID-Schlüssel, Service-Account und PWA-Installation beschreibt [`docs/FCM_HOWTO.md`](docs/FCM_HOWTO.md). diff --git a/CMBNet/cmbnet/api/push.py b/CMBNet/cmbnet/api/push.py index 4458eda..c755335 100644 --- a/CMBNet/cmbnet/api/push.py +++ b/CMBNet/cmbnet/api/push.py @@ -181,6 +181,12 @@ def wake_mobile_clients(**kwargs): len(candidates), int(result.get('sent') or 0), int(result.get('failed') or 0) ) + error_details = list(result.get('errors') or [])[:5] + for item in error_details: + current_app.logger.warning( + 'FCM-Wake-Fehler: tenant=%s token=%s error=%s', + g.tenant_id, item.get('fingerprint'), item.get('error') + ) return jsonify({ 'ok': True, @@ -190,5 +196,6 @@ def wake_mobile_clients(**kwargs): 'failed': int(result.get('failed') or 0), 'valid_tokens': stats['valid_tokens'], 'connected': stats['connected'], + 'errors': error_details, 'error': result.get('error'), }) diff --git a/CMBNet/cmbnet/services/fcm_service.py b/CMBNet/cmbnet/services/fcm_service.py index f4d57ee..16d8f1e 100644 --- a/CMBNet/cmbnet/services/fcm_service.py +++ b/CMBNet/cmbnet/services/fcm_service.py @@ -7,6 +7,7 @@ Firebase-Konfiguration vollständig startet. """ from __future__ import annotations +import hashlib import json import logging import threading @@ -190,6 +191,24 @@ class FcmService: raise FileNotFoundError(f'Service-Account-Datei fehlt: {path}') return credentials.Certificate(str(path)) + @staticmethod + def _token_fingerprint(token): + """Verkürzter, stabiler Token-Fingerabdruck für Logs (kein Klartext).""" + if not token: + return '-' + return hashlib.sha256(str(token).encode('utf-8')).hexdigest()[:12] + + @staticmethod + def _describe_send_error(token, exception): + """Formatiert einen FCM-Fehler und entfernt das Token aus dem Text.""" + name = type(exception).__name__ if exception is not None else 'UnknownError' + text = str(exception or '').strip() + if token: + text = text.replace(str(token), '') + if text: + return f'{name}: {text}' + return name + def send_wake(self, tokens, reason='wake'): """Sendet ein reines Daten-Signal an die angegebenen FCM-Tokens. @@ -205,6 +224,7 @@ class FcmService: 'failed': 0, 'sent_tokens': [], 'invalid_tokens': [], + 'errors': [], } if not tokens: return result @@ -246,6 +266,9 @@ class FcmService: result['failed'] += batch_result['failed'] result['sent_tokens'].extend(batch_result['sent_tokens']) result['invalid_tokens'].extend(batch_result['invalid_tokens']) + result['errors'].extend(batch_result['errors']) + if batch_result.get('error'): + result['error'] = batch_result['error'] return result @@ -255,6 +278,7 @@ class FcmService: 'failed': 0, 'sent_tokens': [], 'invalid_tokens': [], + 'errors': [], } message = messaging.MulticastMessage( tokens=tokens, @@ -266,8 +290,17 @@ class FcmService: response = messaging.send_each_for_multicast(message) responses = list(response.responses) except Exception as exc: - logger.warning('FCM-Batchversand fehlgeschlagen: %s', exc) + details = self._describe_send_error(None, exc) + logger.warning( + 'FCM-Batchversand fehlgeschlagen (%s Empfänger): %s', + len(tokens), details + ) batch_result['failed'] += len(tokens) + batch_result['error'] = details + batch_result['errors'].append({ + 'fingerprint': '-', + 'error': details, + }) return batch_result for token, send_response in zip(tokens, responses): @@ -277,6 +310,16 @@ class FcmService: continue batch_result['failed'] += 1 exception = send_response.exception + details = self._describe_send_error(token, exception) + fingerprint = self._token_fingerprint(token) + logger.warning( + 'FCM-Signal abgelehnt: token=%s error=%s', + fingerprint, details + ) + batch_result['errors'].append({ + 'fingerprint': fingerprint, + 'error': details, + }) text = str(exception or '').upper() if ( isinstance(exception, messaging.UnregisteredError) diff --git a/CMBNet/docs/.~lock.FCM_PROTOKOLL.md# b/CMBNet/docs/.~lock.FCM_PROTOKOLL.md# new file mode 100644 index 0000000..a38d29a --- /dev/null +++ b/CMBNet/docs/.~lock.FCM_PROTOKOLL.md# @@ -0,0 +1 @@ +Thomas Kugelmeier,thomas,MacBookAir.lan,11.11.2026 07:42,file:///Users/thomas/Library/Application%20Support/LibreOffice/4; \ No newline at end of file diff --git a/CMBNet/docs/FCM_ARCHITEKTUR.md b/CMBNet/docs/FCM_ARCHITEKTUR.md index 240cf2e..2d9c6c3 100644 --- a/CMBNet/docs/FCM_ARCHITEKTUR.md +++ b/CMBNet/docs/FCM_ARCHITEKTUR.md @@ -14,6 +14,11 @@ Das Signal besteht aus einem Data-Payload mit den Feldern `type` und `reason` Protokollierung und der Entscheidung, ob ein sichtbarer Hinweis sinnvoll ist. Sie sind kein Anwendungsinhalt. +Der vollständige Ablauf vom Laden der PWA bis zur Reaktion auf das +Aufwachsignal – mit allen Funktionsnamen, Endpunkten und Fehlerpfaden – steht +in [`FCM_PROTOKOLL.md`](FCM_PROTOKOLL.md). Dort sind auch die Anforderungen an +Reverse Proxy, Service Worker, WebSocket und CORS beschrieben. + ## Beteiligte Komponenten | Komponente | Aufgabe | diff --git a/CMBNet/docs/FCM_PROTOKOLL.md b/CMBNet/docs/FCM_PROTOKOLL.md new file mode 100644 index 0000000..c51c271 --- /dev/null +++ b/CMBNet/docs/FCM_PROTOKOLL.md @@ -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. `//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 => { 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 //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)` 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= 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. | + +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: + +- `//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. diff --git a/CMBNet/static/js/views/dispatcher.js b/CMBNet/static/js/views/dispatcher.js index 6c70017..3ab1c0c 100644 --- a/CMBNet/static/js/views/dispatcher.js +++ b/CMBNet/static/js/views/dispatcher.js @@ -3669,9 +3669,17 @@ async function wakeMobileClients() { true ); } else { + const firstError = result.error + || (Array.isArray(result.errors) + && result.errors[0] + && result.errors[0].error) + || ''; + const detail = firstError + ? ` Grund: ${String(firstError).slice(0, 240)}` + : ''; setStreetSearchStatus( `Wecken fehlgeschlagen: ${Number(result.failed) || 0} Fehler ` - + `bei ${candidates} Empfängern.`, + + `bei ${candidates} Empfängern.${detail}`, true ); } diff --git a/CMBNet/static/js/views/mobile.js b/CMBNet/static/js/views/mobile.js index 8d37433..898bc26 100644 --- a/CMBNet/static/js/views/mobile.js +++ b/CMBNet/static/js/views/mobile.js @@ -680,9 +680,17 @@ async function wakeMobileClientsFromUi() { + `(registriert: ${tokens}, verbunden: ${connected}).` ); } else { + const firstError = result.error + || (Array.isArray(result.errors) + && result.errors[0] + && result.errors[0].error) + || ''; + const detail = firstError + ? ` Grund: ${String(firstError).slice(0, 240)}` + : ''; showMobileToast( `Wecken fehlgeschlagen: ${Number(result.failed) || 0} Fehler ` - + `bei ${candidates} Empfängern.`, + + `bei ${candidates} Empfängern.${detail}`, true ); }