mirror of
https://github.com/Govor-team/Govor.git
synced 2026-11-17 04:58:46 +00:00
Add reactions, reliable push & session checks
Implements message reactions and reaction packs (domain models, services, admin HTTP API, media processing via ImageSharp and limits) and adds reliable push delivery (ChatPushNotification, ChatPushDispatcher, ChatPushWorker, improved ChatNotificationService). Enhances message reading (ReadChat API, unread counts, concurrency-safe receipts) and tightens session security (access-token session validation in JWT, hub filter, SessionAuthorization). Improves SignalR behavior (session groups, reaction/channel events, hub/error mappings). Adds EF migrations, many controller fixes (Forbid handling, password API), tests (Govor.Server.Tests), docs, CI and tooling updates (Dockerfile → .NET 10, GH Actions matrix for sqlite/postgres, Govor.Server.slnx, global.json), and small infra changes (AutoMapper bump, NullPushProvider, storage/token handling).
This commit is contained in:
@@ -0,0 +1,35 @@
|
||||
# Администрирование и незавершённые группы
|
||||
|
||||
## Административные маршруты
|
||||
|
||||
Следующая таблица показывает фактические атрибуты, а не требуемую безопасную политику.
|
||||
|
||||
| Метод | Маршрут | Защита сейчас |
|
||||
| --- | --- | --- |
|
||||
| POST | /api/admin/InviteUser/Invitation | Без Authorize |
|
||||
| GET | /api/admin/InviteUser | Без Authorize |
|
||||
| GET | /api/admin/InviteUser/GetAllActiveInvitations | Без Authorize |
|
||||
| GET | /api/admin/InviteUser/{id} | Без Authorize |
|
||||
| GET | /api/admin/Users/all | Любой аутентифицированный пользователь |
|
||||
| GET | /api/admin/Users/{id} | Любой аутентифицированный пользователь |
|
||||
| GET | /api/admin/Users/user/{id}/setpassword/{password} | Любой аутентифицированный пользователь |
|
||||
|
||||
CreateInvitationRequest: endDate, maxParticipants, isAdmin, description. Генератор возвращает строковый код в JSON (200). Списки приглашений возвращают id, description, isAdmin, maxParticipants, code, createdAt, endAt, isActive, participantCount.
|
||||
|
||||
Users/all фактически ограничен 50 записями без стабильной пагинации. Ответ UserResponse включает passwordHash, что недопустимо для клиентского контракта. Смена пароля выполняется GET и кладёт пароль в URL.
|
||||
|
||||
Эти маршруты нужно закрыть ролью Admin до публичного использования. Создание административного приглашения вместе с регистрацией позволяет получить роль Admin. Не подключайте их к пользовательскому интерфейсу.
|
||||
|
||||
## Группы
|
||||
|
||||
GET /invite/{code} задуман как вход в группу и требует Authorize. IGroupService не зарегистрирован в AddServices, а _currentUser не присваивается. Маршрут не является рабочим сценарием вступления.
|
||||
|
||||
GroupsHub пуст и не подключён MapHub. Административный FriendshipsController содержит только закомментированные действия, поэтому рабочих endpoints у него нет.
|
||||
|
||||
Наличие моделей ChatGroup/GroupMembership/GroupInvitation и проверки участия в групповом Send не подтверждает готовый продуктовый сценарий групп и каналов.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
Источник: [Govor.API/Controllers/AdminStuff/UsersController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/AdminStuff/UsersController.cs).
|
||||
|
||||
@@ -1,45 +1,26 @@
|
||||
# Аутентификация
|
||||
|
||||
## Последовательность
|
||||
|
||||
1. `POST /api/auth/register` либо `POST /api/auth/login` возвращает `{ refreshToken, accessToken }`.
|
||||
2. HTTP-запросы передают `Authorization: Bearer <accessToken>`.
|
||||
3. Для SignalR задайте AccessTokenProvider, который возвращает актуальный access token. Program.cs также принимает query `access_token` на путях /hubs.
|
||||
4. `POST /api/auth/token/refresh` возвращает новую пару; клиент сохраняет новый refresh token.
|
||||
5. Отзыв сессий выполняется методами /api/Session/close.
|
||||
|
||||
Access token содержит `userId`, `sid` и роль User/Admin. Подпись HS256 проверяется, срок проверяется, issuer и audience не проверяются. Токены возвращаются JSON; сервер не устанавливает HttpOnly-cookie.
|
||||
|
||||
## Ограничения реализации
|
||||
|
||||
Отзыв сессии блокирует refresh, но Program.cs не проверяет IsRevoked при каждом использовании access token. Уже открытые SignalR-соединения явно не разрываются. Немедленный logout на всех устройствах не гарантирован.
|
||||
|
||||
Refresh JWT содержит userId и tokenType, но не случайный jti или sid. При выпуске одному пользователю в одну секунду возможны одинаковые токены, конфликтующие с уникальным RefreshTokenHash. Ротация не защищена атомарным compare-and-swap от параллельных запросов.
|
||||
|
||||
Не используйте refresh token как access token. В bearer-валидации нет явного требования tokenType=access; методы с одним Authorize требуют исправления разделения типов токенов.
|
||||
|
||||
На MAUI рекомендовано хранить refresh token в SecureStorage и выполнять обновление последовательно. Это рекомендация клиенту, а не свойство сервера.
|
||||
|
||||
---
|
||||
description: How to work with jwt tokens
|
||||
icon: user
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
# Authentication
|
||||
|
||||
### <mark style="color:$info;">Components</mark>
|
||||
|
||||
* **AuthController**: Handles registration and login.
|
||||
* **Route**: `/api/auth`
|
||||
* **RefreshController**: Manages token refresh.
|
||||
* **Route**: `/api/auth/token`
|
||||
|
||||
### <mark style="color:$info;">Authentication Process</mark>
|
||||
|
||||
* **Registration**:
|
||||
* **Endpoint**: `POST /api/auth/register`
|
||||
* **Input**: `RegistrationRequest` (name, password, inviteLink, deviceInfo)
|
||||
* **Output**: Access token
|
||||
* **Action**: Validates invite, registers user, opens session.
|
||||
* **Login**:
|
||||
* **Endpoint**: `POST /api/auth/login`
|
||||
* **Input**: `LoginRequest` (name, password, deviceInfo)
|
||||
* **Output**: Access token
|
||||
* **Action**: Authenticates user, opens session.
|
||||
* **Token Refresh**:
|
||||
* **Endpoint**: `POST /api/auth/token/refresh`
|
||||
* **Input**: `RefreshTokenRequest` (refreshToken)
|
||||
* **Output**: `RefreshTokenResponse` (accessToken, refreshToken)
|
||||
* **Action**: Refreshes expired access token.
|
||||
|
||||
### <mark style="color:$info;">Token Usage</mark>
|
||||
|
||||
* **Access Token**:
|
||||
* **Request**: Obtain during registration or login.
|
||||
* **Refresh**: Request via `/api/auth/token/refresh` when expired (e.g., 02:12 PM CEST, July 21, 2025).
|
||||
* **Refresh Token**:
|
||||
* **Request**: Received during registration or login.
|
||||
* **Refresh**: Use to obtain new access token when current one expires.
|
||||
|
||||
### Security
|
||||
|
||||
* **Protocol**: Requires HTTPS.
|
||||
* **Storage**: Store refresh token in HTTP-only cookie with `Secure` and `SameSite=Strict`.
|
||||
Источник: [Govor.Application/Authentication/JWT/JwtService.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.Application/Authentication/JWT/JwtService.cs).
|
||||
|
||||
@@ -1,141 +1,45 @@
|
||||
# Регистрация и вход
|
||||
|
||||
Оба метода доступны анонимно, Content-Type: application/json.
|
||||
|
||||
## POST /api/auth/register
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Артём",
|
||||
"password": "example-password",
|
||||
"inviteLink": "<код приглашения>",
|
||||
"deviceInfo": "Android test device"
|
||||
}
|
||||
```
|
||||
|
||||
Имя: 4–44 символа, только кириллица и цифры, первый символ — буква. Модерация запрещает зарезервированные имена, совпадения/подстроки из конфигурации и пять одинаковых символов подряд. Пароль: минимум 8 символов. DeviceInfo необязателен в запросе, но в БД ограничен 256 символами.
|
||||
|
||||
Код создаётся как Guid.ToString("N"): 32 символа без дефисов. Поиск кода — по строковому равенству. InviteLink — код, а не URL.
|
||||
|
||||
Проверяется существование приглашения, срок и число участников. Проверка IsActive отсутствует, лимит участников не защищён от конкурентной регистрации.
|
||||
|
||||
Успех 200:
|
||||
|
||||
```json
|
||||
{"refreshToken":"<token>","accessToken":"<token>"}
|
||||
```
|
||||
|
||||
Конфликт имени — 409; ошибки валидации — 400; отсутствующее приглашение — 404. Тело сервисных ошибок — ProblemDetails с errorCode. Регистрация и открытие сессии — отдельные сохранения: ошибка открытия сессии не откатывает созданного пользователя.
|
||||
|
||||
## POST /api/auth/login
|
||||
|
||||
```json
|
||||
{"name":"Артём","password":"example-password","deviceInfo":"Android test device"}
|
||||
```
|
||||
|
||||
Успех 200 с той же парой токенов. Пользователь не найден — 404 (UserNotRegisteredException); неверный пароль — 400 (InvalidOperationException). Это текущее поведение, а не рекомендуемая политика ошибок входа: разные ответы раскрывают существование аккаунта.
|
||||
|
||||
## Ограничения
|
||||
|
||||
Rate limiting и блокировка перебора в Program.cs не настроены. Для публичного запуска нужны единая ошибка входа, ограничение частоты и защита административных приглашений.
|
||||
|
||||
---
|
||||
description: >-
|
||||
Controller for handling user authentication operations, including registration
|
||||
and login, with session management and invite-based registration.
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
# AuthController
|
||||
|
||||
### Controller Description
|
||||
|
||||
* **Route**: `api/auth`
|
||||
* **Authorize**: Allows anonymous access (`[AllowAnonymous]`).
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### <mark style="color:$info;">Register</mark>
|
||||
|
||||
* **Description**: Registers a new user using a valid invite link and opens a user session, returning an authentication token.
|
||||
* **Route**: `[POST] api/auth/register`
|
||||
* **HTTP Method**: `POST`
|
||||
* **Request**:
|
||||
* **Content-Type**: `application/json`
|
||||
* **Request Body**: `RegistrationRequest` object with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string",
|
||||
"password": "string",
|
||||
"inviteLink": "string",
|
||||
"deviceInfo": "string"
|
||||
}
|
||||
```
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns the authentication token upon successful registration and session creation.
|
||||
|
||||
```json
|
||||
{
|
||||
"refreshToken": "string",
|
||||
"accessToken": "string"
|
||||
}
|
||||
```
|
||||
* <mark style="color:$danger;">**400 Bad Request**</mark>:
|
||||
* If model validation fails.
|
||||
* If the user already exists: `"Registration failed: user already exists."`
|
||||
* If the invite link is invalid: `"Invite link invalid."`
|
||||
* If the username is invalid: `"Invalid username: <error_message>"`
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"An unexpected error occurred. Please try again later."
|
||||
```
|
||||
|
||||
#### <mark style="color:$info;">Login</mark>
|
||||
|
||||
* **Description**: Authenticates an existing user and opens a session, returning an authentication token.
|
||||
* **Route**: `[POST] api/auth/login`
|
||||
* **HTTP Method**: `POST`
|
||||
* **Request**:
|
||||
* **Content-Type**: `application/json`
|
||||
* **Request Body**: `LoginRequest` object with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string",
|
||||
"password": "string",
|
||||
"deviceInfo": "string"
|
||||
}
|
||||
```
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns the authentication token upon successful login and session creation.
|
||||
|
||||
```json
|
||||
{
|
||||
"refreshToken": "string",
|
||||
"accessToken": "string"
|
||||
}
|
||||
```
|
||||
* <mark style="color:$danger;">**400 Bad Request**</mark>:
|
||||
* If model validation fails.
|
||||
* If the user does not exist: `"Login failed: user does not exist."`
|
||||
* If the username or password is incorrect: `"Login failed: username or password is incorrect."`
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"An unexpected error occurred. Please try again later."
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
#### RegistrationRequest
|
||||
|
||||
* **Description**: Model for registration request data.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string",
|
||||
"password": "string",
|
||||
"inviteLink": "string",
|
||||
"deviceInfo": "string"
|
||||
}
|
||||
```
|
||||
|
||||
#### LoginRequest
|
||||
|
||||
* **Description**: Model for login request data.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string",
|
||||
"password": "string",
|
||||
"deviceInfo": "string"
|
||||
}
|
||||
```
|
||||
|
||||
#### RefreshResult
|
||||
|
||||
* **Description**: Model for refresh token response data.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"refreshToken": "string",
|
||||
"accessToken": "string"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **Invalid User ID**: Not applicable (handled by session service).
|
||||
* **Invalid Operations**: Registration fails if the user already exists, invite link is invalid, or username is invalid, returning `400 Bad Request`.
|
||||
* **Unauthorized Access**: Not applicable (endpoint is `[AllowAnonymous]`).
|
||||
* **Unexpected Errors**: General exceptions are caught, logged, and returned as `500 Internal Server Error`.
|
||||
|
||||
### Logging
|
||||
|
||||
* Logs successful registration and login events with username and user ID.
|
||||
* Logs session opening events with username and user ID.
|
||||
* Logs warnings for specific exceptions (e.g., user already exists, invalid invite link, login failures).
|
||||
* Logs errors for unexpected exceptions during registration and login.
|
||||
Источник: [Govor.API/Controllers/Authentication/AuthController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/Authentication/AuthController.cs).
|
||||
|
||||
@@ -1,90 +1,36 @@
|
||||
# Обновление токенов
|
||||
|
||||
## POST /api/auth/token/refresh
|
||||
|
||||
Доступ анонимный. JSON:
|
||||
|
||||
```json
|
||||
{"refreshToken":"<последний сохранённый refresh token>"}
|
||||
```
|
||||
|
||||
Сервис хеширует переданную строку и ищет UserSession по RefreshTokenHash. Проверяет IsRevoked и ExpiresAt, выпускает новую пару, заменяет хеш и продлевает ExpiresAt. CreatedAt также перезаписывается, поэтому после refresh это не исходная дата открытия сессии.
|
||||
|
||||
Успех 200:
|
||||
|
||||
```json
|
||||
{"refreshToken":"<new token>","accessToken":"<new token>"}
|
||||
```
|
||||
|
||||
| Случай | Текущий ответ |
|
||||
| --- | --- |
|
||||
| Пустая строка | 400, errorCode Auth.EmptyToken |
|
||||
| Хеш не найден | 400, errorCode Auth.InvalidToken |
|
||||
| Истекшая/отозванная сессия | 400, errorCode Auth.InvalidToken |
|
||||
|
||||
Не документируйте неверный refresh как гарантированный 401: текущий Error.Failure преобразуется в 400.
|
||||
|
||||
## Клиент
|
||||
|
||||
Сохраните оба новых токена и сериализуйте refresh-запросы. Ошибка сети не должна автоматически удалять авторизацию пользователя. При подтверждённо недействительном refresh требуется повторный вход.
|
||||
|
||||
Ротация сейчас не имеет защиты от конкурентного использования и истории повторного применения. Детали — в разделе «Аутентификация».
|
||||
|
||||
---
|
||||
description: >-
|
||||
Controller for managing token refresh operations, allowing users to refresh
|
||||
their access tokens using a valid refresh token.
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
# RefreshController
|
||||
|
||||
### Controller Description
|
||||
|
||||
* **Route**: `api/auth/token`
|
||||
* **Authorize**: Allows anonymous access (`[AllowAnonymous]`).
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### <mark style="color:$info;">Refresh</mark>
|
||||
|
||||
* **Description**: Refreshes an access token using a provided refresh token and returns a new access token and refresh token pair.
|
||||
* **Route**: `[POST] api/auth/token/refresh`
|
||||
* **HTTP Method**: `POST`
|
||||
* **Request**:
|
||||
* **Content-Type**: `application/json`
|
||||
* **Request Body**: `RefreshTokenRequest` object with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"refreshToken": "string"
|
||||
}
|
||||
```
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns a new access token and refresh token upon successful refresh.
|
||||
|
||||
```json
|
||||
{
|
||||
"accessToken": "string",
|
||||
"refreshToken": "string"
|
||||
}
|
||||
```
|
||||
* <mark style="color:$warning;">**400 Bad Request**</mark>: If model validation fails or the refresh token is empty.
|
||||
|
||||
```json
|
||||
"Refresh token cant be empty."
|
||||
```
|
||||
* <mark style="color:$warning;">**401 Unauthorized**</mark>: If the refresh token is invalid or authorization fails.
|
||||
|
||||
```json
|
||||
"Invalid refresh token"
|
||||
```
|
||||
* <mark style="color:$danger;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"An unexpected error occurred."
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
#### RefreshTokenRequest
|
||||
|
||||
* **Description**: Model for refresh token request data.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"refreshToken": "string"
|
||||
}
|
||||
```
|
||||
|
||||
#### RefreshTokenResponse
|
||||
|
||||
* **Description**: Model for refresh token response data.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"accessToken": "string",
|
||||
"refreshToken": "string"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **Invalid User ID**: Not applicable (handled by session service).
|
||||
* **Invalid Operations**: Returns `400 Bad Request` if the refresh token is empty or invalid.
|
||||
* **Unauthorized Access**: Returns `401 Unauthorized` if the refresh token fails authorization.
|
||||
* **Unexpected Errors**: General exceptions are caught, logged, and returned as `500 Internal Server Error`.
|
||||
|
||||
### Logging
|
||||
|
||||
* Logs warnings for invalid or failed refresh token attempts.
|
||||
* Logs errors for unexpected exceptions during token refresh.
|
||||
Источник: [Govor.Application/Users/UserSessions/UserSessionRefresher.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.Application/Users/UserSessions/UserSessionRefresher.cs).
|
||||
|
||||
@@ -1,259 +1,44 @@
|
||||
# История сообщений
|
||||
|
||||
Требуется роль User/Admin.
|
||||
|
||||
| Метод | Маршрут | Идентификатор |
|
||||
| --- | --- | --- |
|
||||
| GET | /api/user/{userId}/messages | В userId передаётся **ID PrivateChat** |
|
||||
| GET | /api/groups/{groupId}/messages | ID ChatGroup |
|
||||
|
||||
Query: StartMessageId (Guid?, необязателен), Before=20, After=2. Before и After неотрицательные, сумма ≤100.
|
||||
|
||||
Без StartMessageId возвращаются последние Before сообщений, упорядоченные по SentAt по возрастанию; After не используется. С якорем возвращаются Before старых, якорное сообщение и After новых: максимум 101 запись. Неизвестный якорь — [].
|
||||
|
||||
Успех 200, MessageResponse[]:
|
||||
|
||||
```json
|
||||
[{
|
||||
"id":"11111111-1111-1111-1111-111111111111",
|
||||
"senderId":"22222222-2222-2222-2222-222222222222",
|
||||
"recipientId":"33333333-3333-3333-3333-333333333333",
|
||||
"recipientType":0,
|
||||
"encryptedContent":"<строка>",
|
||||
"sentAt":"2026-10-03T00:00:00Z",
|
||||
"isEdited":false,
|
||||
"editedAt":null,
|
||||
"replyToMessageId":null,
|
||||
"mediaAttachments":[],
|
||||
"reactions":[],
|
||||
"messageViews":[]
|
||||
}]
|
||||
```
|
||||
|
||||
У HTTP-ответа поле id; у SignalR UserMessageResponse — messageId. Вложения HTTP имеют id, messageId, mediaFileId.
|
||||
|
||||
## Известные проблемы
|
||||
|
||||
Личный загрузчик принимает currentUser, но не проверяет участие в указанном чате. Это критичная ошибка доступа. Для группы участие проверяется; неучастнику возвращается [].
|
||||
|
||||
Пагинация сравнивает только SentAt: сообщения с одинаковой датой могут выпадать вокруг якоря. Reactions и MessageViews не включаются явным Include, поэтому эти массивы не являются надёжным источником состояния. Нужны проверки доступа и стабильный курсор (SentAt, Id).
|
||||
|
||||
---
|
||||
description: Controller for loading chat messages for users and groups with pagination.
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
# ChatLoadController
|
||||
|
||||
### Controller Description
|
||||
|
||||
* **Route**: `api/chats`
|
||||
* **Authorize**: Requires authenticated user with roles "Admin" or "User" (`[Authorize(Roles = "Admin, User")]`).
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### <mark style="color:$info;">GetGroupMessages</mark>
|
||||
|
||||
* **Description**: Retrieves messages from a specified group chat with pagination.
|
||||
* **Route**: `[GET] api/chats/group-messages`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**:
|
||||
* **Path Parameter**: `chatId` (Guid, required): ID of the group chat.
|
||||
* **Query Parameter**: `query` (`MessageQuery`, required) with:
|
||||
* `startMessageId` (Guid?, optional): ID of the starting message.
|
||||
* `before` (int, default=20): Number of messages before the start.
|
||||
* `after` (int, default=2): Number of messages after the start.
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns a list of group chat messages.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "Guid",
|
||||
"senderId": "Guid",
|
||||
"recipientId": "Guid",
|
||||
"recipientType": "string",
|
||||
"encryptedContent": "string",
|
||||
"sentAt": "DateTime",
|
||||
"isEdited": "boolean",
|
||||
"editedAt": "DateTime?",
|
||||
"replyToMessageId": "Guid?",
|
||||
"mediaAttachments": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"mediaFileId": "Guid"
|
||||
}
|
||||
],
|
||||
"reactions": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"reactionCode": "string",
|
||||
"reactedAt": "DateTime"
|
||||
}
|
||||
],
|
||||
"messageViews": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"viewedAt": "DateTime"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
* <mark style="color:$danger;">**400 Bad Request**</mark>:
|
||||
* If `before` or `after` is negative or total exceeds 100: `"Values must be non-negative and total must not exceed 100."`
|
||||
* If an argument or resource is invalid: `"string"`
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"Unexpected Error! Please try again later."
|
||||
```
|
||||
|
||||
#### <mark style="color:$info;">GetUserMessages</mark>
|
||||
|
||||
* **Description**: Retrieves messages from a specified user chat with pagination.
|
||||
* **Route**: `[GET] api/chats/user-messages`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**:
|
||||
* **Path Parameter**: `userId` (Guid, required): ID of the target user.
|
||||
* **Query Parameter**: `query` (`MessageQuery`, required) with:
|
||||
* `startMessageId` (Guid?, optional): ID of the starting message.
|
||||
* `before` (int, default=20): Number of messages before the start.
|
||||
* `after` (int, default=2): Number of messages after the start.
|
||||
* **Responses**:
|
||||
* **200 OK**: Returns a list of user chat messages.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "Guid",
|
||||
"senderId": "Guid",
|
||||
"recipientId": "Guid",
|
||||
"recipientType": "string",
|
||||
"encryptedContent": "string",
|
||||
"sentAt": "DateTime",
|
||||
"isEdited": "boolean",
|
||||
"editedAt": "DateTime?",
|
||||
"replyToMessageId": "Guid?",
|
||||
"mediaAttachments": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"mediaFileId": "Guid"
|
||||
}
|
||||
],
|
||||
"reactions": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"reactionCode": "string",
|
||||
"reactedAt": "DateTime"
|
||||
}
|
||||
],
|
||||
"messageViews": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"viewedAt": "DateTime"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
* **400 Bad Request**:
|
||||
* If `before` or `after` is negative or total exceeds 100: `"Values must be non-negative and total must not exceed 100."`
|
||||
* If an operation or resource is invalid: `"string"`
|
||||
* **403 Forbidden**: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* **500 Internal Server Error**: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"Unexpected Error! Please try again later."
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
#### MessageQuery
|
||||
|
||||
* **Description**: Model for pagination query parameters.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"startMessageId": "Guid?",
|
||||
"before": "int",
|
||||
"after": "int"
|
||||
}
|
||||
```
|
||||
|
||||
#### MessageResponse
|
||||
|
||||
* **Description**: Data transfer object for chat message details.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "Guid",
|
||||
"senderId": "Guid",
|
||||
"recipientId": "Guid",
|
||||
"recipientType": "string",
|
||||
"encryptedContent": "string",
|
||||
"sentAt": "DateTime",
|
||||
"isEdited": "boolean",
|
||||
"editedAt": "DateTime?",
|
||||
"replyToMessageId": "Guid?",
|
||||
"mediaAttachments": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"mediaFileId": "Guid"
|
||||
}
|
||||
],
|
||||
"reactions": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"reactionCode": "string",
|
||||
"reactedAt": "DateTime"
|
||||
}
|
||||
],
|
||||
"messageViews": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"viewedAt": "DateTime"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### MediaAttachmentResponse
|
||||
|
||||
* **Description**: Data transfer object for media attachments in messages.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"mediaFileId": "Guid"
|
||||
}
|
||||
```
|
||||
|
||||
#### MessageReactionResponse
|
||||
|
||||
* **Description**: Data transfer object for message reactions.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"reactionCode": "string",
|
||||
"reactedAt": "DateTime"
|
||||
}
|
||||
```
|
||||
|
||||
#### MessageViewResponse
|
||||
|
||||
* **Description**: Data transfer object for message view tracking.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"viewedAt": "DateTime"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **Invalid User ID**: Handled by `ICurrentUserService`, aborts if invalid.
|
||||
* **Invalid Operations**: Returns `400 Bad Request` for negative values, total exceeding 100, or `InvalidOperationException`.
|
||||
* **Unauthorized Access**: Returns `403 Forbidden` for `UnauthorizedAccessException`.
|
||||
* **Resource Not Found**: Returns `400 Bad Request` for `NotFoundException`.
|
||||
* **Unexpected Errors**: Caught and returned as `500 Internal Server Error`.
|
||||
|
||||
### Logging
|
||||
|
||||
* Logs warnings for `UnauthorizedAccessException`, `NotFoundException`, `ArgumentException`, and `InvalidOperationException`.
|
||||
* Logs errors for unexpected exceptions.
|
||||
Источник: [Govor.Application/Messages/MessagesLoader.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.Application/Messages/MessagesLoader.cs).
|
||||
|
||||
@@ -1,114 +1,30 @@
|
||||
# Друзья и поиск
|
||||
|
||||
Bearer token обязателен; отдельная роль в атрибуте не задана.
|
||||
|
||||
| Метод | Маршрут | Результат |
|
||||
| --- | --- | --- |
|
||||
| GET | /api/friends | UserDto[] друзей |
|
||||
| GET | /api/friends/search?query=Арт | UserDto[] результатов поиска |
|
||||
|
||||
```json
|
||||
[{
|
||||
"id":"11111111-1111-1111-1111-111111111111",
|
||||
"username":"Артём",
|
||||
"description":"",
|
||||
"wasOnline":"2026-10-03T00:00:00Z",
|
||||
"iconId":"00000000-0000-0000-0000-000000000000",
|
||||
"isOnline":false
|
||||
}]
|
||||
```
|
||||
|
||||
Пустой/пробельный query возвращает 400 строкой "Query cannot be empty". Успех — 200; серверные ошибки — 500 с объектом error. Не смешивайте UserDto и UserProfileDto: у второго нет wasOnline.
|
||||
|
||||
Изменение заявок выполняется через FriendsHub. HTTP-контроллер не содержит команды отправки, принятия и отклонения.
|
||||
|
||||
Статус isOnline зависит от состояния процесса и подключения к presence. Он не является гарантией доставки сообщений или фоновой доступности устройства.
|
||||
|
||||
---
|
||||
description: >-
|
||||
Description: Controller for managing friendship-related operations, including
|
||||
searching for users and retrieving the list of friends for the current user.
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
# FriendshipController
|
||||
|
||||
### Controller Description
|
||||
|
||||
* **Route**: `api/friends`
|
||||
* **Authorize**: Requires authenticated user (`[Authorize]`).
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### <mark style="color:$info;">Search</mark>
|
||||
|
||||
* **Description**: Searches for users based on a query string.
|
||||
* **Route**: `[GET] api/friends/search?query=`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**:
|
||||
* **Query Parameter**: `query` (string, required)
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns a list of matching users.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "Guid",
|
||||
"username": "string",
|
||||
"description": "string",
|
||||
"wasOnline": "DateTime",
|
||||
"iconId": "Guid"
|
||||
}
|
||||
]
|
||||
```
|
||||
* <mark style="color:$danger;">**400 Bad Request**</mark>: If the query is empty.
|
||||
|
||||
```json
|
||||
"Query cannot be empty"
|
||||
```
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Internal error during user search."
|
||||
}
|
||||
```
|
||||
|
||||
#### <mark style="color:$info;">GetFriends</mark>
|
||||
|
||||
* **Description**: Retrieves the list of friends for the authenticated user.
|
||||
* **Route**: `[GET] api/friends`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**: None
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns a list of the user's friends or an empty list if none.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "Guid",
|
||||
"username": "string",
|
||||
"description": "string",
|
||||
"wasOnline": "DateTime",
|
||||
"iconId": "Guid"
|
||||
}
|
||||
]
|
||||
```
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Internal server error."
|
||||
}
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
#### UserDto
|
||||
|
||||
* **Description**: Data transfer object for user information.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "Guid",
|
||||
"username": "string",
|
||||
"description": "string",
|
||||
"wasOnline": "DateTime",
|
||||
"iconId": "Guid"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **Invalid User ID**: Handled by `ICurrentUserService`, aborts if invalid.
|
||||
* **Invalid Operations**: Returns `400 Bad Request` for empty query.
|
||||
* **Unexpected Errors**: Caught and returned as `500 Internal Server Error`.
|
||||
|
||||
### Logging
|
||||
|
||||
* Logs warnings for `SearchUsersException`.
|
||||
* Logs errors for unexpected exceptions and `InvalidOperationException`.
|
||||
Источник: [Govor.API/Controllers/Friends/FriendshipController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/Friends/FriendshipController.cs).
|
||||
|
||||
@@ -1,109 +1,26 @@
|
||||
# Списки заявок в друзья
|
||||
|
||||
Оба маршрута требуют Bearer token и возвращают 200 с FriendshipDto[].
|
||||
|
||||
| Метод | Маршрут | Назначение |
|
||||
| --- | --- | --- |
|
||||
| GET | /api/friends/requests | Входящие заявки |
|
||||
| GET | /api/friends/responses | Исходящие записи, кроме Accepted (включая Pending, Rejected, Blocked) |
|
||||
|
||||
```json
|
||||
[{
|
||||
"id":"11111111-1111-1111-1111-111111111111",
|
||||
"requesterId":"22222222-2222-2222-2222-222222222222",
|
||||
"addresseeId":"33333333-3333-3333-3333-333333333333",
|
||||
"status":0
|
||||
}]
|
||||
```
|
||||
|
||||
FriendshipStatus сериализуется числом: Pending=0, Accepted=1, Rejected=2, Blocked=3. id — идентификатор заявки/дружбы; именно он передаётся в AcceptRequest и RejectRequest.
|
||||
|
||||
При отсутствии записей — пустой массив. Ошибки контроллера — 500 с {"error":"Internal server error."}. Для восстановления после reconnect перечитайте списки: события не являются журналом гарантированной доставки.
|
||||
|
||||
---
|
||||
description: >-
|
||||
Description: Controller for querying friend request-related data, including
|
||||
incoming friend requests and responses to sent friend requests.
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
# FriendsRequestQueryController
|
||||
|
||||
### Controller Description
|
||||
|
||||
* **Route**: `api/friends`
|
||||
* **Authorize**: Requires authenticated user (`[Authorize]`).
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### <mark style="color:$info;">GetIncomingRequests</mark>
|
||||
|
||||
* **Description**: Retrieves a list of incoming friend requests for the authenticated user.
|
||||
* **Route**: `[GET] api/friends/requests`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**: None
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns a list of incoming friend requests or an empty list if none.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "Guid",
|
||||
"senderId": "Guid",
|
||||
"receiverId": "Guid",
|
||||
"status": "string",
|
||||
"createdAt": "DateTime"
|
||||
}
|
||||
]
|
||||
```
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Internal server error."
|
||||
}
|
||||
```
|
||||
|
||||
#### <mark style="color:$info;">GetResponses</mark>
|
||||
|
||||
* **Description**: Retrieves a list of responses to the authenticated user's sent friend requests.
|
||||
* **Route**: `[GET] api/friends/responses`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**: None
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns a list of friend request responses or an empty list if none.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "Guid",
|
||||
"senderId": "Guid",
|
||||
"receiverId": "Guid",
|
||||
"status": "string",
|
||||
"createdAt": "DateTime"
|
||||
}
|
||||
]
|
||||
```
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Internal server error."
|
||||
}
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
#### FriendshipDto
|
||||
|
||||
* **Description**: Data transfer object for friend request information.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "Guid",
|
||||
"senderId": "Guid",
|
||||
"receiverId": "Guid",
|
||||
"status": "string",
|
||||
"createdAt": "DateTime"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **Invalid User ID**: Handled by `ICurrentUserService`, aborts if invalid.
|
||||
* **Invalid Operations**: Returns `200 OK` with an empty list for `InvalidOperationException`.
|
||||
* **Unexpected Errors**: Caught and returned as `500 Internal Server Error`.
|
||||
|
||||
### Logging
|
||||
|
||||
* Logs warnings for `InvalidOperationException`.
|
||||
* Logs information for successful response retrieval.
|
||||
* Logs errors for unexpected exceptions.
|
||||
Источник: [Govor.API/Controllers/Friends/FriendsRequestQueryController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/Friends/FriendsRequestQueryController.cs).
|
||||
|
||||
@@ -1,107 +1,42 @@
|
||||
# Медиа
|
||||
|
||||
Требуется роль User/Admin.
|
||||
|
||||
## POST /api/media/upload
|
||||
|
||||
Content-Type: multipart/form-data. Поля:
|
||||
|
||||
| Поле | Тип | Назначение |
|
||||
| --- | --- | --- |
|
||||
| FromFile | файл | Непустое содержимое |
|
||||
| Type | число | Image=0, Video=1, Audio=2, File=3, Voice=4 |
|
||||
| MimeType | строка ≤255 | MIME типа файла |
|
||||
| EncryptedKey | строка | Обязательное поле запроса; сохранение ключа не реализовано |
|
||||
| OwnerType | число | Message=0, Avatar=1, GroupAvatar=2, System=3 |
|
||||
|
||||
Ограничение запроса — 20 000 000 байт, включая multipart; проверка файла также ≤20 000 000. Не следует обещать загрузку файла ровно этого размера: overhead тоже входит в лимит.
|
||||
|
||||
Успех 200:
|
||||
|
||||
```json
|
||||
{"mediaId":"11111111-1111-1111-1111-111111111111","url":"2026/10/<имя файла>"}
|
||||
```
|
||||
|
||||
url — относительный путь хранилища, не публичный URL. Для скачивания используйте endpoint.
|
||||
|
||||
## GET /api/media/download/{id}
|
||||
|
||||
Проверяет HasAccessAsync, затем возвращает бинарный файл с MIME и Content-Disposition. Если доступа нет или запись не найдена — 403, потому что проверка доступа выполняется первой. Сервисные ошибки — через ResultExtensions.
|
||||
|
||||
## Ограничения
|
||||
|
||||
Для личного сообщения accesser сравнивает Message.RecipientId с userId, хотя там ID чата: получатель может получить 403. При Send принадлежность вложения загрузившему пользователю не проверяется. OwnerType задаёт клиент, включая публично доступный System, — нужна серверная политика владения.
|
||||
|
||||
EncryptedKey не хранится ни в MediaFile, ни в MediaAttachments. Нельзя обещать восстановление ключа из истории.
|
||||
|
||||
Файлы целиком буферизуются в памяти, MIME принимается от клиента. Запись файла и БД не атомарна: возможны файлы без записи. Очистка неиспользуемых загрузок и stream-based выдача требуют реализации.
|
||||
|
||||
---
|
||||
description: Controller for uploading and downloading media files.
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
# MediaController
|
||||
|
||||
### Controller Description
|
||||
|
||||
* **Route**: `api/media`
|
||||
* **Authorize**: Requires authenticated user with roles "User" or "Admin" (`[Authorize(Roles = "User,Admin")]`).
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### <mark style="color:$info;">Upload</mark>
|
||||
|
||||
* **Description**: Uploads a media file with associated metadata.
|
||||
* **Route**: `[POST] api/media/upload`
|
||||
* **HTTP Method**: `POST`
|
||||
* **Request**:
|
||||
* **Content-Type**: `multipart/form-data`
|
||||
* **Request Body**: `MediaUploadRequest` object with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"fromFile": "IFormFile",
|
||||
"type": "MediaType",
|
||||
"mimeType": "string",
|
||||
"encryptedKey": "string"
|
||||
}
|
||||
```
|
||||
* **Constraints**: File size limit of 20 MB.
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns the upload result.
|
||||
|
||||
```json
|
||||
"string" // Media ID or similar result
|
||||
```
|
||||
* <mark style="color:$danger;">**400 Bad Request**</mark>:
|
||||
* If model validation fails.
|
||||
* If no file is uploaded: `"No file uploaded"`
|
||||
* If file exceeds 20 MB: `"File is too large"`
|
||||
* If MIME type is missing: `"Missing MIME type"`
|
||||
* If operation is invalid: `"string"`
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"Internal server error"
|
||||
```
|
||||
|
||||
#### <mark style="color:$info;">Download</mark>
|
||||
|
||||
* **Description**: Downloads a media file by its ID.
|
||||
* **Route**: `[GET] api/media/download/{id}`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**:
|
||||
* **Path Parameter**: `id` (Guid, required): ID of the media file.
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns the media file as a stream.
|
||||
* **Content-Type**: Matches `MimeType` of the media.
|
||||
* **Content-Disposition**: Includes `filename` from `FileName`.
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks access.
|
||||
* No body.
|
||||
* <mark style="color:$danger;">**404 Not Found**</mark>: If media is not found.
|
||||
|
||||
```json
|
||||
"Media not found"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"Internal server error"
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
#### MediaUploadRequest
|
||||
|
||||
* **Description**: Model for media upload request data.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"fromFile": "IFormFile",
|
||||
"type": "MediaType",
|
||||
"mimeType": "string",
|
||||
"encryptedKey": "string"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **Invalid User ID**: Handled by `ICurrentUserService`, aborts if invalid.
|
||||
* **Invalid Operations**: Returns `400 Bad Request` for `InvalidOperationException`.
|
||||
* **Unauthorized Access**: Returns `403 Forbidden` for `UnauthorizedAccessException`.
|
||||
* **Resource Not Found**: Returns `404 Not Found` for `KeyNotFoundException`.
|
||||
* **Unexpected Errors**: Caught and returned as `500 Internal Server Error`.
|
||||
|
||||
### Logging
|
||||
|
||||
* Logs warnings for `UnauthorizedAccessException`, `InvalidOperationException`, and `KeyNotFoundException`.
|
||||
* Logs information for successful file uploads.
|
||||
* Logs errors for unexpected exceptions during upload and download.
|
||||
Источник: [Govor.API/Controllers/MediaController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/MediaController.cs).
|
||||
|
||||
@@ -0,0 +1,67 @@
|
||||
# Прочтение сообщений
|
||||
|
||||
Контракт реализован в рабочей копии сервера от 03.10.2026. Требуются access token, роль User/Admin и участие именно в запрошенном чате. `chatId` — ID PrivateChat либо ChatGroup, а не ID собеседника. `recipientType`: 0 — личный чат, 1 — группа.
|
||||
|
||||
## POST /api/chats/{chatId}/read
|
||||
|
||||
Три взаимоисключающих режима:
|
||||
|
||||
| Действие клиента | Тело запроса | Семантика |
|
||||
| --- | --- | --- |
|
||||
| Скролл, входящие сообщения видны на экране | `{"recipientType":0,"messageIds":["<id1>","<id2>"]}` | Прочитать только эти сообщения |
|
||||
| Пользователь просмотрел историю до определённого сообщения | `{"recipientType":0,"upToMessageId":"<id>"}` | Прочитать входящие до границы включительно |
|
||||
| Команда «Пометить как прочитано» | `{"recipientType":0}` | Зафиксировать последнюю границу и прочитать входящие до неё |
|
||||
|
||||
Граница упорядочена по `(sentAt, messageId)`: ID разрешает совпадающие timestamps. Сообщения после этой границы остаются непрочитанными. Свои сообщения не получают MessageView. В режиме messageIds передавайте только входящие: от 1 до 100 ID, без Guid.Empty. Список и upToMessageId нельзя объединять. Весь список проверяется до записи; ID из другого чата возвращает 404 без частичного прочтения. Отсутствие участия возвращает 403; неверная комбинация и собственные сообщения в списке — 400.
|
||||
|
||||
200 OK, JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"chatId":"<chat-id>",
|
||||
"recipientType":0,
|
||||
"readerId":"<current-user-id>",
|
||||
"readAt":"2026-10-03T07:00:00Z",
|
||||
"upToMessageId":null,
|
||||
"upToSentAt":null,
|
||||
"messageIds":["<incoming-id>"],
|
||||
"readCount":1,
|
||||
"unreadCount":3
|
||||
}
|
||||
```
|
||||
|
||||
Для режима границы messageIds=null, upToMessageId/upToSentAt заполнены. У пустого чата граница null. readCount — число новых записей данного вызова; повторный запрос возвращает 0 и не меняет время существующих MessageView. readAt — время операции; исходное время каждого прочтения доступно в истории, через messageViews. unreadCount относится к readerId в этом чате и включает все оставшиеся входящие сообщения на момент подсчёта.
|
||||
|
||||
Уникальный индекс `(MessageId, UserId)` и `ON CONFLICT DO NOTHING` защищают параллельные отметки с нескольких устройств. Получение истории само по себе ничего не помечает.
|
||||
|
||||
## GET /api/chats/{chatId}/unread-count?recipientType=0
|
||||
|
||||
200 OK: `{"unreadCount":3}`. Считает входящие без MessageView текущего пользователя. Те же требования авторизации и участия. Клиент использует endpoint после подключения/переподключения и для восстановления локального счётчика.
|
||||
|
||||
## SignalR
|
||||
|
||||
`ReadChat(Guid chatId, ReadChatRequest request)` на `/hubs/chats` выполняет ту же операцию, возвращает `HubResult<ChatReadResponse>`. После успешного HTTP или SignalR вызова сервер отправляет событие `ChatRead` с ChatReadResponse всем активным сессиям текущих участников, включая устройства читателя. Ошибки HubResult используют 400/401/403/404/500; это поле status, а не HTTP-статус WebSocket.
|
||||
|
||||
Старый `Read(ReadMessageRequest)` сохраняется. Он читает одно входящее сообщение и возвращает прежнюю квитанцию при повторении. Для совместимости отправляются `MessageReaded` и `MessageRead`; подпишитесь на одно из этих имён. Для массового прочтения используйте ChatRead.
|
||||
|
||||
## Использование в MAUI
|
||||
|
||||
Собирайте ID реально видимых входящих сообщений, отправляйте пачками до 100, объединяя частые события скролла. Отправляйте запрос только при активном окне чата. Обновляйте локальное состояние после успешного ответа; при потере сети повторяйте тот же список. Не отмечайте всю загруженную страницу как просмотренную, если она была вне экрана.
|
||||
|
||||
```csharp
|
||||
var request = new ReadChatRequest
|
||||
{
|
||||
RecipientType = RecipientType.User,
|
||||
MessageIds = visibleIncomingIds.Distinct().Take(100).ToList()
|
||||
};
|
||||
if (request.MessageIds.Count > 0)
|
||||
{
|
||||
var result = await connection.InvokeAsync<HubResult<ChatReadResponse>>(
|
||||
"ReadChat", chatId, request);
|
||||
// При успешном status примените result.Result и его UnreadCount.
|
||||
}
|
||||
```
|
||||
|
||||
Кнопка «Пометить как прочитано» передаёт `new ReadChatRequest { RecipientType = type }`. Событие ChatRead обновляет галочки у автора и состояние на остальных устройствах читателя. Оно не требует от других участников подтверждать прочтение. При отключённом SignalR восстановите messageViews через историю и счётчик через unread-count. На устройстве читателя отмените уведомление с tag `chat_<chatId>`, когда чат полностью прочитан.
|
||||
|
||||
ReceiveMessage и MessageSent могут описывать одно исходящее сообщение. Дедуплицируйте их по messageId; счётчик увеличивается только для новых входящих.
|
||||
@@ -1,50 +1,19 @@
|
||||
# HTTP-присутствие — ограничения
|
||||
|
||||
Требуется роль User/Admin.
|
||||
|
||||
| Метод | Маршрут | Текущее поведение |
|
||||
| --- | --- | --- |
|
||||
| PATCH | /api/online/ping | Вызывает PingHandlerService, успех 200 без тела |
|
||||
| GET | /api/online/status/{userId} | Неработоспособен: 500 |
|
||||
|
||||
В конструкторе не присваиваются _userOnlineStore и _presenceReader. GetStatus обращается к null; catch возвращает 500 "Internal server error.".
|
||||
|
||||
Задуманное тело status — { isOnline, lastSeen }, но сейчас его нельзя считать рабочим контрактом.
|
||||
|
||||
Для событий online/offline подключайтесь к /hubs/presence. Ping и наличие SignalR-подключения — разные механизмы; требуется единая политика lastSeen/TTL. Не считайте HTTP ping подтверждением активного presence-соединения.
|
||||
|
||||
---
|
||||
description: >-
|
||||
Description: Controller for handling user online status updates by processing
|
||||
ping requests.
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
# OnlinePingingController(не работает)
|
||||
|
||||
**Route**: `api/online`\
|
||||
**Authorize**: Requires "User" or "Admin" role
|
||||
|
||||
### <mark style="color:purple;">End Point {PATCH}</mark>
|
||||
|
||||
`[PATCH] api/online/ping`
|
||||
|
||||
#### Description
|
||||
|
||||
Updates the online status of the current user by sending a ping request.
|
||||
|
||||
**Request**
|
||||
|
||||
* **Content-Type**: `application/json`
|
||||
* **Request Body**: None
|
||||
|
||||
**Responses**
|
||||
|
||||
* **200 OK**: Ping processed successfully.
|
||||
|
||||
```json
|
||||
{}
|
||||
```
|
||||
* **400 Bad Request**: If the user cannot be found in the database.
|
||||
|
||||
```json
|
||||
"User can't be found in our database."
|
||||
```
|
||||
* **403 Forbidden**: If the user is not authorized to perform the action.
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Not authorized to perform this action."
|
||||
}
|
||||
```
|
||||
* **500 Internal Server Error**: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Failed to send friend request."
|
||||
}
|
||||
```
|
||||
Источник: [Govor.API/Controllers/OnlinePingingController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/OnlinePingingController.cs).
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# Личные чаты
|
||||
|
||||
Требуется роль User/Admin.
|
||||
|
||||
| Метод | Маршрут | Успех |
|
||||
| --- | --- | --- |
|
||||
| GET | /api/user/{friendId}/private-chat | 200, Guid чата в JSON |
|
||||
| GET | /api/user/private-chats | 200, PrivateChatDto[] |
|
||||
|
||||
Первый метод проверяет дружбу, возвращает существующий чат либо создаёт новый. Это побочный эффект GET; рекомендуемый будущий контракт — POST, но маршрут пока не изменён.
|
||||
|
||||
```json
|
||||
[{
|
||||
"chatId":"11111111-1111-1111-1111-111111111111",
|
||||
"friendId":"22222222-2222-2222-2222-222222222222"
|
||||
}]
|
||||
```
|
||||
|
||||
При принятии заявки FriendRequestCommandService также создаёт личный чат и добавляет текущие соединения участников в SignalR-группу.
|
||||
|
||||
Используйте chatId в Send.recipientId и в /api/user/{userId}/messages. Несмотря на имя параметра userId, загрузчик ожидает ID PrivateChat.
|
||||
|
||||
Ошибки дружбы передаются через Forbid(ex.Message), что ошибочно трактует сообщение как имя схемы аутентификации и может дать 500. Параллельное создание и повторное присоединение после частичного сбоя требуют отдельной проверки.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
Источник: [Govor.API/Controllers/PrivateChatController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/PrivateChatController.cs).
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# Профиль и аватар
|
||||
|
||||
Требуется роль User/Admin.
|
||||
|
||||
| Метод | Маршрут | Успех |
|
||||
| --- | --- | --- |
|
||||
| GET | /api/profile/download/me | 200, UserProfileDto текущего пользователя |
|
||||
| GET | /api/profile/download/{id} | 200, UserProfileDto указанного пользователя |
|
||||
| POST | /api/profile/avatar | 200, MediaUploadResult |
|
||||
|
||||
UserProfileDto: id, username, description (nullable), iconId (nullable), isOnline. Отсутствующий пользователь — 404 ProblemDetails.
|
||||
|
||||
Загрузка аватара: multipart/form-data с FromFile, Type, MimeType. В отличие от MediaController, отдельный лимит 20 MB не задан; действуют ограничения хоста. Контроллер сохраняет медиа с OwnerType.Avatar и устанавливает IconId.
|
||||
|
||||
Описание изменяется через ProfileHub.SetDescription. ProfileHub.SetAvatar принимает существующий iconId и рассылает AvatarUpdated.
|
||||
|
||||
## Ограничения
|
||||
|
||||
REST UploadAvatar не рассылает AvatarUpdated. Клиентам может потребоваться отдельное обновление данных. В ProfileHub.SetAvatar проверяется существование файла, но не его загрузчик/тип/владелец.
|
||||
|
||||
Хаб игнорирует Result от SetDescription и SetNewIcon, поэтому успех true не всегда подтверждает изменение. MappingProfile дважды регистрирует UserProfile → UserProfileDto; это нужно устранить и проверить isOnline.
|
||||
|
||||
Чтение чужого профиля не применяет PrivacyUserSettings. Наличие моделей приватности не означает действующую политику доступа.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
Источник: [Govor.API/Controllers/ProfileController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/ProfileController.cs).
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# Push-уведомления
|
||||
|
||||
## POST /api/pushes/token/register
|
||||
|
||||
Требуется роль User/Admin. JSON:
|
||||
|
||||
```json
|
||||
{"token":"<FCM registration token>","platform":"Android"}
|
||||
```
|
||||
|
||||
Сервис связывает токен с userId и sid текущего access token, добавляет или обновляет запись. Успех Unit — 204. Пустой token/platform отклоняется 400; тело BadRequest(ModelState) не всегда содержит полезное объяснение.
|
||||
|
||||
При отзыве сессии связанные токены деактивируются. В DI зарегистрирован FirebasePushProvider; credentials читаются при старте приложения.
|
||||
|
||||
## Отправка
|
||||
|
||||
Личные сообщения вызывают отправку push собеседнику. title — имя отправителя; body — первые 40 символов EncryptedContent. Data содержит chatId и isGroup ("false"). Это текущая реализация: сервер не расшифровывает содержимое.
|
||||
|
||||
Для E2EE тело push должно быть нейтральным. Для текущего MAUI, отправляющего обычный текст, этот body раскрывает превью сообщения внешнему push-провайдеру.
|
||||
|
||||
## Доставка
|
||||
|
||||
Сохранение сообщения, SignalR и Firebase не образуют единую транзакцию. Ошибка после SaveChanges может дать ошибку Send, хотя сообщение уже записано. Автоматическое повторение без идентификатора клиентской операции может создать дубль. Нужны outbox, дедупликация и обработка недействительных FCM-токенов.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
Источник: [Govor.API/Hubs/Infrastructure/ChatNotificationService.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Hubs/Infrastructure/ChatNotificationService.cs).
|
||||
|
||||
@@ -0,0 +1,133 @@
|
||||
# Реакции, паки и настройки каналов
|
||||
|
||||
Контракт рабочей версии сервера от 03.10.2026. Все маршруты требуют Bearer **access** token и активную сессию. JSON использует camelCase, перечисления передаются числами. HTTP и SignalR вызывают один сервис с одинаковыми проверками доступа.
|
||||
|
||||
## Реакции сообщения
|
||||
|
||||
На одном сообщении пользователь может иметь одну реакцию: новая заменяет предыдущую. Изменять чужую реакцию нельзя; userId берётся из токена. Доступ имеют участники личного чата и незаблокированные участники группы/канала.
|
||||
|
||||
| Метод | Маршрут | Тело / результат |
|
||||
| --- | --- | --- |
|
||||
| GET | `/api/messages/{messageId}/reactions` | Снимок реакций |
|
||||
| PUT | `/api/messages/{messageId}/reactions/me` | `{ "reactionId": "<GUID>" }`; снимок |
|
||||
| DELETE | `/api/messages/{messageId}/reactions/me` | Без тела; снимок |
|
||||
|
||||
Успех — HTTP 200. Повтор PUT той же реакции и DELETE отсутствующей реакции идемпотентны: не повышают version и не отправляют событие. PUT требует активную реакцию активного пака. Ошибки: 400 — некорректный ID; 401 — нет активной access-сессии; 403 — нет доступа или запрещено настройками канала; 404 — сообщение/реакция недоступны.
|
||||
|
||||
Снимок и событие `MessageReactionsChanged` имеют одинаковый формат:
|
||||
|
||||
```json
|
||||
{
|
||||
"messageId": "11111111-1111-1111-1111-111111111111",
|
||||
"recipientId": "22222222-2222-2222-2222-222222222222",
|
||||
"recipientType": 0,
|
||||
"version": 3,
|
||||
"actorId": "33333333-3333-3333-3333-333333333333",
|
||||
"actorReaction": null,
|
||||
"counts": [
|
||||
{ "reactionId": "b3000000-0000-0000-0001-000000000001", "reactionCode": "👍", "count": 2 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
В GET actorId — текущий пользователь. В событии — пользователь, который изменил реакцию. actorReaction — его текущая MessageReactionResponse либо null после удаления. Не принимайте чужую actorReaction за свою. В counts передаётся полный снимок счётчиков, а не приращения. recipientType: 0 — личный чат (recipientId = PrivateChat.Id), 1 — группа/канал.
|
||||
|
||||
История сообщений содержит reactionsVersion и reactions с reactionId, reactionCode, userId и reactedAt. Старая неизвестная reactionCode может иметь reactionId=null; отображайте её как сохранённый код. Миграция связывает известные старые эмодзи с базовым паком.
|
||||
|
||||
## SignalR и синхронизация клиента
|
||||
|
||||
Подключение: `/hubs/chats`, обычный access token. Методы возвращают существующий `HubResult<T>` с status, result, errorMessage:
|
||||
|
||||
```csharp
|
||||
var result = await connection.InvokeAsync<HubResult<MessageReactionsChangedResponse>>(
|
||||
"React", messageId, new SetReactionRequest { ReactionId = reactionId });
|
||||
var removed = await connection.InvokeAsync<HubResult<MessageReactionsChangedResponse>>(
|
||||
"RemoveReaction", messageId);
|
||||
|
||||
connection.On<MessageReactionsChangedResponse>("MessageReactionsChanged", state =>
|
||||
{
|
||||
// На UI-потоке: принять более новую версию и заменить counts целиком.
|
||||
// actorReaction обновляет собственный выбор только при actorId == currentUserId.
|
||||
});
|
||||
connection.On<ChannelReactionPolicyResponse>("ChannelReactionPolicyChanged", policy =>
|
||||
{
|
||||
// Обновить разрешённые реакции канала по более новой version.
|
||||
});
|
||||
```
|
||||
|
||||
Событие после сохранения получают активные сессии обоих участников личного чата или незаблокированных участников группы, включая устройства автора изменения. Для этих событий push не отправляется. События SignalR не имеют долговременной очереди: после reconnect загрузите HTTP-снимки видимых сообщений и политику канала. Подпишитесь на события до загрузки истории и сравнивайте version отдельно для каждого сообщения, чтобы запоздавший ответ не затёр новое состояние. Ответ команды и событие могут дублировать одну версию.
|
||||
|
||||
## Каталог, установка и обмен
|
||||
|
||||
Базовый пак Emoji доступен каждому автоматически, не требует установки и не отключается. Его ID — `b3000000-0000-0000-0000-000000000001`; содержит 👍 👎 ❤️ 🔥 🥰 👏 😁 🤔 😢 🎉 🤯 🙏. Пользовательские паки публичны среди авторизованных пользователей. Установка добавляет пак в личный выбор; применять публичную реакцию можно и без установки.
|
||||
|
||||
| Метод | Маршрут | Назначение |
|
||||
| --- | --- | --- |
|
||||
| GET | `/api/reaction-packs?skip=0&take=50` | Активный каталог |
|
||||
| GET | `/api/reaction-packs/mine?skip=0&take=50` | Базовый и установленные паки |
|
||||
| GET | `/api/reaction-packs/{packId}` | Активный пак с активными реакциями |
|
||||
| GET | `/api/reaction-packs/shared/{shareCode}` | Открыть пак по коду обмена |
|
||||
| PUT | `/api/reaction-packs/{packId}/subscription` | Установить; HTTP 204 |
|
||||
| DELETE | `/api/reaction-packs/{packId}/subscription` | Удалить из выбора; HTTP 204 |
|
||||
| GET | `/api/reactions/{reactionId}` | Определение реакции, включая отключённую |
|
||||
| GET | `/api/reaction-packs/limits` | Лимиты файлов и пака |
|
||||
|
||||
skip >= 0, take от 1 до 100. Возвращается список паков. Каждый пак: id, name, description, shareCode, sharePath, isDefault, isEnabled, createdByUserId, createdAt, reactions. sharePath — относительный API-маршрут; клиент может передавать shareCode в своей deep link. Отдельного механизма отправки приглашения/сообщения сервер не добавляет.
|
||||
|
||||
Элемент reactions: id, packId, code, name, kind, emoji, mediaFileId, mediaUrl, width, height, sizeBytes, durationMilliseconds, isEnabled, createdAt. kind: Emoji=0, Image=1, Gif=2. Для файлов используйте mediaUrl (`/api/media/download/{id}`) с Bearer token. Файлы реакций доступны всем авторизованным пользователям, включая исторические файлы отключённых реакций. ID файла не даёт доступ к обычным закрытым вложениям чата.
|
||||
|
||||
При отображении незнакомого reactionId получите `/api/reactions/{reactionId}` и кешируйте определение/изображение. Идентичность и файл реакции неизменяемы; для замены изображения администратор создаёт новый элемент.
|
||||
|
||||
## Администрирование паков
|
||||
|
||||
Требуется роль Admin; операции изменения дополнительно проверяют административное приглашение пользователя в БД, согласно существующей модели прав проекта. Будущий бот может использовать эти маршруты с access-сессией административного пользователя. Выдача отдельной bot-учётной записи/токена пока не реализована.
|
||||
|
||||
| Метод | Маршрут | Тело |
|
||||
| --- | --- | --- |
|
||||
| GET | `/api/admin/reaction-packs?skip=0&take=50` | Каталог, включая отключённые паки и элементы |
|
||||
| GET | `/api/admin/reaction-packs/{packId}` | Пак, включая отключённые элементы |
|
||||
| POST | `/api/admin/reaction-packs` | `{ "name": "Cats", "description": "..." }` |
|
||||
| PUT | `/api/admin/reaction-packs/{packId}` | `{ "name": "Cats", "description": "...", "isEnabled": true }` |
|
||||
| DELETE | `/api/admin/reaction-packs/{packId}` | Мягкое отключение пака; 204 |
|
||||
| POST | `/api/admin/reaction-packs/{packId}/reactions/emoji` | `{ "name": "Cool", "emoji": "😎" }` |
|
||||
| POST | `/api/admin/reaction-packs/{packId}/reactions/media` | multipart/form-data: name и file |
|
||||
| DELETE | `/api/admin/reaction-packs/{packId}/reactions/{reactionId}` | Мягкое отключение элемента; 204 |
|
||||
|
||||
Создание/обновление возвращает HTTP 200 с DTO. name — 1–100 символов, description — до 500. До 100 элементов в паке, включая отключённые. Базовый пак и его элементы неизменяемы. Отключение исключает пак/элемент из выбора и запрещает новые реакции, но сохраняет ранее поставленные реакции и файлы; пользователь может снять свою старую реакцию. Отдельного события изменения каталога нет: обновляйте каталог при открытии выбора и после отказа установки реакции.
|
||||
|
||||
## Файлы
|
||||
|
||||
Формат определяется по содержимому: PNG, JPEG, WebP для статичных картинок; GIF для анимации. SVG и анимации других форматов отклоняются. Имя файла и заявленный MIME не определяют результат. Сервер декодирует, удаляет необязательные метаданные, уменьшает и заново кодирует файл. Картинки сохраняются как PNG, анимации как GIF.
|
||||
|
||||
| Ограничение | Значение |
|
||||
| --- | --- |
|
||||
| Исходный файл | До 2 МиБ, стороны до 2048 пикселей |
|
||||
| Результат | Обе стороны не больше 128 пикселей |
|
||||
| Картинка | До 256 КиБ |
|
||||
| GIF | До 512 КиБ, до 60 кадров, до 5 секунд за цикл |
|
||||
|
||||
Для достижения лимита размера сервер может уменьшить стороны до 96, 64 или 48 пикселей. Задержка кадра GIF нормализуется минимум до 20 мс; лимит длительности проверяется после нормализации. Слишком сложный/повреждённый файл возвращает 400; тело запроса выше транспортного лимита может вернуть 413.
|
||||
|
||||
Обработка использует SixLabors.ImageSharp 3.1.12 с Six Labors Split License; пакет не требует лицензионного ключа для сборки. Условия использования доступны в [пакете NuGet](https://www.nuget.org/packages/SixLabors.ImageSharp/3.1.12). Переход на ImageSharp 4 требует отдельно настроить build-time license key.
|
||||
|
||||
## Настройки канала
|
||||
|
||||
Группы с IsChannel=true поддерживают ограничения. Новые и существующие каналы после миграции используют All. Управлять политикой может незаблокированный участник, записанный в GroupAdmins этого канала; глобальная роль Admin сама по себе не даёт этих прав.
|
||||
|
||||
| Метод | Маршрут | Результат |
|
||||
| --- | --- | --- |
|
||||
| GET | `/api/groups/{groupId}/reactions` | Политика для участников |
|
||||
| PUT | `/api/groups/{groupId}/reactions` | `{ "mode": 2, "reactionIds": ["<GUID>"] }`; обновлённая политика |
|
||||
|
||||
mode: All=0 — все активные реакции; None=1 — новые реакции запрещены; Selected=2 — только выбранные ID (до 100). Для All/None reactionIds должен быть пустым. Пустой Selected запрещает все новые реакции. Выбираются только активные элементы активных паков. Результат: groupId, mode, version, reactionIds. После успешного PUT приходит ChannelReactionPolicyChanged. Обычная группа не поддерживает PUT политики (400). Изменение политики не удаляет историю; собственную реакцию разрешено снять при любом режиме.
|
||||
|
||||
## Обновление базы и проверка
|
||||
|
||||
Из корня серверного проекта:
|
||||
|
||||
```powershell
|
||||
dotnet ef database update --project Govor.Domain --startup-project Govor.API
|
||||
dotnet test Govor.Server.Tests/Govor.Server.Tests.csproj -c Release
|
||||
```
|
||||
|
||||
Миграция `20261003101700_ReactionPacksAndChannelPolicies` создаёт каталог, установки, разрешения канала, версии и базовый пак; старые реакции сохраняются. Она подготовлена, но к вашей рабочей БД автоматически не применялась. Локальные тесты используют SQLite и HTTP pipeline с JWT; SignalR-доставка проверяется через mock транспорта. CI также настроен на PostgreSQL. Реальные устройства/сокеты и PostgreSQL локально не проверены.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Ключи сессий — экспериментальный API
|
||||
|
||||
RequireHttps и роль User/Admin обязательны.
|
||||
|
||||
| Метод | Маршрут | Назначение |
|
||||
| --- | --- | --- |
|
||||
| POST | /api/session/keys | Привязать публичные ключи текущей сессии |
|
||||
| GET | /api/session/users/{userId}/keys | Получить ключи друга |
|
||||
| POST | /api/session/keys/rotate | Пополнить одноразовые ключи |
|
||||
| GET | /api/session/keys/remaining | { remaining: число } |
|
||||
| POST | /api/session/keys/{preKeyId}/used | Пометить собственный ключ использованным |
|
||||
|
||||
byte[] в JSON передаются строкой base64. UploadKeysRequest содержит identityKey, signedPreKey, signedPreKeySignature и oneTimePreKeys (массив base64). За запрос допускается максимум 100 одноразовых ключей. Сервис запрещает повторную привязку ключей к сессии и проверяет владельца.
|
||||
|
||||
RotateOneTimePreKeysRequest содержит newOneTimePreKeys. В реализации ротация удаляет использованные записи и добавляет новые, не ограничивая общий размер набора.
|
||||
|
||||
## Неработающие и небезопасные части
|
||||
|
||||
_oneTimePreKeysRotator не передан в конструктор SessionKeysController: rotate и used падают при обращении к null.
|
||||
|
||||
remaining считает все записи, включая IsUsed. Reader выдаёт все OneTimePreKeys и возвращает EF-сущности UserCryptoSession вместо PublicSessionKeysDto. Include(UserSession) может включить внутренние поля, а двусторонние навигации могут привести к циклу сериализации. SignedPreKey не включён явным Include.
|
||||
|
||||
Доступ к чужим ключам ограничен дружбой, но Forbid("текст") ошибочно используется как имя authentication scheme. Атомарной выдачи одного неиспользованного prekey потребителю нет: endpoint used относится к текущей сессии владельца.
|
||||
|
||||
## Статус E2EE
|
||||
|
||||
Это заготовка хранения ключей, не законченный криптографический протокол. Нет доказанной реализации обмена/проверки подписей, одноразового потребления, ratchet и поддержки шифрования на клиенте. Не используйте этот раздел как обещание сквозного шифрования.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
Источник: [Govor.API/Controllers/Authentication/SessionKeysController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/Authentication/SessionKeysController.cs).
|
||||
|
||||
@@ -1,157 +1,35 @@
|
||||
# Сессии
|
||||
|
||||
Все методы требуют Bearer access token с ролью User или Admin.
|
||||
|
||||
| Метод | Маршрут | Успех |
|
||||
| --- | --- | --- |
|
||||
| GET | /api/Session/all | 200, SessionDto[] |
|
||||
| DELETE | /api/Session/close/{sessionId} | 204, без тела |
|
||||
| DELETE | /api/Session/close | 204, закрыть sid текущего токена |
|
||||
| DELETE | /api/Session/close/all | 204, закрыть все сессии пользователя |
|
||||
|
||||
```json
|
||||
[{
|
||||
"id":"11111111-1111-1111-1111-111111111111",
|
||||
"deviceInfo":"Android test device",
|
||||
"createdAt":"2026-10-03T00:00:00Z",
|
||||
"expiresAt":"2026-10-10T00:00:00Z",
|
||||
"isRevoked":false
|
||||
}]
|
||||
```
|
||||
|
||||
Список фильтруется по UserId и !IsRevoked, но не по ExpiresAt; истекшие сессии могут присутствовать. CreatedAt меняется при refresh.
|
||||
|
||||
Закрытие чужой, неизвестной или уже отозванной сессии возвращает 404 с errorCode UserSession.NotFoundOrUnauthorized. Guid.Empty возвращает 400. CloseAll без активных сессий тоже успешен.
|
||||
|
||||
Отзыв деактивирует связанные push-токены. Успех Unit преобразуется в 204, а не в 200.
|
||||
|
||||
## Ограничение logout
|
||||
|
||||
IsRevoked проверяется при refresh; bearer middleware не сверяет текущий sid с БД. Access token может работать до окончания срока, а существующее соединение SignalR не закрывается этим контроллером.
|
||||
|
||||
---
|
||||
description: >-
|
||||
Controller for managing user sessions, including retrieving and closing
|
||||
sessions.
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
# SessionController
|
||||
|
||||
### Controller Description
|
||||
|
||||
* **Route**: `api/session`
|
||||
* **Authorize**: Requires authenticated user with roles "Admin" or "User" (`[Authorize(Roles = "Admin,User")]`).
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### <mark style="color:$info;">GetAllSessions</mark>
|
||||
|
||||
* **Description**: Retrieves all active sessions for the authenticated user.
|
||||
* **Route**: `[GET] api/session/all`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**: None
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns a list of user sessions.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "Guid",
|
||||
"deviceInfo": "string",
|
||||
"createdAt": "DateTime",
|
||||
"expiresAt": "DateTime",
|
||||
"isRevoked": "boolean"
|
||||
}
|
||||
]
|
||||
```
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"Unexpected Error! Please try again later."
|
||||
```
|
||||
|
||||
#### <mark style="color:$info;">CloseSession</mark>
|
||||
|
||||
* **Description**: Closes a specific session for the authenticated user.
|
||||
* **Route**: `[DELETE] api/session/close/{sessionId}`
|
||||
* **HTTP Method**: `DELETE`
|
||||
* **Request**:
|
||||
* **Path Parameter**: `sessionId` (Guid, required): ID of the session to close.
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Indicates session was successfully closed.
|
||||
* No body.
|
||||
* <mark style="color:$danger;">**400 Bad Request**</mark>: If `sessionId` is invalid or operation fails.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$danger;">**404 Not Found**</mark>: If session is not found.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"Unexpected Error! Please try again later."
|
||||
```
|
||||
|
||||
#### <mark style="color:$info;">CloseSession</mark>
|
||||
|
||||
* **Description**: Closes a current session for the authenticated user.
|
||||
* **Route**: `[DELETE] api/session/close/`
|
||||
* **HTTP Method**: `DELETE`
|
||||
* **Request**:
|
||||
* No body.
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Indicates session was successfully closed.
|
||||
* No body.
|
||||
* <mark style="color:$danger;">**400 Bad Request**</mark>: If `sessionId` is invalid or operation fails.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$danger;">**404 Not Found**</mark>: If session is not found.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"Unexpected Error! Please try again later."
|
||||
```
|
||||
|
||||
#### <mark style="color:$info;">CloseAllSessions</mark>
|
||||
|
||||
* **Description**: Closes all active sessions for the authenticated user.
|
||||
* **Route**: `[DELETE] api/session/close/all`
|
||||
* **HTTP Method**: `DELETE`
|
||||
* **Request**: None
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Indicates all sessions were successfully closed.
|
||||
* No body.
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"Unexpected Error! Please try again later."
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
#### SessionDto
|
||||
|
||||
* **Description**: Data transfer object for session information.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "Guid",
|
||||
"deviceInfo": "string",
|
||||
"createdAt": "DateTime",
|
||||
"expiresAt": "DateTime",
|
||||
"isRevoked": "boolean"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **Invalid User ID**: Handled by `ICurrentUserService`, aborts if invalid.
|
||||
* **Invalid Operations**: Returns `400 Bad Request` for `InvalidOperationException`.
|
||||
* **Unauthorized Access**: Returns `403 Forbidden` for `UnauthorizedAccessException`.
|
||||
* **Resource Not Found**: Returns `404 Not Found` for `NotFoundException`.
|
||||
* **Unexpected Errors**: Caught and returned as `500 Internal Server Error`.
|
||||
|
||||
### Logging
|
||||
|
||||
* Logs warnings for `UnauthorizedAccessException` and `NotFoundException`.
|
||||
* Logs errors for `InvalidOperationException` and unexpected exceptions.
|
||||
Источник: [Govor.API/Controllers/SessionController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/SessionController.cs).
|
||||
|
||||
Reference in New Issue
Block a user