Harden push notification delivery

Keep encrypted message content out of push payloads and improve cross-platform notification data. Add token registration validation and per-session unregister support, batch and deduplicate sends, remove only confirmed unregistered tokens, and protect queued retries with leases. Add delivery tests and document the push API and Firebase setup.
This commit is contained in:
Artemy
2026-10-17 19:53:34 +07:00
parent 9aa7e017e2
commit e060b2bcbb
21 changed files with 16353 additions and 132 deletions
+38 -12
View File
@@ -1,29 +1,55 @@
# Push-уведомления
## POST /api/pushes/token/register
## Регистрация устройства
Требуется роль User/Admin. JSON:
`POST /api/pushes/token/register` требует access token с ролью User/Admin и действующей сессией. Тело:
```json
{"token":"<FCM registration token>","platform":"Android"}
```
Сервис связывает токен с userId и sid текущего access token, добавляет или обновляет запись. Успех Unit — 204. Пустой token/platform отклоняется 400; тело BadRequest(ModelState) не всегда содержит полезное объяснение.
Токен привязывается к `userId` и `sid` из JWT. Передавать эти идентификаторы в запросе не нужно. Одна сессия имеет один токен; повторная регистрация обновляет токен/платформу и активирует запись. При переходе устройства на другой аккаунт токен переносится, старый аккаунт больше не получает push на это устройство.
При отзыве сессии связанные токены деактивируются. В DI зарегистрирован FirebasePushProvider; credentials читаются при старте приложения.
Успех — `204 No Content`. Отсутствующие, пустые и состоящие из пробелов поля отклоняются с `400`; ограничения длины: token — 512, platform — 50 символов. Отозванная или истёкшая сессия не может зарегистрировать токен. Передавайте новый FCM token при его обновлении и заново регистрируйте его после входа в новую сессию.
## Отправка
`DELETE /api/pushes/token` отключает push **только для текущей сессии**, не завершая её. Повторный вызов также возвращает `204`. Другие устройства пользователя продолжают получать уведомления. Повторный POST включает push снова. При отзыве сессии её токены деактивируются; при отправке дополнительно проверяются срок и отзыв сессии.
Личные сообщения вызывают отправку push собеседнику. title — имя отправителя; body — первые 40 символов EncryptedContent. Data содержит chatId и isGroup ("false"). Это текущая реализация: сервер не расшифровывает содержимое.
## Содержимое
Для E2EE тело push должно быть нейтральным. Для текущего MAUI, отправляющего обычный текст, этот body раскрывает превью сообщения внешнему push-провайдеру.
Личный чат уведомляет собеседника; группа/канал — действующих незабаненных участников, кроме отправителя. Перед каждой попыткой сервер исключает прочитавших сообщение. Push не зависит от наличия SignalR-соединения: подключение само по себе не подтверждает, что сообщение прочитано.
## Доставка
`title` содержит имя отправителя (при недоступности профиля — `Govor`), `body` — нейтральное `New message`. Содержимое `EncryptedContent` в Firebase не передаётся, даже если клиент записал туда обычный текст.
Сохранение сообщения, SignalR и Firebase не образуют единую транзакцию. Ошибка после SaveChanges может дать ошибку Send, хотя сообщение уже записано. Автоматическое повторение без идентификатора клиентской операции может создать дубль. Нужны outbox, дедупликация и обработка недействительных FCM-токенов.
Данные для перехода к сообщению (все значения — строки):
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
```json
{
"type": "chat_message",
"chatId": "<chat UUID>",
"messageId": "<message UUID>",
"senderId": "<sender UUID>",
"isGroup": "false"
}
```
Источник: [Govor.API/Hubs/Infrastructure/ChatNotificationService.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Hubs/Infrastructure/ChatNotificationService.cs).
Для группы/канала `isGroup` равно `"true"`. Android получает канал `chat_messages`, высокий приоритет, стандартный звук и tag `chat_<chatId>`. Клиент должен создать этот канал. iOS получает APNs alert со стандартным звуком и `thread-id` чата; Web — notification tag чата. На iOS нужны корректная APNs-конфигурация проекта Firebase и разрешение уведомлений в приложении.
## Надёжность
Сообщение и `ChatPushNotification` сохраняются одним `SaveChanges`. Worker каждые 2 секунды выбирает до 20 задач и получает условную аренду на 2 минуты. После сбоя/перезапуска задача остаётся в БД. Ошибки повторяются с задержкой 2–300 секунд; исключение одной отправки не блокирует остальные сообщения пакета. Номер попытки защищает завершение/перепланирование от старого worker после повторного захвата задачи.
Токены дедуплицируются и отправляются независимыми пакетами до 500. Удаляются только токены, для которых FCM подтвердил `UNREGISTERED`. Ошибки доступа, неверный payload, `INVALID_ARGUMENT` и временные сбои не удаляют токены. Неполный ответ провайдера или ошибка очистки токенов не считаются успешной доставкой. Отсутствие активных токенов завершает задачу без отправки; последующая регистрация не отправляет старые сообщения задним числом.
Доставка допускает повторы до принятия провайдером и не подтверждает показ на устройстве. При частичном успехе общий повтор может повторно уведомить уже получившие устройства. Прерывание после принятия FCM до удаления задачи тоже допускает повтор: клиенту следует дедуплицировать события по `messageId`. Tag объединяет уведомления чата, но не заменяет дедупликацию. При удалении сообщения задача удаляется каскадно. Для реакций и изменений профилей/сообществ push сейчас не создаётся.
## Настройка Firebase
Включите `Firebase__Enabled=true` и передайте service account через `Firebase__CredentialsJson` либо `Firebase__CredentialsPath`. Также поддерживается путь `GOOGLE_APPLICATION_CREDENTIALS`; путь по умолчанию — `secrets/firebase-adminsdk.json` относительно каталога API. Ключи не должны попадать в репозиторий. При включённом Firebase некорректные credentials останавливают запуск.
`Firebase__Enabled=false` выбирает NullPushProvider для разработки: реальной доставки нет, задачи считаются обработанными. Это не режим накопления push на время отключения провайдера.
Изменения не требуют новой миграции; в БД должна быть применена существующая `20261003070406_ReliableChatPush`.
Проверка: `dotnet test Govor.Server.Tests/Govor.Server.Tests.csproj`. Тесты проверяют HTTP API, SQL-очередь/аренду/retry, обработку ошибок и реальную сериализацию Firebase SDK через подменённый HTTP-транспорт. Для PostgreSQL предусмотрена `TEST_POSTGRES_CONNECTION` на отдельную БД с именем, заканчивающимся `_tests`. Эти тесты не подтверждают доставку на физическое устройство.
Лимит пакета и классификация ошибок сверены с [документацией отправки FCM](https://firebase.google.com/docs/cloud-messaging/send/admin-sdk) и [кодами ошибок FCM](https://firebase.google.com/docs/cloud-messaging/error-codes).