RedWizardsLab/EchoHub
1
0
Fork 0
mirror of https://github.com/RedWizardsLab/EchoHub.git synced 2026-09-07 15:46:02 +02:00
Code Issues 2 Packages Projects Releases 10 Wiki Activity

deploy: 0105f798e0

Browse Source
This commit is contained in:
HueByte
2026-07-23 09:48:40 +00:00
parent 37bd8c0f57
commit 32c664518a
144 changed files with 5098 additions and 6498 deletions
Download Patch File Download Diff File Expand all files Collapse all files
auriondocs/Synthesis/real-time-connection.md
+10 -15
View File
@@ -1,34 +1,29 @@
# Real-time connection management
# Real-time connection and messaging
> Managing the SignalR hub connection lifecycle and connection state.
> How the client establishes and maintains a real-time connection to the server and handles channel messaging.
# Real-time connection management
This guide explains how the client-side pieces manage a SignalR-based chat connection, surface server events to the UI, and carry message and attachment DTOs across those boundaries. Read it to understand which types own the HubConnection lifecycle, which types represent messages and attachments, and how connection orchestration hands events and histories back to the UI layer.
A compact overview of the client-side real-time layer: how the connection is created, the runtime surface it exposes to higher layers, and the DTOs used to carry chat and channel data. Read this to understand which types you call to open a SignalR-backed, end-to-end-capable chat connection, what events and exceptions to expect, and which transport records carry message and attachment metadata.
## EchoHubConnection.cs
Implements the SignalR connection lifecycle and messaging.
Encapsulates the SignalR connection to the server and join history with encryption info.
The [EchoHubConnection](../Code/src/EchoHub.Client/Services/EchoHubConnection.cs.md) type is a thin, SignalR-backed client wrapper that owns a HubConnection and translates server callbacks into plain .NET events (for example OnMessageReceived, OnUserJoined, OnChannelUpdated). It also integrates client-side encryption and room-key lookup: incoming payloads are decrypted before being raised to subscribers, and join history plus encryption metadata is tracked so callers can present past messages. EchoHubConnection declares focused exception types such as ChannelPasswordRequiredException (thrown when a join fails for password reasons) to enable UI-driven retry flows. According to the file relationships, EchoHubConnection consumes message and channel shapes from [ChatDtos.cs](../Code/src/EchoHub.Core/DTOs/ChatDtos.cs.md) and is instantiated and used by [ConnectionManager](../Code/src/EchoHub.Client/Services/ConnectionManager.cs.md).
This file defines a small domain exception and a single, high-level connection wrapper. The `ChannelPasswordRequiredException` is a dedicated exception type that carries a `ChannelName` and signals that a channel join failed due to missing or invalid credentials; the doc recommends UIs catch this specific type to prompt for a password and retry. The `EchoHubConnection` class is an event-driven wrapper around a SignalR `HubConnection`: it registers the server callback handlers defined by the server contract, decrypts incoming content when necessary, exposes simple events for messages, presence and channel updates, surfaces connection-state changes, and centralizes token provision and reconnection wiring. Within this topic `EchoHubConnection` consumes the transport records from [ChatDtos.cs](../Code/src/EchoHub.Core/DTOs/ChatDtos.cs.md) and is constructed/managed by the [ConnectionManager](../Code/src/EchoHub.Client/Services/ConnectionManager.cs.md).
## ConnectionManager.cs
Orchestrates connection state and event wiring for the real-time layer.
Coordinates connection lifecycle and connection events across the client.
The [ConnectionManager](../Code/src/EchoHub.Client/Services/ConnectionManager.cs.md) is the high-level owner of authentication, E2E key retrieval, HubConnection creation, wiring of SignalR callbacks, and tracking of joined channels. It exposes a small event surface that forwards the EchoHubConnection events to the UI (the doc notes AppOrchestrator subscribes), implements IAsyncDisposable to tear down both the hub wrapper and the underlying client, and reports progress from ConnectAsync via an onStatus callback while throwing on authentication failure. ConnectionManager also defines the [ConnectResult](../Code/src/EchoHub.Client/Services/ConnectionManager.cs.md) record that packages the login response, a list of channel DTOs, and a dictionary of channel histories (the histories contain [MessageDto] entries defined in ChatDtos). Per the relationships, ConnectionManager depends on [ChatDtos.cs](../Code/src/EchoHub.Core/DTOs/ChatDtos.cs.md) for payload shapes and on [EchoHubConnection](../Code/src/EchoHub.Client/Services/EchoHubConnection.cs.md) to manage the live SignalR interactions.
`ConnectionManager` is the composition root for a full client connection: it performs authentication (via the project's HTTP API client), attempts to fetch and apply end-to-end encryption keys, constructs and wires an [EchoHubConnection](../Code/src/EchoHub.Client/Services/EchoHubConnection.cs.md), and maintains channel membership state. It forwards the hub's runtime events (for example message and presence events) as higher-level events such as `MessageReceived`, `UserJoined`, and `ConnectionStatusChanged`, so UI orchestrators can subscribe without touching SignalR internals; these forwarded events may be raised from SignalR threads and callers must marshal to the UI thread if required. `ConnectAsync` reports progress through an `onStatus` callback and returns a `ConnectResult` (also declared in this file) to indicate outcome; the class and the underlying `EchoHubConnection` both implement `IAsyncDisposable`, and the doc emphasizes awaiting disposal so resources (connection, tokens, keys) are cleaned up.
## ChatDtos.cs
`AttachmentDto` collaborates directly with `ConnectResult` and other members of this topic (9 dependency links).
[ChatDtos.cs](../Code/src/EchoHub.Core/DTOs/ChatDtos.cs.md) defines the immutable DTOs used across the connection boundary: records such as AttachmentDto, ChannelDto, ChannelMetaDto, MessageDto, JoinChannelResult, and request shapes like SendMessageRequest. The [AttachmentDto](../Code/src/EchoHub.Core/DTOs/ChatDtos.cs.md) record carries metadata for file attachments (kind, URL, filename, filesize, optional ASCII preview) and is explicitly designed to work with end-to-end encrypted channels where the resource behind Url may be ciphertext the server cannot read. These DTOs are the concrete payload shapes that both [EchoHubConnection](../Code/src/EchoHub.Client/Services/EchoHubConnection.cs.md) and [ConnectionManager](../Code/src/EchoHub.Client/Services/ConnectionManager.cs.md) send, receive, and store in histories.
This file declares the transport records used across the real-time boundary: types such as `AttachmentDto`, `ChannelCryptoDto`, `ChannelDto`, `ChannelMetaDto`, `CreateChannelRequest`, `EmbedDto`, `JoinChannelResult`, `MessageDto`, `RekeyChannelRequest`, `ReplyRefDto`, `SendMessageRequest`, `SendUrlRequest`, `UpdateTopicRequest`, and `UserDto` model messages, channels, users and channel crypto metadata. Concretely, `AttachmentDto` is a value record holding `Kind`, `Url`, `FileName`, `FileSize`, and an optional `AsciiPreview`; the doc highlights that `Url` and `AsciiPreview` may be ciphertext for end-to-end encrypted channels, and that attachments are carried as metadata so clients can fetch or preview content on demand. `ChannelCryptoDto` is a small record with `IsEncrypted` and an optional `EncryptionSalt` and is used to indicate whether channel payloads are protected. These DTOs are the typed payloads that [EchoHubConnection](../Code/src/EchoHub.Client/Services/EchoHubConnection.cs.md) emits and that [ConnectionManager](../Code/src/EchoHub.Client/Services/ConnectionManager.cs.md) tracks when reporting join results and message events.
How the pieces fit
ConnectionManager is the orchestration layer: it authenticates, attempts to acquire E2E keys, builds and wires an [EchoHubConnection](../Code/src/EchoHub.Client/Services/EchoHubConnection.cs.md), and exposes forwarded events to the UI while tracking joined channels and histories. EchoHubConnection is the SignalR-focused implementation that manages the HubConnection lifecycle, maps server callbacks to events, performs decryption of incoming payloads, and throws focused exceptions (for example ChannelPasswordRequiredException) so the UI can prompt and retry joins. The DTOs in [ChatDtos.cs](../Code/src/EchoHub.Core/DTOs/ChatDtos.cs.md) are the shared, immutable shapes (messages, channels, attachments) that flow between the manager, the hub wrapper, and the UI; ConnectResult packages those DTOs back to callers after an initial connect sequence.
ConnectionManager is the orchestration layer: it authenticates, applies E2E keys, constructs an [EchoHubConnection](../Code/src/EchoHub.Client/Services/EchoHubConnection.cs.md), and subscribes to its events so UI-level orchestrators can observe high-level events and results without dealing with SignalR. EchoHubConnection implements the low-level SignalR wiring, dispatches strongly-typed events and domain exceptions (for example `ChannelPasswordRequiredException`), and uses the DTOs from [ChatDtos.cs](../Code/src/EchoHub.Core/DTOs/ChatDtos.cs.md) as its message and channel payloads. Together they present a clear separation: DTOs define the wire shape, EchoHubConnection maps wire messages to runtime events and errors, and ConnectionManager composes those primitives into a single lifecycle and event surface for the UI.
---
*Covers 3 of 3 source files identified for this topic.*
*Synthesised by Aurion on 2026-07-23 05:51:44 UTC*
*Synthesised by AurionDocs on 2026-07-23 09:31:01 UTC*