Files
Govor/docs/endpoints/push.md
Artemy 2d99c57a3b Expand server tests and enforce coverage
Consolidate server tests under tests/, upgrade them to .NET 10, and add CI coverage thresholds and reports. Expand API and application boundary coverage while fixing related issues in media handling, friend blocking, session crypto, presence, username validation, and local storage.
2026-10-24 15:30:32 +07:00

56 lines
7.8 KiB
Markdown
Raw Permalink 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.
# Push-уведомления
## Регистрация устройства
`POST /api/pushes/token/register` требует access token с ролью User/Admin и действующей сессией. Тело:
```json
{"token":"<FCM registration token>","platform":"Android"}
```
Токен привязывается к `userId` и `sid` из JWT. Передавать эти идентификаторы в запросе не нужно. Одна сессия имеет один токен; повторная регистрация обновляет токен/платформу и активирует запись. При переходе устройства на другой аккаунт токен переносится, старый аккаунт больше не получает push на это устройство.
Успех — `204 No Content`. Отсутствующие, пустые и состоящие из пробелов поля отклоняются с `400`; ограничения длины: token — 512, platform — 50 символов. Отозванная или истёкшая сессия не может зарегистрировать токен. Передавайте новый FCM token при его обновлении и заново регистрируйте его после входа в новую сессию.
`DELETE /api/pushes/token` отключает push **только для текущей сессии**, не завершая её. Повторный вызов также возвращает `204`. Другие устройства пользователя продолжают получать уведомления. Повторный POST включает push снова. При отзыве сессии её токены деактивируются; при отправке дополнительно проверяются срок и отзыв сессии.
## Содержимое
Личный чат уведомляет собеседника; группа/канал — действующих незабаненных участников, кроме отправителя. Перед каждой попыткой сервер исключает прочитавших сообщение. Push не зависит от наличия SignalR-соединения: подключение само по себе не подтверждает, что сообщение прочитано.
`title` содержит имя отправителя (при недоступности профиля — `Govor`), `body` — нейтральное `New message`. Содержимое `EncryptedContent` в Firebase не передаётся, даже если клиент записал туда обычный текст.
Данные для перехода к сообщению (все значения — строки):
```json
{
"type": "chat_message",
"chatId": "<chat UUID>",
"messageId": "<message UUID>",
"senderId": "<sender UUID>",
"isGroup": "false"
}
```
Для группы/канала `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 tests/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).