GITBOOK-14: Govor.API: документация по текущему коду и диагностика 03.10.2026

This commit is contained in:
stalcke2288969
2026-10-03 06:20:45 +00:00
committed by gitbook-bot
parent 4603be9f71
commit 6c8abb23e3
27 changed files with 827 additions and 1901 deletions
+50 -143
View File
@@ -2,161 +2,68 @@
icon: wifi
---
# ChatHub
# ChatsHub — сообщения
**Route**: `hubs/chats`\
**Authorize**: Requires authentication (user must be logged in)
Подключение: /hubs/chats, Bearer access token. Серверный класс называется ChatsHub. Команды возвращают HubResult, события приходят независимо от ответа команды.
***
## Команды
### Hub Methods
| Имя | Запрос | Успешный Result |
| ------ | ---------------------------------- | ---------------------- |
| Send | MessageRequest | UserMessageResponse |
| Read | { messageId } | MessageReadResponse |
| Edit | { messageId, newEncryptedContent } | MessageEditResponse |
| Remove | { messageId, requestType } | MessageRemovedResponse |
#### <mark style="color:$primary;">OnConnectedAsync</mark>
**Description**: Automatically invoked when a client establishes a connection to the hub. Adds the user to their personal group for private messages and notifications.
**Behavior**:
* Retrieves the user's ID from the connection context.
* If the user ID is invalid (`Guid.Empty`), logs a warning and aborts the connection.
* Adds the user to a group named after their user ID (e.g., `userId.ToString()`).
* Logs the connection event with the user ID and connection ID.
**Notes**:
* Future enhancements may include adding the user to their chat groups (currently a TODO in the code).
***
#### <mark style="color:$primary;">OnDisconnectedAsync</mark>
**Description**: Automatically invoked when a client disconnects from the hub. Removes the user from their personal group.
**Behavior**:
* Retrieves the user's ID from the connection context, suppressing exceptions if the ID is unavailable (e.g., due to an early abort).
* If the user ID is valid, removes the user from their personal group.
* Logs the disconnection event with the user ID and connection ID.
* If an exception occurs, logs it as a warning along with the connection ID.
* If no exception occurs but the user ID is invalid, logs the disconnection with the connection ID.
**Notes**:
* Future enhancements may include removing the user from their chat groups (currently a TODO in the code).
***
#### <mark style="color:$info;">Send</mark>
**Description**: Allows a client to send a message to a recipient, which can be either a user or a group.
**Request**:
* **Method Name**: `Send`
* **Parameters**:
* `request`: An object of type `MessageRequest` with the following structure:
```json
{
"encryptedContent": "string",
"replyToMessageId": "Guid",
"recipientId": "Guid",
"recipientType": "string", // "User" or "Group"
"mediaAttachments": [
{
"mediaId": "Guid",
"encryptedKey": "string",
"type": "string",
"mimeType": "string"
}
]
}
```
**Responses**:
* <mark style="color:$success;">**Success**</mark>:
* Sends the message to the recipient (user or group) via the `ReceiveMessage` event.
* Notifies the sender with a confirmation via the `MessageSent` event.
* Logs the successful message send with the message ID, sender ID, recipient ID, and recipient type.
* <mark style="color:$danger;">**Error**</mark>:
* If the message is empty (no `encryptedContent` and no `mediaAttachments`), logs a warning and throws an `ArgumentException`.
* If the message fails to send (e.g., due to an internal error), logs the error and throws a `HubException`.
**Client-Side Events**:
* <mark style="color:$primary;">**ReceiveMessage**</mark>: Triggered on the recipient's client(s) to deliver the message.
* Payload: `UserMessageResponse` object.
* <mark style="color:$primary;">**MessageSent**</mark>: Triggered on the sender's client to confirm the message was sent.
* Payload: `UserMessageResponse` object.
**Notes**:
* The message must contain either `encryptedContent` or `mediaAttachments`; otherwise, it is invalid.
* The recipient is determined by `recipientType`:
* `"User"`: Sends to the recipient’s personal group (e.g., `recipientId.ToString()`).
* `"Group"`: Sends to all members of the group (e.g., `group_{recipientId}`).
***
### Data Models
#### MessageRequest
MessageRequest:
```json
{
"encryptedContent": "string",
"replyToMessageId": "Guid",
"recipientId": "Guid",
"recipientType": "string", // "User" or "Group"
"mediaAttachments": [
{
"mediaId": "Guid",
"encryptedKey": "string",
"type": "string",
"mimeType": "string"
}
]
"recipientId":"11111111-1111-1111-1111-111111111111",
"recipientType":0,
"encryptedContent":"<содержимое>",
"replyToMessageId":null,
"mediaAttachments":[]
}
```
#### UserMessageResponse
RecipientType.User=0 означает **личный чат**, recipientId — PrivateChat.Id. Group=1 означает ChatGroup.Id. Вложение: { mediaId, encryptedKey }.
```json
{
"messageId": "Guid",
"senderId": "Guid",
"recipientId": "Guid",
"recipientType": "string",
"encryptedContent": "string",
"sentAt": "DateTime",
"isEdited": "bool",
"mediaAttachments": [
{
"mediaId": "Guid",
"encryptedKey": "string",
"type": "string",
"mimeType": "string"
}
],
"replyToMessageId": "Guid"
}
```
Содержимое или вложение обязательно. Хаб ограничивает текст 50 000 символами, хотя атрибут DTO указывает 100 000. SignalR не выполняет MVC DataAnnotations автоматически; транспортный лимит входящего сообщения отдельно ограничивает размер JSON. При null encryptedContent с вложением возможна ошибка на Length.
## События
| Имя события (точно) | Payload |
| ------------------- | ---------------------- |
| ReceiveMessage | UserMessageResponse |
| MessageEdited | MessageEditResponse |
| MessageRemoved | MessageRemovedResponse |
| MessageReaded | MessageReadResponse |
Опечатка MessageReaded является текущим именем wire-контракта. Константа MessageSent есть, но отправка этого события закомментирована; не ожидайте его.
UserMessageResponse: messageId, senderId, recipientId, recipientType, encryptedContent, replyToMessageId, sentAt, isEdited, mediaAttachments. mediaAttachments — список MediaFile, не HTTP MediaAttachmentResponse; навигация MediaFile после Send явно не загружается и элементы могут быть null.
MessageEditResponse: messageId, editorId, recipientId, recipientType, newEncryptedContent, editedAt. MessageReadResponse: viewId, messageId, readerId, recipientId, whenWas, recipientType. MessageRemovedResponse: messageId, senderId, recipientId, requestType, recipientType.
## Семантика и ошибки
Edit проверяет автора и срок из MessageEditingOptions (по умолчанию 15 минут при Enabled=true), но не применяет лимит текста Send. Многие сервисные ошибки хаб превращает в InvalidOperationException и возвращает status=500, теряя исходный код.
RemoveMessageRequestType: HideForMe=0, ForceRemove=1. **HideForMe сейчас не реализован**: если автор вызывает Remove, сервис физически удаляет сообщение независимо от флага. Групповое удаление сравнивает DeleterId с ID группы вместо автора/прав администратора.
Read проверяет наличие у пользователя любого личного чата вместо участия в чате сообщения. Для групп прочтение не реализовано; хаб может упасть на First при отсутствии MessageView. Параллельные Read могут конфликтовать по уникальному индексу (MessageId, UserId).
Уведомления Edit/Remove/Read в личных чатах отправляются инициатору и группе с именем ID чата, хотя второй адресат должен быть участником. Поэтому собеседник может не получить событие.
Send для личного чата проверяет только его существование, не участие отправителя. Исправление доступа обязательно.
## Доставка
Успех сохранения и доставка события — разные этапы. После reconnect загрузите историю через HTTP, объединяйте ответ Send и ReceiveMessage по messageId. Без clientMessageId/idempotency-key повтор Send после сбоя может создать дубль.
***
### Error Handling
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; сервер с БД и Firebase в рамках диагностики не запускался.
* **Invalid User ID**: If the user ID is `Guid.Empty` during connection, the connection is aborted with a logged warning.
* **Empty Message**: If a message lacks both content and attachments, an `ArgumentException` is thrown with a logged warning.
* **Message Send Failure**: If sending fails (e.g., due to a service error), a `HubException` is thrown with the error logged.
***
### Logging
* Logs connection events with user ID and connection ID.
* Logs disconnection events, including exceptions if present.
* Logs message send attempts, successes, and failures for monitoring and debugging.
***
Источник: [Govor.API/Hubs/ChatsHub.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Hubs/ChatsHub.cs).