GitBook: No commit message

2026-07-21 19:54:55 +00:00 · 2025-07-24 08:07:52 +00:00
parent 53ea25f9fd
commit 19f1ccdfd5
15 changed files with 1943 additions and 0 deletions
@@ -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.
+
+***