mirror of
https://github.com/Govor-team/Govor.git
synced 2026-07-21 11:44:56 +00:00
rework docs
This commit is contained in:
Artemy
@@ -0,0 +1,162 @@
|
||||
---
|
||||
icon: wifi
|
||||
---
|
||||
|
||||
# ChatHub
|
||||
|
||||
**Route**: `hubs/chats`\
|
||||
**Authorize**: Requires authentication (user must be logged in)
|
||||
|
||||
***
|
||||
|
||||
### Hub Methods
|
||||
|
||||
#### <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
|
||||
|
||||
```json
|
||||
{
|
||||
"encryptedContent": "string",
|
||||
"replyToMessageId": "Guid",
|
||||
"recipientId": "Guid",
|
||||
"recipientType": "string", // "User" or "Group"
|
||||
"mediaAttachments": [
|
||||
{
|
||||
"mediaId": "Guid",
|
||||
"encryptedKey": "string",
|
||||
"type": "string",
|
||||
"mimeType": "string"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### UserMessageResponse
|
||||
|
||||
```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"
|
||||
}
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **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.
|
||||
|
||||
***
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
description: SignalR hub for managing user online presence and notifications.
|
||||
icon: wifi
|
||||
---
|
||||
|
||||
# PresenceHub
|
||||
|
||||
### Controller Description
|
||||
|
||||
* **Route**: `hubs/presence`
|
||||
* **Authorize**: Requires authenticated user with roles "Admin" or "User" (`[Authorize(Roles = "Admin, User")]`).
|
||||
|
||||
### Hub Methods
|
||||
|
||||
#### <mark style="color:$info;">OnConnectedAsync</mark>
|
||||
|
||||
* **Description**: Invoked when a client connects, updates online status and notifies friends.
|
||||
* **Behavior**:
|
||||
* Retrieves user ID from context.
|
||||
* Aborts connection if user ID is `Guid.Empty` or user does not exist.
|
||||
* Adds user to online store and their personal group.
|
||||
* Notifies friends of user going online via `UserOnline` event.
|
||||
* **Client-Side Events**:
|
||||
* **UserOnline**: Triggered for friends with payload `userId` (Guid).
|
||||
* **Responses**: None (connection aborted on invalid user ID).
|
||||
|
||||
#### <mark style="color:$info;">OnDisconnectedAsync</mark>
|
||||
|
||||
* **Description**: Invoked when a client disconnects, updates offline status and notifies friends.
|
||||
* **Behavior**:
|
||||
* Retrieves user ID from context, suppressing exceptions.
|
||||
* Removes user from personal group if ID is valid.
|
||||
* Updates user's `WasOnline` timestamp.
|
||||
* Sets user as offline in store.
|
||||
* Notifies friends of user going offline via `UserOffline` event.
|
||||
* **Client-Side Events**:
|
||||
* **UserOffline**: Triggered for friends with payload `userId` (Guid).
|
||||
* **Responses**: None.
|
||||
|
||||
### Data Models
|
||||
|
||||
* **N/A**: No specific data models defined for hub methods.
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **Invalid User ID**: Aborts connection with logged warning if `Guid.Empty` or user not found.
|
||||
* **Unexpected Errors**: Logged, but no specific response (handled by base method).
|
||||
|
||||
### Logging
|
||||
|
||||
* Logs warnings for invalid user ID on connection.
|
||||
* Logs information for disconnections with user ID and connection ID.
|
||||
* Logs errors for unexpected exceptions during disconnection.
|
||||
Reference in New Issue
Block a user