mirror of
https://github.com/RedWizardsLab/EchoHub.git
synced 2026-09-05 23:34:09 +02:00
deploy: 0105f798e0
This commit is contained in:
HueByte
File diff suppressed because it is too large
Load Diff
@@ -8,11 +8,14 @@ public static class AsyncRunner
|
||||
```
|
||||
|
||||
|
||||
Eliminates repeated Task.Run/try/catch/app.Invoke(ShowError) boilerplate by consolidating the common pattern of running background work and surfacing errors to the UI. It runs the provided async work on a background thread and routes any exceptions to the UI thread for user notification.
|
||||
Runs the provided asynchronous work on a background thread and routes exceptions to the UI, eliminating boilerplate like `Task.Run`/try/catch/`app.Invoke(ShowError)`.
|
||||
|
||||
`AsyncRunner.Run` takes an `IApplication` (`app`), a `Func<Task>` representing the work, an `Action<string>` (`showError`), a string (`errorPrefix`) used in the user-facing error, and an optional `string? logContext` to enrich logs; if an exception occurs, it logs with `Log.Error` and invokes the UI thread to display the error via `showError`.
|
||||
|
||||
This pattern centralizes background execution and UI-error reporting, so callers need only supply the work and error message components and can rely on consistent logging and user feedback.
|
||||
|
||||
## Remarks
|
||||
AsyncRunner encapsulates a cross-cutting concern: performing asynchronous work without blocking the UI and centralizing error reporting. It uses Task.Run to execute work off the calling thread and app.Invoke to marshal the error surface back to the UI. When an exception occurs, it logs the failure with the provided context (logContext if supplied, otherwise errorPrefix) and shows a UI message using showError prefixed by errorPrefix. Because Run is fire-and-forget (it returns void), callers should not rely on it for completion or exception propagation; choose a different pattern if you need to observe results.
|
||||
This abstraction isolates the cross-cutting concerns of background execution and UI error presentation. By encapsulating this pattern, it avoids duplicating boilerplate across call sites and ensures errors are logged with contextual information and surfaced on the UI thread via `IApplication.Invoke`.
|
||||
|
||||
## Notes
|
||||
- This method is fire-and-forget; exceptions are caught and surfaced but not propagated to the caller.
|
||||
- The UI update and logging rely on the provided IApplication and showError delegate; ensure they are safe to call from a background thread; app.Invoke is used to marshal to the UI thread.
|
||||
- This method is fire-and-forget: it launches the work and does not return a `Task`; callers cannot await completion or observe exceptions from the caller's context. If you need completion signaling, consider returning a `Task` or providing a completion callback.
|
||||
@@ -8,17 +8,12 @@ public class AudioPlaybackService
|
||||
```
|
||||
|
||||
|
||||
AudioPlaybackService is a thread-safe wrapper around an underlying audio player that exposes asynchronous playback controls and a finished event surface. Use it when you need serialized access to play, pause, resume, or stop audio and a consistent event interface without managing locks and state machines yourself.
|
||||
AudioPlaybackService provides a thread-safe, asynchronous facade for audio playback using a private `Player` instance. It exposes the playback state via `IsPlaying` and `IsPaused`, and it forwards a `PlaybackFinished` event when the underlying `Player` completes playback. All public operations are serialized with a private `SemaphoreSlim` named `_lock` to prevent concurrent access to the player. When you call `PlayAsync`, if something is already playing it stops it before starting the new file; `PauseAsync`, `ResumeAsync`, and [`StopAsync`](../../EchoHub.Server/Services/ServerDirectoryService.cs.md) similarly acquire the lock, perform the appropriate operation if possible, and log any exceptions with `Log.Warning`. Volume is controlled via `SetVolumeAsync`, which clamps the requested volume to a maximum of 100 using `Math.Min`.
|
||||
|
||||
## Remarks
|
||||
To prevent concurrent calls from interfering with playback state, the class serializes all operations using a SemaphoreSlim. When PlayAsync is invoked while something is already playing, it stops the current track before starting the new file; PauseAsync, ResumeAsync, and StopAsync perform their actions only when appropriate states are detected. The PlaybackFinished event is forwarded from the internal player, so callers can react to completion without depending on the concrete implementation of the _player. Exceptions raised by the underlying player are caught and logged with a warning, ensuring playback issues do not crash the application.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
// Example usage
|
||||
var audio = new AudioPlaybackService();
|
||||
await audio.PlayAsync("path/to/file.mp3");
|
||||
```
|
||||
This abstraction centralizes concurrency concerns and error handling around audio playback. By bridging the `Player` with a single, serialized surface, it reduces race conditions when multiple callers request playback from different parts of the application. The `PlaybackFinished` event provides a clean notification channel to consumers without exposing the internal player, enabling a decoupled UI or service layer to react to completion.
|
||||
|
||||
## Notes
|
||||
- This wrapper serializes calls to avoid race conditions; however, it is not cancellation-aware. If you need to cancel an in-flight operation, extend the class with cancellation support or a dedicated cancellation mechanism.
|
||||
- Exceptions during playback operations are swallowed after being logged with `Log.Warning`, so callers do not observe crashes but must rely on the logs to diagnose issues.
|
||||
- All playback-related methods acquire the `_lock` semaphore, meaning long-running operations inside any call can block other playback requests and should be kept短-lived to avoid contention.
|
||||
- `SetVolumeAsync` caps the volume at 100 via `Math.Min`, ensuring the underlying player never receives an out-of-range value.
|
||||
|
||||
@@ -8,26 +8,7 @@ internal static class AvatarHelper
|
||||
```
|
||||
|
||||
|
||||
AvatarHelper centralizes the shared logic for uploading avatars by accepting either a local file path or an HTTP(S) URL, resolving the input to a stream, and uploading it via ApiClient.UploadAvatarAsync. It returns the ASCII art response from the server, providing a straightforward way to obtain the server-side representation of the uploaded avatar without duplicating local-file or network-handling code.
|
||||
AvatarHelper provides a single entry point to upload an avatar from either a local file path or a remote URL by converting the target into a `Stream`, then delegating the actual upload to `ApiClient.UploadAvatarAsync`. It abstracts away the file I/O and HTTP fetch logic, ensuring callers don't need to manage streams or HTTP requests themselves. It returns the server's ASCII art response as a `string?` and guarantees the `Stream` is disposed after the upload.
|
||||
|
||||
## Remarks
|
||||
|
||||
By supporting both local and remote sources behind a single UploadAsync entry point, AvatarHelper hides the mechanics of data retrieval and stream management from call sites and ensures consistent disposal of the stream. The actual upload is delegated to ApiClient, keeping concerns separated between data acquisition and server interaction. The class is internal, reinforcing its role as a reusable utility within the client layer rather than a public API.
|
||||
|
||||
The method propagates errors from file access, HTTP fetch, or the server upload to the caller, which is appropriate for a small, focused helper that prioritizes simplicity over internal retries or resilience policies.
|
||||
|
||||
## Example
|
||||
|
||||
```csharp
|
||||
// Example usage within the same assembly
|
||||
var client = new ApiClient("https://api.example.org");
|
||||
string? artFromFile = await AvatarHelper.UploadAsync(client, @"C:\avatars\user.png");
|
||||
string? artFromUrl = await AvatarHelper.UploadAsync(client, "https://example.org/avatars/user.png");
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Creating a new HttpClient per invocation can lead to socket exhaustion in high-throughput scenarios; consider reusing a shared HttpClient instance or using HttpClientFactory in production code.
|
||||
- If the local path does not exist, a FileNotFoundException is thrown.
|
||||
- When targeting a URL, if the URL's file name is missing or lacks an extension, the code defaults to using avatar.png as the upload file name.
|
||||
- Exceptions from the HTTP request or the server upload propagate to the caller; there is no retry logic within this helper.
|
||||
AvatarHelper isolates avatar uploading behind a focused API, so higher-level code doesn't need to know whether the source is a local file or a URL. It accepts either a local path or an HTTP(S) URL, resolves a valid `fileName` (defaulting to `avatar.png` when the URL doesn't supply one), and streams the content to `ApiClient.UploadAvatarAsync`. The helper ensures proper resource management by disposing the `Stream` after the upload, and it centralizes the cross-cutting concern of avatar uploads to a single place.
|
||||
@@ -8,28 +8,24 @@ public sealed class ClientEncryptionService : IMessageEncryptionService
|
||||
```
|
||||
|
||||
|
||||
ClientEncryptionService provides client-side encryption for messages by applying AES-256-GCM using a key supplied by the server. It mirrors the server’s encryption format so messages are encrypted end-to-end between client and server. When no key has been set, Encrypt is a no-op and returns the plaintext to preserve compatibility with unauthenticated flows; once initialized, Encrypt produces a prefixed, base64-encoded payload containing the nonce and ciphertext+tag, and Decrypt reverses this process. If decryption fails due to a missing or mismatched key or corrupted data, a sentinel message is returned to indicate the failure and prompt re-authentication to refresh the key.
|
||||
ClientEncryptionService implements client-side encryption using AES-256-GCM to protect messages before sending them to the server, aligning with the server's ciphertext format so decryption occurs only with the shared key. After you provide a base64-encoded key via `SetKey`, it encrypts plaintext by generating a fresh 12-byte nonce and a 16-byte authentication tag, returning a string that starts with the `EncryptionPrefix` and includes base64-encoded nonce and payload; if no key has been set (`_key` is null), `Encrypt` returns the plaintext unchanged.
|
||||
|
||||
## Remarks
|
||||
This abstraction isolates cryptography behind a single, testable service that can be swapped or disabled without changing business logic. It enforces a clear security boundary: encryption only happens after a server-provided key is loaded, reducing the risk of leaking plaintext. The pre-key pass-through behavior preserves compatibility with existing flows during login or in environments where the key has not yet been fetched.
|
||||
This class hides cryptography behind the [`IMessageEncryptionService`](../../EchoHub.Core/Contracts/IMessageEncryptionService.cs.md) contract, offering a simple, predictable API for encryption and decryption while keeping key material private. It ensures that only a server-provisioned key enables encryption, and it produces self-contained ciphertext that carries its nonce and tag so the server can decrypt it reliably. The design also provides nullable-friendly helpers (`EncryptNullable`, `DecryptNullable`) to gracefully handle missing values.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
// Example: encrypt and decrypt with a server-provided key
|
||||
var client = new ClientEncryptionService();
|
||||
|
||||
// Create a 32-byte key for demonstration (replace with real server-provided key)
|
||||
var keyBytes = new byte[32];
|
||||
var base64Key = Convert.ToBase64String(keyBytes);
|
||||
client.SetKey(base64Key);
|
||||
|
||||
// Example usage of client-side encryption
|
||||
var encryption = new ClientEncryptionService();
|
||||
string base64Key = "<32-byte-base64-key>";
|
||||
encryption.SetKey(base64Key);
|
||||
string plaintext = "Secret message";
|
||||
string encrypted = client.Encrypt(plaintext);
|
||||
string decrypted = client.Decrypt(encrypted);
|
||||
// decrypted should equal plaintext
|
||||
string ciphertext = encryption.Encrypt(plaintext);
|
||||
string decrypted = encryption.Decrypt(ciphertext);
|
||||
```
|
||||
|
||||
## Notes
|
||||
- Encrypt and Decrypt only work after a 32-byte key has been provided via SetKey; otherwise Encrypt returns plaintext and Decrypt returns content unchanged.
|
||||
- If the encrypted content is tampered with, the key is wrong, or the payload is malformed, Decrypt returns the special placeholder: "[encrypted message — decryption failed, try re-logging to fetch the latest key]".
|
||||
- The key is held in memory and is not rotated automatically; ensure proper key management and re-fetch after key rotation on the server.
|
||||
- Encrypt before calling `SetKey` is a no-op: the input plaintext is returned unchanged when `_key` is null.
|
||||
- Decrypt returns the original content if `_key` is null or the input does not start with the expected `EncryptionPrefix`.
|
||||
- `SetKey` enforces a 32-byte (256-bit) key length and throws `InvalidOperationException` if the length is not exactly 32 bytes.
|
||||
- Decryption errors are handled gracefully; if decryption fails for any reason, a sentinel message is returned: "[encrypted message — decryption failed, try re-logging to fetch the latest key]".
|
||||
@@ -8,25 +8,20 @@ public static class ClipboardFiles
|
||||
```
|
||||
|
||||
|
||||
ClipboardFiles reads file paths from the clipboard when the clipboard contains a file-list (such as after copying files in Explorer/Finder). Use TryGetFiles to retrieve those paths so you can attach copied files directly without pasting textual paths; this works on Windows and Linux, while macOS and other platforms do not expose a file-list clipboard.
|
||||
ClipboardFiles reads the OS clipboard to obtain a list of files when the clipboard holds a file-list (such as after copying files in a file manager). This enables scenarios where a copied set of files can be pasted or attached directly, without requiring the user to paste raw text paths. Call `TryGetFiles` to retrieve existing file paths from the clipboard; the method returns true when one or more valid paths are found, and false otherwise (including on platforms without file-list clipboard support).
|
||||
|
||||
## Remarks
|
||||
ClipboardFiles encapsulates platform differences behind a single API. It isolates Windows-specific CF_HDROP handling and Linux's text/uri-list retrieval, performing path existence checks and filtering out non-file entries to return a clean list of existing paths. It returns true only when at least one file is found; otherwise false, letting callers gracefully fall back to other input methods.
|
||||
This helper abstracts away platform differences in clipboard formats and presents a single, cohesive API for retrieving file lists from the clipboard. On Windows it enumerates files via the CF_HDROP channel and returns the paths that point to existing files. On Linux it reads a `text/uri-list` from the clipboard (via `wl-paste` or `xclip`), converts `file://` URLs to local paths, and keeps only paths that exist. The implementation favors a graceful failure path: any read-time exception is logged and the caller simply receives a non-success result, allowing callers to degrade gracefully without crashing. The API design emphasizes a simple success/failure boolean along with a concrete list of files, enabling straightforward integration into UX flows that want to treat copied files as attachable entities rather than plain text.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
if (ClipboardFiles.TryGetFiles(out var files))
|
||||
{
|
||||
Console.WriteLine($"Clipboard contains {files.Count} file(s): {string.Join(", ", files)}");
|
||||
}
|
||||
else
|
||||
{
|
||||
Console.WriteLine("Clipboard does not contain a file-list or contains only non-existent paths.");
|
||||
foreach (var path in files)
|
||||
Console.WriteLine(path);
|
||||
}
|
||||
```
|
||||
|
||||
## Notes
|
||||
- Returns only existing files; non-existent or inaccessible paths are ignored.
|
||||
- Windows implementation relies on CF_HDROP with a brief retry loop to tolerate clipboard contention.
|
||||
- Linux implementation uses wl-paste or xclip (one must be available for success).
|
||||
- macOS and other platforms do not provide file-list clipboard support.
|
||||
- macOS and other non-supported platforms do not provide a file-list clipboard, so `TryGetFiles` returns false there.
|
||||
- The method only returns paths that actually exist on disk; non-existent or malformed clipboard entries are ignored, and an empty result yields false.
|
||||
|
||||
@@ -8,22 +8,15 @@ public static class ClipboardImage
|
||||
```
|
||||
|
||||
|
||||
Reads raw image data from the OS clipboard and returns PNG-encoded bytes suitable for saving, embedding, or transmitting. Use this when you need a single, consistent PNG representation of whatever image the user has copied (browser-copied PNGs, screenshots, editor bitmaps) so callers don't need per-OS or per-format handling.
|
||||
Reads raw image bytes from the platform clipboard and returns them as a PNG byte array when available. Use `ClipboardImage.TryGetPng` when you need a canonical, pasteable PNG representation of whatever image the user has on the clipboard (for example, when accepting pasted screenshots or images in a terminal or chat input that cannot accept raw bitmap data).
|
||||
|
||||
## Remarks
|
||||
This class normalizes multiple clipboard image formats into PNG. It prefers native clipboard PNG formats when available (preserving transparency) and falls back to platform clipboard bitmaps (CF_DIB on Windows) by wrapping the DIB bytes in a minimal BMP file header and decoding/re-encoding them as PNG. TryGetPng routes to OS-specific helpers and catches/logs errors, returning false on failure rather than throwing.
|
||||
`ClipboardImage` centralizes platform-specific clipboard handling: `TryGetPng` dispatches to `TryGetWindows`, `TryGetLinux`, or `TryGetMacOS` depending on `OperatingSystem` checks, and normalizes all outputs to PNG. When the clipboard format already contains PNG bytes (detected using the `PngMagic` signature or platform-registered PNG formats such as those discovered via `RegisterClipboardFormatW` on Windows), the bytes are passed through to preserve fidelity and transparency. When the clipboard exposes a DIB/bitmap (`CfDib` on Windows), the `DibToPng` helper builds a minimal BMP wrapper around the DIB bytes, decodes it with `Image.Load`, and re-encodes the result as PNG; this covers screenshots and editors that expose only device-independent bitmaps.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
// Save whatever image is on the clipboard to a file named clipboard.png
|
||||
if (ClipboardImage.TryGetPng(out var png))
|
||||
{
|
||||
System.IO.File.WriteAllBytes("clipboard.png", png);
|
||||
}
|
||||
```
|
||||
The class intentionally swallows and logs exceptions (via `Log.Warning`) from clipboard access and image decoding so callers get a simple success/failure result from `TryGetPng` instead of propagating clipboard or image-library exceptions.
|
||||
|
||||
## Notes
|
||||
- DibToPng returns null for malformed or undecodable DIB input; TryGetPng propagates that as a failure (false).
|
||||
- The implementation prefers registered PNG clipboard formats to preserve alpha; CF_DIB bitmaps are re-encoded and may lose or change metadata.
|
||||
- Re-encoding a bitmap to PNG allocates memory and does CPU work; callers should avoid doing this in a tight loop.
|
||||
- TryGetPng checks the platform (Windows/Linux/macOS) and will return false on unsupported platforms; failures are logged rather than thrown.
|
||||
- Clipboard APIs are platform and threading sensitive. On Windows the OS clipboard typically requires running on an STA thread; calling `TryGetPng` from a non-STA thread may fail or return false. Ensure clipboard access is performed on an appropriate thread context for the platform.
|
||||
- `DibToPng` validates the DIB header (minimum 40 bytes, header size bounds) and returns null for malformed input. Decoding can still fail at `Image.Load` for unsupported or corrupted bitmaps; such failures are logged and surface as a failure to `TryGetPng`.
|
||||
- Re-encoding a DIB to PNG may not preserve alpha/transparency if the original bitmap format lacks alpha channels (DIB/CF_DIB often does not include alpha). If preserving exact alpha semantics is required, prefer sources that supply native PNG clipboard formats when possible.
|
||||
- Converting clipboard data allocates buffers (the BMP wrapper and the resulting PNG byte array) and performs image decode/encode work; callers should expect a non-trivial CPU and memory cost for large images.
|
||||
@@ -18,16 +18,15 @@ internal sealed class ConnectionManager : IAsyncDisposable
|
||||
```
|
||||
|
||||
|
||||
Manages the full lifecycle of a live chat connection: authenticating with the server, establishing end-to-end encryption keys, creating and wiring the SignalR (EchoHub) connection, tracking joined channels, and exposing a thin event surface that the UI (AppOrchestrator) can subscribe to. Use this when you want a single, high-level component to own connection state and SignalR event forwarding instead of manipulating ApiClient and EchoHubConnection directly.
|
||||
Manages a server connection end-to-end: handles authentication via [`ApiClient`](ApiClient.cs.md), establishes end-to-end encryption, creates and wires an [`EchoHubConnection`](EchoHubConnection.cs.md), tracks joined channels, and exposes SignalR events so higher-level orchestrators can react without touching connection internals. Reach for `ConnectionManager` when you want UI code (for example an [`AppOrchestrator`](../AppOrchestrator.cs.md)) to observe connection and chat events through simple events rather than managing [`ApiClient`](ApiClient.cs.md) and [`EchoHubConnection`](EchoHubConnection.cs.md) yourself.
|
||||
|
||||
## Remarks
|
||||
This class centralizes the responsibilities that would otherwise be scattered across UI code: authentication and token rotation, attempting to fetch and apply the E2E encryption key, instantiating and wiring an EchoHubConnection, and keeping track of which channels have been joined. It forwards SignalR events as simple .NET events so the UI layer can react without needing to know SignalR details. ConnectionManager also implements IAsyncDisposable so callers can cleanly tear down both the EchoHubConnection and the underlying ApiClient.
|
||||
`ConnectionManager` centralizes lifecycle concerns: it authenticates (login/registration/refresh), subscribes to token rotation, attempts to fetch and apply the E2E encryption key, constructs and registers handlers on the [`EchoHubConnection`](EchoHubConnection.cs.md), and ensures channel membership state is tracked. It forwards the hub's runtime events (for example `MessageReceived`, `UserJoined`, `ChannelUpdated`) so callers receive high-level notifications and do not need to bind SignalR handlers directly. The class is intended as the single place that composes [`ApiClient`](ApiClient.cs.md), [`ClientEncryptionService`](ClientEncryptionService.cs.md)/[`RoomKeyStore`](RoomKeyStore.cs.md), and [`EchoHubConnection`](EchoHubConnection.cs.md) into a usable connection for the UI.
|
||||
|
||||
## Notes
|
||||
- ConnectionManager may raise forwarded events from background threads (SignalR callbacks). UI handlers should marshal to the UI thread if required by the UI framework.
|
||||
- ConnectAsync reports progress via the onStatus callback and will throw on authentication failure; callers are expected to handle expired saved sessions or retry logic.
|
||||
- Failure to fetch the encryption key is treated as non-fatal: the manager logs a warning and proceeds without message encryption.
|
||||
- Dispose of the manager (DisposeAsync) when the app shuts down to ensure the hub connection and ApiClient are cleaned up.
|
||||
- `ConnectAsync` reports progress via the `onStatus` callback and will throw on authentication failure — callers are expected to handle saved-session expiry and similar error flows.
|
||||
- Event handlers (for example `MessageReceived`, `UserJoined`, `ConnectionStatusChanged`) may be invoked from signalr/connection threads; subscribers should not assume they run on the UI thread and must marshal to the UI thread when necessary.
|
||||
- Always `await` disposing the manager (it implements `IAsyncDisposable`) so underlying resources such as the [`EchoHubConnection`](EchoHubConnection.cs.md) and [`ApiClient`](ApiClient.cs.md) are cleanly released; failing to do so can leave connections or background work active.
|
||||
|
||||
---
|
||||
|
||||
@@ -51,13 +50,12 @@ internal record ConnectResult(
|
||||
| `Histories` | `Dictionary<string, List<MessageDto>>` | — |
|
||||
|
||||
|
||||
Represents the outcome of a successful connection, returned to AppOrchestrator for UI updates. It bundles the authentication result, the current set of channels, and the initial histories for every auto-joined channel (keyed by channel name and including the default channel). As an immutable record, it serves as a single, self-contained snapshot that the UI can bootstrap from after a connect.
|
||||
ConnectResult represents the payload returned after a successful connection, carrying everything the [`AppOrchestrator`](../AppOrchestrator.cs.md) needs to update the UI. It includes the authenticated login information (`Login`), the collection of available channels (`Channels`), and the initial per-channel histories (`Histories`), where each channel name maps to its starting list of messages, always including the default channel.
|
||||
|
||||
## Remarks
|
||||
This object centralizes the data needed to render the initial connected state, decoupling the connection logic from the UI orchestration. By passing a single ConnectResult, the AppOrchestrator can immediately populate channel lists and histories without issuing additional fetches, promoting a clean separation between connection handling and presentation concerns.
|
||||
ConnectResult is a `record`, so it participates in value-based equality and can be treated as a single unit when comparing connection outcomes. Note that its `Channels` and `Histories` collections are mutable (`List<ChannelDto>` and `Dictionary<string, List<MessageDto>>`); if you need true immutability, expose read-only wrappers or clone the collections when passing them onward.
|
||||
|
||||
## Notes
|
||||
- ConnectResult is immutable; to reflect changes (e.g., new messages or channels), construct and pass a new instance rather than mutating the existing one.
|
||||
- Histories is a dictionary keyed by channel name that contains the initial per-channel histories; ensure channel names in the dictionary align with the Channels list to avoid inconsistencies.
|
||||
- The contained `List<ChannelDto>` and `Dictionary<string, List<MessageDto>>` are mutable; avoid mutating them in place and consider treating the `ConnectResult` as a snapshot that should be cloned if you require immutability downstream.
|
||||
|
||||
---
|
||||
@@ -20,26 +20,13 @@ public sealed class ChannelPasswordRequiredException : Exception
|
||||
```
|
||||
|
||||
|
||||
Thrown when joining a channel fails because a password is required or the provided password is incorrect. The UI catches this to prompt the user for credentials and retry the join, using ChannelName to provide channel context.
|
||||
ChannelPasswordRequiredException represents the domain condition that a join operation on a channel cannot proceed because a password is required or the provided password was invalid. It is intended to be caught by the UI layer, which then prompts the user for the correct password and retries the join operation. The exception carries the channel name via the `ChannelName` property to identify which channel needs authentication.
|
||||
|
||||
## Remarks
|
||||
ChannelPasswordRequiredException provides a precise signal for a password-related join failure. By carrying the ChannelName, it enables the UI to present a meaningful prompt and retry flow without inspecting lower-level errors. This focused exception helps keep join logic cohesive and testable by separating password-entry concerns from generic failure handling.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
try
|
||||
{
|
||||
// Code that attempts to join a channel and may throw ChannelPasswordRequiredException
|
||||
}
|
||||
catch (ChannelPasswordRequiredException ex)
|
||||
{
|
||||
Console.WriteLine($"Password is required to join channel '{ex.ChannelName}'.");
|
||||
// Prompt the user for a password and retry the join using the provided channel name
|
||||
}
|
||||
```
|
||||
Using a distinct exception type to signal password-related authentication flows keeps the connection logic decoupled from the UI. The `ChannelName` property provides channel-specific context for prompts, enabling precise feedback such as prompting for the password of the channel identified by `ChannelName` when retrying.
|
||||
|
||||
## Notes
|
||||
- Be mindful that ChannelName may be null if constructed with null; guard accordingly before displaying it to users.
|
||||
- Use a specific catch for `ChannelPasswordRequiredException` rather than a broad catch of `Exception`, to avoid handling unrelated failures; access the `ChannelName` to present a contextual, channel-specific prompt.
|
||||
|
||||
---
|
||||
|
||||
@@ -52,35 +39,30 @@ public sealed class EchoHubConnection : IAsyncDisposable
|
||||
```
|
||||
|
||||
|
||||
A SignalR-backed client wrapper that manages a HubConnection to the Echo chat hub, integrates client-side encryption/room-key lookup, and exposes simple event callbacks for incoming messages, presence and channel events. Reach for EchoHubConnection when you need a higher-level, event-driven connection to the server that automatically handles authentication token provisioning and reconnect behavior while decrypting incoming payloads for the UI.
|
||||
A lightweight, event-driven wrapper around a SignalR `HubConnection` that manages authentication, reconnection and client-side handlers for the chat protocol. Use `EchoHubConnection` when you need a high-level, strongly-typed bridge between the server's [`IEchoHubClient`](../../EchoHub.Core/Contracts/IEchoHubClient.cs.md) callbacks and your UI or application logic — it registers the server method handlers, decrypts incoming content, exposes simple events (for messages, presence, channel updates, errors, etc.), and surfaces connection state changes.
|
||||
|
||||
## Remarks
|
||||
EchoHubConnection encapsulates the SignalR HubConnection lifecycle and maps server callbacks onto plain .NET events (e.g. OnMessageReceived, OnUserJoined, OnChannelUpdated). It supplies the HubConnectionBuilder with an AccessTokenProvider using the provided ApiClient so calls are authenticated, and it wires automatic-reconnect handlers that surface connection state changes via OnConnectionStateChanged and OnReconnected. Incoming MessageDto instances are passed through the client-side encryption pipeline (ClientEncryptionService and RoomKeyStore) so the UI sees decrypted content or a locked placeholder when a room key is not available.
|
||||
`EchoHubConnection` centralizes SignalR integration concerns: it creates and configures the underlying `HubConnection` (including token provisioning via the provided [`ApiClient`](ApiClient.cs.md)), wires up automatic reconnect behavior, and maps server-invoked methods to public events such as `OnMessageReceived`, `OnUserJoined`, `OnChannelUpdated`, and others. Incoming [`MessageDto`](../../EchoHub.Core/DTOs/ChatDtos.cs.md) instances are run through the connection's decryption path (see `DecryptMessage`/`DecryptField`) before being forwarded, and encrypted content that cannot be unlocked is replaced by the `LockedMessagePlaceholder`. The class implements `IAsyncDisposable` so consumers should `await DisposeAsync()` to cleanly stop the connection.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
// Subscribe to events and inspect connection state
|
||||
var echo = new EchoHubConnection(serverUrl, apiClient, encryptionService, roomKeyStore);
|
||||
// Assume these are already created: serverUrl (string), apiClient (ApiClient),
|
||||
// encryption (ClientEncryptionService), roomKeys (RoomKeyStore).
|
||||
var connection = new EchoHubConnection(serverUrl, apiClient, encryption, roomKeys);
|
||||
|
||||
echo.OnMessageReceived += message =>
|
||||
{
|
||||
// MessageDto is provided by the library; content may be the LockedMessagePlaceholder
|
||||
Console.WriteLine($"Message received in {message.ChannelName}: {message.Content}");
|
||||
};
|
||||
connection.OnConnectionStateChanged += state => Console.WriteLine($"State: {state}");
|
||||
connection.OnMessageReceived += message => Console.WriteLine($"Message from {message.From}: {message.Content}");
|
||||
connection.OnReconnected += () => Console.WriteLine("Reconnected to hub");
|
||||
|
||||
if (echo.IsConnected)
|
||||
{
|
||||
Console.WriteLine("Currently connected to the chat hub.");
|
||||
}
|
||||
|
||||
// Remember to dispose when finished
|
||||
await echo.DisposeAsync();
|
||||
// When finished with the connection:
|
||||
await connection.DisposeAsync();
|
||||
```
|
||||
|
||||
## Notes
|
||||
- Events are raised directly from SignalR callbacks; handlers may not run on a UI thread — marshal to the UI thread if required.
|
||||
- Encrypted messages for channels without a stored key are replaced with LockedMessagePlaceholder; supply the channel passphrase (through the app's key store flow) to see decrypted content.
|
||||
- Call DisposeAsync to release the underlying HubConnection and related resources to avoid background network activity.
|
||||
- Event handlers are invoked from the SignalR callbacks — subscribers should ensure any UI updates or shared-state mutations are marshalled to the correct synchronization context or made thread-safe.
|
||||
- Encrypted message content is represented by the `LockedMessagePlaceholder` when the client lacks the room key; rejoining the channel with the passphrase (and so populating [`RoomKeyStore`](RoomKeyStore.cs.md)) is required to decrypt those contents.
|
||||
- `IsConnected` reflects the underlying `HubConnection.State` at the moment of access and may change shortly after; use `OnConnectionStateChanged` and `OnReconnected` for lifecycle-driven logic.
|
||||
- Attempting to join a password-protected channel can surface a `ChannelPasswordRequiredException` — callers that perform join flows should handle that explicitly.
|
||||
|
||||
---
|
||||
|
||||
@@ -93,31 +75,10 @@ public sealed class RoomLockedException : Exception
|
||||
```
|
||||
|
||||
|
||||
Thrown to signal a security-sensitive condition when attempting to send a message into an end-to-end encrypted channel whose room key isn't cached. The operation is blocked to prevent sending plaintext; catching this exception lets the UI prompt for the channel's passphrase and unlock the room before retrying.
|
||||
`RoomLockedException` is thrown when attempting to send into an end-to-end encrypted channel whose room key isn’t cached. Without the key, the operation would emit plaintext, which must never happen, so the exception blocks the send. The `ChannelName` property exposes which channel is locked, and the constructor formats the failure message to include `#{channelName}` to guide unlocking.
|
||||
|
||||
## Remarks
|
||||
|
||||
RoomLockedException acts as a clear boundary between encryption policy and transport logic. By exposing the ChannelName, callers can present a channel-scoped unlock prompt without parsing the error text, and the sealed Exception type communicates a concrete, expected failure mode that downstream code can handle distinctly from generic errors.
|
||||
|
||||
## Example
|
||||
|
||||
```csharp
|
||||
try
|
||||
{
|
||||
// Simulated scenario: an attempt to send into a locked E2E channel
|
||||
throw new RoomLockedException("Lobby");
|
||||
}
|
||||
catch (RoomLockedException ex)
|
||||
{
|
||||
// Use the information to drive the unlock UX
|
||||
Console.WriteLine(ex.Message);
|
||||
Console.WriteLine($"Unlock channel: {ex.ChannelName} by entering its passphrase.");
|
||||
}
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Do not swallow this as a generic error; catch RoomLockedException to trigger the unlock UX and use ex.ChannelName to identify the affected channel. The displayed message is user-facing and not localized.
|
||||
This exception acts as a boundary between encryption state and message-sending logic. It is a domain-level signal distinct from other transport or I/O failures, enabling callers to trigger a user prompt to unlock the channel and retry the operation once unlocked. The `ChannelName` property ties the failure to a specific channel, enabling precise remediation flows.
|
||||
|
||||
---
|
||||
|
||||
@@ -138,21 +99,12 @@ public sealed record JoinOutcome(List<MessageDto> History, string? EncryptionSal
|
||||
| `WrappedRoomKey` | `string?` | — |
|
||||
|
||||
|
||||
JoinOutcome is a sealed record that represents the result of joining a channel: it includes the decrypted history (History) and, for end-to-end encrypted channels, the key envelope necessary to unlock the room's content key (WrappedRoomKey). EncryptionSalt is the salt used to derive the encryption key when applicable. This type is typically produced by the join logic and consumed by the UI to render messages and initialize decryption if needed.
|
||||
Represents the result of joining a channel: the decrypted message history and, for end-to-end encrypted rooms, the key envelope needed to unlock the room content key. `History` is a `List<MessageDto>` containing the decrypted messages, and `WrappedRoomKey` (with optional `EncryptionSalt`) provides the cryptographic envelope when encryption is in play.
|
||||
|
||||
## Remarks
|
||||
This abstraction centralizes the outcome of a join into a single, immutable value that downstream components can rely on. The History is always present (even if empty), while EncryptionSalt and WrappedRoomKey are nullable to reflect that some rooms are not end-to-end encrypted or that keys may not be provisioned yet. By grouping history and encryption metadata together, the join logic can separate concerns: rendering chat versus handling cryptographic setup.
|
||||
|
||||
## Example
|
||||
|
||||
```csharp
|
||||
using System.Collections.Generic;
|
||||
|
||||
List<MessageDto> history = new List<MessageDto>();
|
||||
var joinResult = new JoinOutcome(history, null, null);
|
||||
```
|
||||
By encapsulating the join outcome in a single type, the caller can render history and prepare for decryption in one step. The nullable `WrappedRoomKey` and `EncryptionSalt` signal whether encryption is active for the channel; callers not using end-to-end encryption can ignore them. This keeps the join path concise while preserving a clear contract about what data is available after join.
|
||||
|
||||
## Notes
|
||||
- EncryptionSalt and WrappedRoomKey can be null; callers should verify non-null before attempting decryption-related steps.
|
||||
- `EncryptionSalt` and `WrappedRoomKey` are nullable; guard for nulls and only attempt decryption when these values are provided.
|
||||
|
||||
---
|
||||
@@ -19,16 +19,17 @@ public static class NativeFolderPicker
|
||||
```
|
||||
|
||||
|
||||
Opens the OS-native folder picker by shelling out to the host OS, keeping the TUI free of GUI toolkit dependencies. It supports Windows, macOS, and Linux by delegating to platform-specific helpers and returns a FolderPickResult that communicates whether a folder was chosen, the dialog was cancelled, or the native picker is unavailable so the caller can fall back to a configured path.
|
||||
Opens the OS-native folder chooser by shelling out to platform-specific dialogs (Windows Explorer, macOS Finder, Linux GTK/KDE), allowing the TUI to remain GUI-toolkit agnostic. It dispatches to the appropriate platform helper at runtime and returns a `FolderPickResult` with a `PickerOutcome` of `Unavailable` when no native dialog can run, so callers can fall back to a configured path. Failures are caught and logged to avoid crashing the UI, and the dialog title is a fixed prompt guiding the user to select EchoHub’s download folder.
|
||||
|
||||
## Remarks
|
||||
|
||||
NativeFolderPicker centralizes cross-platform behavior for obtaining a folder path without pulling in a GUI toolkit. It hides OS differences behind a single entry point, PickFolderAsync, and exposes a uniform result type (FolderPickResult with a PickerOutcome) that callers can inspect to either proceed with the chosen path or fall back to defaults. Failures are caught and logged, ensuring graceful degradation rather than exceptions propagating to the UI.
|
||||
By shielding native dialogs behind `NativeFolderPicker`, the rest of the application stays decoupled from platform GUI toolkits, improving portability and testability. The abstraction also centralizes cross‑platform quirks (Windows PowerShell quoting, AppleScript invocation, and GTK/KDialog fallbacks) in one place, reducing duplication and ensuring a consistent user experience across environments.
|
||||
|
||||
## Notes
|
||||
- Linux will not attempt a graphical picker if no graphical session is detected (DISPLAY or WAYLAND_DISPLAY are missing); in that case, the method returns Unavailable.
|
||||
- On Windows, the initial directory is sanitized (apostrophes are doubled) to safely embed the path in the PowerShell script, and PowerShell is invoked via an encoded command to avoid quoting issues.
|
||||
- If the platform-specific helper cannot be started, the code falls back to returning Unavailable instead of throwing, allowing callers to implement their own fallback strategy.
|
||||
|
||||
- Headless Linux environments (no `DISPLAY` or `WAYLAND_DISPLAY`) cause the picker to return `PickerOutcome.Unavailable`.
|
||||
- Windows path handling escapes apostrophes in the initial directory to survive the embedded PowerShell script.
|
||||
- If the user cancels the dialog or no path is selected, the result is `PickerOutcome.Cancelled` rather than an error; callers should handle this as a user action.
|
||||
|
||||
---
|
||||
|
||||
@@ -48,22 +49,16 @@ public sealed record FolderPickResult(PickerOutcome Outcome, string? Path)
|
||||
| `Path` | `string?` | — |
|
||||
|
||||
|
||||
FolderPickResult is an immutable data carrier that represents the outcome of a native folder-picking operation and, when successful, the path of the selected folder.
|
||||
FolderPickResult is an immutable data container that captures the result of a native folder picker operation. It pairs the `PickerOutcome` with an optional `Path`, letting callers distinguish between a successful selection and cancellation while carrying the selected folder path only when available.
|
||||
|
||||
## Remarks
|
||||
Because FolderPickResult is a record, it benefits from value-based equality and straightforward pattern matching when consumed by calling code. The Path member is nullable to reflect that a folder may not be selected; always check the Outcome before using Path. This abstraction decouples application logic from platform-specific picker implementations, promoting testability and cross-platform compatibility.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
var result = new FolderPickResult(PickerOutcome.Success, @"C:\Projects");
|
||||
if (result.Outcome == PickerOutcome.Success && result.Path is not null)
|
||||
{
|
||||
Console.WriteLine(result.Path);
|
||||
}
|
||||
```
|
||||
As a `record`, `FolderPickResult` benefits from value-based equality and supports deconstruction, enabling concise comparisons and pattern matching when consuming results from the native folder picker. It encapsulates the outcome and potential path in a single, strongly-typed value, simplifying higher-level handling and reducing the need for multiple disparate return values.
|
||||
|
||||
## Notes
|
||||
- Path may be null when Outcome indicates cancellation or failure; always verify Outcome before accessing Path.
|
||||
|
||||
- `Path` is nullable; validate before use and prefer accessing `Path` only when `Outcome` indicates a successful result.
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -83,14 +78,32 @@ public enum PickerOutcome
|
||||
```
|
||||
|
||||
|
||||
PickerOutcome encodes the result of attempting to display a native folder picker. It defines three mutually exclusive states: Chosen (the user picked a folder and FolderPickResult.Path is set), Cancelled (the native dialog ran but no selection was made), and Unavailable (no native picker is available on the current machine).
|
||||
|
||||
Use this enum to drive post-pick logic without scattering platform checks or error handling across call sites.
|
||||
Represents the outcome of prompting the user to pick a folder via the native picker. Use it to branch logic based on whether the user selected a folder, cancelled the dialog, or the environment doesn't provide a picker.
|
||||
|
||||
## Remarks
|
||||
This enum serves as a lightweight sum type for the outcome of a folder-picking operation. It centralizes decision points and pairs with FolderPickResult to obtain the actual path when Chosen is returned. Consumers can implement a fallback flow for Unavailable and provide a smooth user experience when Cancelled.
|
||||
By isolating the three possible results into a single enum, callers can write concise, robust code without tying their logic to UI details. The Cancelled and Unavailable outcomes allow you to differentiate between a user-initiated abort and a runtime environment where the picker isn't present, enabling graceful fallbacks. Tie the Chosen outcome to a corresponding `FolderPickResult` instance that carries the selected path in its `Path` property.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
// Example: respond to folder-picking outcomes
|
||||
public void HandleOutcome(PickerOutcome outcome, FolderPickResult folderPath)
|
||||
{
|
||||
switch (outcome)
|
||||
{
|
||||
case PickerOutcome.Chosen:
|
||||
Console.WriteLine($"Selected folder: {folderPath.Path}");
|
||||
break;
|
||||
case PickerOutcome.Cancelled:
|
||||
// User cancelled the dialog; no folder selected.
|
||||
break;
|
||||
case PickerOutcome.Unavailable:
|
||||
// Fall back to a non-UI flow
|
||||
break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Notes
|
||||
- Unavailable is not an error; it indicates the absence of a native picker and warrants a fallback strategy (e.g., a non-native picker or manual path entry).
|
||||
- Do not access `FolderPickResult.Path` when outcome is not `PickerOutcome.Chosen`.
|
||||
|
||||
---
|
||||
@@ -8,12 +8,16 @@ public class NotificationSoundService
|
||||
```
|
||||
|
||||
|
||||
NotificationSoundService centralizes the playback of the notification sound. It resolves the sound file from configuration (if specified and found) or falls back to a bundled default, then plays the sound at a configurable volume when requested. The service exposes SetEnabled and SetVolume for simple runtime tuning, and PlayAsync for normal operation or PlayTestAsync for QA scenarios where playback should occur regardless of the Enabled flag. Internally it uses a semaphore to serialize concurrent playback, and a 10-second timeout to prevent a stuck caller if the sound does not finish.
|
||||
NotificationSoundService coordinates playback of the application's notification sound using a configurable file path and volume. It exposes `PlayAsync` for normal operation (respecting the `Enabled` setting) and `PlayTestAsync` to audition the sound regardless of that setting; internally it resolves the sound path, applies the configured volume, and uses a `SemaphoreSlim` lock plus a timeout (`PlaybackTimeout`) to avoid blocking future notifications.
|
||||
|
||||
## Remarks
|
||||
The class isolates all concerns around audio playback: path resolution, volume handling, concurrency, and fault tolerance. By hiding these details behind a single service, higher-level notification logic can simply request a sound without worrying about file presence, logging, or synchronization. The design anticipates environments where a sound file might be missing or playback might stall, and it ensures resources are released and the system remains responsive.
|
||||
|
||||
Architecturally, this class centralizes notification sound behavior so callers don't need to touch the `_player` or handle `PlaybackFinished` events directly. It encapsulates path resolution: first a user-configured path (`_config.SoundFile`), if present and exists, else a bundled default at `Path.Combine(AppContext.BaseDirectory, "Assets", "Notification.mp3")`. The combination of a serializing lock (`_lock`) and a guarded finish path ensures only one sound plays at a time and that resources are released promptly even if playback misbehaves.
|
||||
|
||||
The playback flow subscribes to `_player.PlaybackFinished` and uses a `TaskCompletionSource` to await either completion or the timeout; this design guarantees the lock is released even if playback misfires or completes synchronously.
|
||||
|
||||
## Notes
|
||||
- Silent fallback if a sound file cannot be found; production environments should ensure the asset exists if audible alerts are required.
|
||||
- The PlaybackFinished event and the 10-second timeout guard the system against hangs; the lock may be released before the sound finishes, which means subsequent playback requests can start while a prior one is still playing.
|
||||
- PlayAsync respects the Enabled flag, while PlayTestAsync allows testing the sound regardless of Enabled.
|
||||
|
||||
- If no valid sound file is found, notifications will be silent (log: "No notification sound file found — notifications will be silent").
|
||||
- `PlayAsync` will early-return if `_config.Enabled` is false or `_resolvedSoundPath` is null; `PlayTestAsync` will still return early if `_resolvedSoundPath` is null. Both rely on a correctly resolved path to function.
|
||||
- The `_lock` is released in a `finally` block to guarantee progress even when exceptions occur.
|
||||
@@ -21,26 +21,10 @@ public sealed record OutgoingAttachment(
|
||||
| `EncryptedPreview` | `string?` | `null` |
|
||||
|
||||
|
||||
OutgoingAttachment is a transport object that represents a single file to upload as part of a message. It bundles the data Stream and FileName, and optionally carries DeclaredKind and EncryptedPreview for encrypted channels, while non-encrypted channels typically set only Stream and FileName.
|
||||
OutgoingAttachment is a compact, immutable data carrier that bundles the pieces needed to upload a file as part of a message: the content as a `Stream` and the original `FileName`. When using end-to-end encrypted channels, `DeclaredKind` signals the attachment type (image, audio, or file) and `EncryptedPreview` holds the room-encrypted ASCII preview for images; on normal channels, only `Stream` and `FileName` are populated.
|
||||
|
||||
## Remarks
|
||||
OutgoingAttachment serves as a compact, immutable data carrier that travels through the sending pipeline. As a record, it uses value-based equality which helps comparisons and deduplication when attachments are tracked across requests. It also clarifies ownership: the record does not manage the lifetime of the underlying Stream; callers are responsible for opening and disposing streams as appropriate.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
using System.IO;
|
||||
|
||||
// Normal channel usage: only Stream and FileName are provided
|
||||
var data = new byte[] { 0x01, 0x02, 0x03 };
|
||||
var stream = new MemoryStream(data);
|
||||
var attachment = new OutgoingAttachment(stream, "data.bin");
|
||||
|
||||
// End-to-end encrypted channel usage: DeclaredKind and EncryptedPreview are set
|
||||
var ciphertext = new MemoryStream(new byte[] { 0xAA, 0xBB, 0xCC });
|
||||
var asciiPreview = @"ASCII_ART_PREVIEW";
|
||||
var encryptedAttachment = new OutgoingAttachment(ciphertext, "image.png", "image", asciiPreview);
|
||||
```
|
||||
As a `record`, `OutgoingAttachment` provides value-based equality, making attachments easy to compare, cache, or deduplicate as they traverse the messaging pipeline. The optional `DeclaredKind` and `EncryptedPreview` fields separate transport payload from encryption/presentation concerns, keeping encoding logic out of the transport object.
|
||||
|
||||
## Notes
|
||||
- The lifetime of the underlying Stream is not managed by OutgoingAttachment; the caller must ensure the stream is disposed when appropriate.
|
||||
- DeclaredKind and EncryptedPreview are intended for encrypted channels; in normal channels these values are typically null.
|
||||
- If `DeclaredKind` is provided for an encrypted attachment, ensure `EncryptedPreview` is also supplied to avoid inconsistent previews.
|
||||
@@ -8,17 +8,19 @@ public static class PathSetup
|
||||
```
|
||||
|
||||
|
||||
PathSetup is a cross-platform helper that ensures the application's directory is present on the system PATH, enabling commands like echohub to be run from any terminal session without specifying the full path. EnsureOnPath checks for the directory and, if missing, updates PATH in a platform-appropriate way: Windows updates the user PATH; Unix-like systems append an export line to common shell profile files.
|
||||
PathSetup is a small helper that ensures the application's directory is present on the system PATH so users can run the `echohub` CLI from any terminal without specifying the full path. The public entry point, `EnsureOnPath`, checks the current PATH and, if the app directory isn't already included, updates PATH in a platform-appropriate way: Windows adds the directory to the user-level PATH, while Unix-like systems append an export line to common shell profile files. The implementation derives the target directory from `AppContext.BaseDirectory`, normalizes path separators, and gracefully handles failures by logging at the debug level if PATH modification cannot be completed.
|
||||
|
||||
## Remarks
|
||||
By centralizing PATH manipulation, this abstraction reduces code duplication and the risk of divergent PATH states across platforms. It uses a lightweight, best-effort approach and logs outcomes to aid diagnostics when PATH updates fail or are skipped. The addition is clearly marked by a PathMarker to avoid duplicating lines in shell profiles.
|
||||
PathSetup centralizes platform-specific PATH augmentation behind a simple, testable API. It makes the side-effect of PATH modification explicit and isolated from business logic, reducing duplication and potential inconsistencies across the codebase. The class uses an idempotent approach: it first checks whether the directory is already on PATH and only proceeds if needed. On Unix-like systems, it uses a persistent marker (`# Added by EchoHub`) to identify its export line in shell profiles, and it guards against duplicating entries. The combination of platform-specific handling, guarded writes, and informative logging ensures predictable behavior during installation and first-run setup while minimizing surprises for end users.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
// Typical usage during installation or first-run setup
|
||||
PathSetup.EnsureOnPath();
|
||||
```
|
||||
|
||||
## Notes
|
||||
- The method swallows exceptions and logs at debug level, so callers should not rely on exceptions to signal failure.
|
||||
- Unix updates affect the user's shell environment; new terminal sessions are typically required to observe changes.
|
||||
- Windows updates are done at the per-user level; system-wide PATH is not modified.
|
||||
- On Windows, the path update affects only the current user by modifying the user PATH environment variable, avoiding system-wide changes.
|
||||
- On Unix-like systems, the code appends a PATH export line to common shell profiles (``.profile``, ``.bashrc``, ``.zshrc``); it skips profiles that already contain the app directory and creates ``~/.profile`` as a fallback when no profiles exist.
|
||||
- A persistent marker (``# Added by EchoHub``) helps avoid duplicating the export line on repeated runs.
|
||||
- The operation is best observed after restarting terminals or re-sourcing profiles; until that point, newly opened sessions may not reflect the updated PATH.
|
||||
|
||||
@@ -8,23 +8,9 @@ public sealed class RoomKeyProtector
|
||||
```
|
||||
|
||||
|
||||
Encrypts cached room content keys at rest so the client config never holds them as plain base64. Windows uses DPAPI (current-user scope, format prefix "dp1:"). On other platforms the keys are AES-GCM encrypted with a per-user master key file stored next to the config with 0600 permissions (prefix "k1:") — without an OS keychain that is file-permission-level protection, not zero-knowledge: anyone who can read both the config and the key file can recover the room keys. Values with no recognized prefix are legacy plain-base64 keys from older clients; they load once and are re-encrypted. The room passphrase itself is never stored in any form.
|
||||
Encrypts cached room content keys at rest so the client config never holds them as plain base64. Windows uses DPAPI (current-user scope, format prefix `dp1:`). On other platforms the keys are AES-GCM encrypted with a per-user master key file stored next to the config with permissions 0600 (prefix `k1:`) — without an OS keychain that is file-permission-level protection, not zero-knowledge: anyone who can read both the config and the key file can recover the room keys. Values with no recognized prefix are legacy plain-base64 keys from older clients; they load once and are re-encrypted. The room passphrase itself is never stored in any form.
|
||||
|
||||
The RoomKeyProtector class provides a single API surface to protect and unprotect per-user room keys across platforms. The Protect method returns a string suitable for storage in the config, automatically selecting the appropriate protection mechanism for the current OS (DPAPI on Windows, file-based AES-GCM on others). TryUnprotect decodes a stored value back into a room key, reporting whether the value was a legacy (unencrypted) entry and whether the decryption succeeded. The implementation intentionally hides platform differences behind a consistent interface, so callers can persist and reload keys without worrying about the underlying cryptosystem.
|
||||
|
||||
The constructor accepts a directory that holds the master key file and an optional flag to override the OS-provided protection path (useful for tests). The key file path is derived from the directory by appending the fixed file name roomkeys.key. Key loading is guarded by a small lock and the master key is cached after the first read. The Protect path prefixes the output to indicate how the data is protected ("dp1:" or "k1:").
|
||||
|
||||
The class ensures the room passphrase itself is never persisted, and it gracefully tolerates missing or unreadable key material by returning false from TryUnprotect (leaving the caller to prompt the user for action).
|
||||
|
||||
````csharp
|
||||
// Typical usage
|
||||
var protector = new RoomKeyProtector("/config");
|
||||
byte[] roomKey = new byte[32]; // obtain from a secure source
|
||||
string stored = protector.Protect(roomKey);
|
||||
|
||||
if (protector.TryUnprotect(stored, out var recovered, out bool wasLegacy))
|
||||
{
|
||||
// recovered contains the room key if the value was decryptable
|
||||
// wasLegacy is true only if the input was a legacy base64 key without a prefix
|
||||
}
|
||||
````
|
||||
The primary public surface consists of:
|
||||
- `Protect(byte[] roomKey)`: encrypts a room key for storage in the config.
|
||||
- `TryUnprotect(string stored, out byte[] roomKey, out bool wasLegacy)`: decrypts a stored value back into a room key.
|
||||
The class caches the per-user master key and selects the protection mechanism based on the platform (DPAPI on Windows when enabled, otherwise the per-user master-key path). It also handles migration of legacy entries by re-encrypting them using the active scheme on subsequent saves. The constants `DpapiPrefix` and `KeyFilePrefix` label the on-disk formats, ensuring callers remain agnostic to the underlying storage strategy.
|
||||
@@ -8,36 +8,12 @@ public sealed class RoomKeyStore
|
||||
```
|
||||
|
||||
|
||||
Holds and manages end-to-end encrypted room keys for a single client instance: it keeps a decrypted, in-memory cache for the active session and a per-server persisted, encrypted copy so users do not have to re-enter passphrases each launch. Use RoomKeyStore when you need a thread-safe local store that provides room keys to the runtime and ensures keys are encrypted at rest via RoomKeyProtector.
|
||||
Holds and manages room content keys for end-to-end encrypted channels for the active session and the persisted per-server client configuration. Use `RoomKeyStore` when you need a single place to cache decrypted room keys in memory, persist them encrypted to the local config (so users don't retype passphrases on each launch), and track which channels are known to be end-to-end encrypted.
|
||||
|
||||
## Remarks
|
||||
RoomKeyStore links transient runtime state with the client's persisted configuration. It binds to a server (LoadForServer), loads that server's saved ChannelKeys (unprotecting them with RoomKeyProtector), and exposes methods to read, add, replace, or remove keys while persisting changes back to the SavedServer entry. It also records which channels are known to be encrypted so callers can avoid emitting plaintext into rooms without a cached key. The class performs a one-way upgrade of legacy unprotected entries to the protected format when possible and logs unreadable entries rather than failing.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
var store = new RoomKeyStore();
|
||||
store.LoadForServer("https://chat.example.com");
|
||||
|
||||
// Generate and store a new room key for a channel
|
||||
byte[] newKey = RoomCrypto.GenerateRoomKey();
|
||||
store.StoreKey("#team-room", newKey);
|
||||
|
||||
// Retrieve a key for sending encrypted messages
|
||||
if (store.TryGetKey("#team-room", out var key))
|
||||
{
|
||||
// Use `key` with RoomCrypto API to encrypt message content
|
||||
}
|
||||
|
||||
// Accept an encrypted envelope and store the unwrapped key only if the KEK opens it
|
||||
string wrapped = "..."; // envelope string received
|
||||
byte[] kek = /* key-encryption-key */ new byte[RoomCrypto.KeySizeBytes];
|
||||
if (store.TryStoreFromEnvelope("#other-room", wrapped, kek))
|
||||
{
|
||||
// successfully unwrapped and cached
|
||||
}
|
||||
```
|
||||
`RoomKeyStore` is the in-process authority for room keys: it keeps a memory cache (`_keys`) for the running session and a set (`_encryptedChannels`) to mark channels that are treated as encrypted. It delegates on-disk protection to [`RoomKeyProtector`](RoomKeyProtector.cs.md) so keys never leave the machine in plaintext. Calling `LoadForServer` binds the store to a specific server URL, loads that server's `SavedServer.ChannelKeys` via `ConfigManager.Load()`, and hydates the in-memory cache (skipping unreadable entries). Legacy plaintext/legacy-storage entries detected by `RoomKeyProtector.TryUnprotect` are re-encrypted and re-persisted as a one-way upgrade. All public mutation and lookup methods synchronize on the internal `Lock` (`_lock`) to provide basic thread-safety for concurrent callers.
|
||||
|
||||
## Notes
|
||||
- Call LoadForServer(serverUrl) before persisting or retrieving server-scoped keys; the store clears and reinitializes its cache when bound to a server.
|
||||
- Legacy (plain/base64) saved entries are upgraded to the protector-backed format when possible; entries that cannot be unprotected are ignored and logged.
|
||||
- The class uses an internal lock for basic thread-safety of the in-memory cache; avoid holding returned keys while performing long synchronous work that might race with store mutations.
|
||||
- `TryGetKey` returns the stored byte array reference from the internal `_keys` map (no defensive copy). Callers must not mutate the returned `byte[]` in-place — clone it first if modification is required.
|
||||
- Channel name lookup is case-insensitive because the internal collections use `StringComparer.OrdinalIgnoreCase`. Treat channel names consistently to avoid duplicate/lookup surprises.
|
||||
- Loading ignores unreadable cached entries and will re-persist only entries that [`RoomKeyProtector`](RoomKeyProtector.cs.md) could successfully unprotect; `TryStoreFromEnvelope` returns false when the provided KEK fails to unwrap the envelope and will leave the cache unchanged. Storing or removing a key persists the corresponding `SavedServer.ChannelKeys` entry immediately (via the store's persistence path).
|
||||
@@ -20,15 +20,11 @@ internal partial class BackupJsonContext : System.Text.Json.Serialization.JsonSe
|
||||
```
|
||||
|
||||
|
||||
BackupJsonContext is an internal partial class that provides the source-generated JSON serialization metadata for the BackupInfo type. It plugs into System.Text.Json’s source generator, enabling reflection-free serialization of BackupInfo when you configure a JsonSerializerOptions with this context.
|
||||
Defines a source-generated JSON serialization context for `BackupInfo` by annotating the internal partial class ``BackupJsonContext`` with ``JsonSerializable(typeof(BackupInfo))``. This enables high-performance, reflection-free JSON serialization and deserialization via System.Text.Json's source generator when working with ``BackupInfo``.
|
||||
|
||||
## Remarks
|
||||
This symbol acts as the concrete carrier of serialization metadata for BackupInfo within the JSON pipeline of EchoHub’s client. By centralizing the generated type information in a single context, it keeps serialization concerns isolated from business logic and allows the type to evolve without scattering attributes across multiple call sites. The pattern here—one generated context per data contract—supports predictable performance improvements while preserving a clean, minimal public surface.
|
||||
By centralizing the JSON metadata in ``BackupJsonContext``, the codebase gains a single, version-stable contract for serializing ``BackupInfo``. The generated ```JsonTypeInfo<BackupInfo>``` exposed as ``BackupJsonContext.Default.BackupInfo`` is consumed by ``JsonSerializer`` overloads that accept type metadata, reducing runtime reflection and enabling better inlining and optimization. This scope-limited context also makes it straightforward to extend serialization support to additional related types by extending the same context without changing call-sites.
|
||||
|
||||
## Notes
|
||||
- The symbol is internal; it is intended for use within the containing assembly, not by external callers.
|
||||
- The class is generated and partial; do not edit it by hand, as changes will be overwritten by the source generator.
|
||||
- If you modify the BackupInfo shape, you must re-run code generation to keep the context in sync with the data contract.
|
||||
|
||||
---
|
||||
|
||||
@@ -41,7 +37,7 @@ public static class UpdateBackupService
|
||||
```
|
||||
|
||||
|
||||
Manages pre-update backups for the auto-updater and provides rollback support by snapshotting the running application prior to an update. Backups are stored under ~/.echohub/update-backup/ as backup.zip with a companion backup-info.json that records the version, application directory, and UTC timestamp. Use CreateBackup before applying an update; verify presence with BackupExists and inspect metadata with GetBackupInfo to drive a rollback if needed. The IsPostUpdate flag signals that a backup from a recent update exists, allowing startup logic to react accordingly.
|
||||
UpdateBackupService is a centralized helper that manages pre-update backups and rollback restoration for the auto-updater. It stores backups under the user profile in `~/.echohub/update-backup/` and exposes operations to create a snapshot, verify an existing backup, and read its metadata. Before applying an update, `CreateBackup()` snapshots the current application directory (via `AppContext.BaseDirectory`) into a ZIP named `backup.zip` and writes a `backup-info.json` containing the version, app directory, and timestamp. It skips log files to avoid locking issues, uses `CompressionLevel.Fastest` for speed, and annotates the backup with the current version from `UpdateChecker.CurrentVersion`. `BackupExists()` checks for the presence of both `backup.zip` and `backup-info.json`, while `GetBackupInfo()` reads and deserializes the metadata using `BackupJsonContext.Default.BackupInfo`. The `IsPostUpdate` flag signals that a post-update backup was produced and may influence rollback or recovery flow.
|
||||
|
||||
---
|
||||
|
||||
@@ -65,22 +61,13 @@ public record BackupInfo(
|
||||
| `CreatedAt` | `DateTimeOffset` | — |
|
||||
|
||||
|
||||
BackupInfo is a lightweight, value-like record that encapsulates metadata about a created backup. It carries the backup Version, the AppDirectory that was backed up, and the CreatedAt timestamp, enabling complete backup metadata to be passed around as a single unit.
|
||||
BackupInfo is a `record` that encapsulates the metadata for a backup produced by the application. It aggregates the `Version` string, the `AppDirectory` path where the backup resides, and the creation timestamp `CreatedAt` as a `DateTimeOffset`, providing a single, immutable value that callers can transport, compare, or display without reconstructing individual fields. Use this type whenever you need to pass around a complete snapshot of backup identity and location rather than scattering primitive values.
|
||||
|
||||
## Remarks
|
||||
BackupInfo, being a record with positional parameters, is immutable and benefits from value-based equality. This makes it ideal as a canonical data carrier when the UpdateBackupService reports or persists backup information, or when UI/logging layers need to compare or display backup entries.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
var backup = new BackupInfo(
|
||||
Version: "1.2.3",
|
||||
AppDirectory: "/opt/MyApp",
|
||||
CreatedAt: DateTimeOffset.UtcNow
|
||||
);
|
||||
```
|
||||
Because `BackupInfo` is a `record`, it provides value-based equality and immutability, so two backups with the same `Version`, `AppDirectory`, and `CreatedAt` compare as equal. This makes it ideal as a transport object across service boundaries and as a stable key or result in collections. It also supports deconstruction, enabling concise extraction of its three fields when needed.
|
||||
|
||||
## Notes
|
||||
- Records provide structural equality; two instances with the same Version, AppDirectory, and CreatedAt compare as equal.
|
||||
- CreatedAt uses DateTimeOffset to preserve offset information; prefer UTC (DateTimeOffset.UtcNow) when constructing backups to avoid timezone ambiguities.
|
||||
- This object is immutable; its properties are set at construction time and cannot be changed afterward.
|
||||
- The `CreatedAt` value uses `DateTimeOffset` to preserve the exact point in time including offset, which is important for cross-system backups and logs.
|
||||
|
||||
---
|
||||
@@ -8,29 +8,30 @@ public sealed class UpdateChecker : IDisposable
|
||||
```
|
||||
|
||||
|
||||
Checks for application updates in the background, presents a TUI confirmation dialog when a new version is available, and defers the actual download/extract/restart work until after the terminal UI has been shut down. Use this class when the host application runs a Terminal.Gui main loop and needs a safe way to offer in-place updates without deadlocking the console or performing heavy I/O while the TUI still owns the terminal.
|
||||
Checks for application updates on a background schedule and coordinates a safe, post-TUI update process. Use `UpdateChecker` when you want automatic or on-demand update checks inside a Terminal.Gui-based host but need the actual download/extract/restart work to run after the UI main loop has exited.
|
||||
|
||||
## Remarks
|
||||
This class encapsulates polling and manual update checks via an internal Updater instance and marshals user interaction back onto the provided IApplication main loop using _app.Invoke. When the user confirms an update, UpdateChecker does not perform the network/download work immediately; instead it sets PendingUpdate to an awaitable callback (ApplyUpdateAsync), stores the selected version, and requests the TUI to stop. The host is expected to call PendingUpdate after the main loop exits and the console has been restored so the update process can safely run headless (the Updater's update flow may restart the process and call Environment.Exit).
|
||||
`UpdateChecker` encapsulates the interaction between the UI, a periodic `Updater` and the host process that must perform the actual update. It listens for `Updater` events and, when the user confirms an update via `UpdateConfirmDialog.Show`, sets the public [`PendingUpdate`](../AppOrchestrator.cs.md) delegate and requests the UI to stop so the host can perform the heavy work on a plain console. This design avoids the console deadlock that would occur if the updating process tried to restart while the Terminal.Gui main loop still owned the console. `CurrentVersion` exposes the assembly version used in the confirmation UI.
|
||||
|
||||
## Example
|
||||
```csharp
|
||||
// During application startup
|
||||
var updateChecker = new UpdateChecker(app);
|
||||
updateChecker.Start(); // starts periodic checks in RELEASE builds
|
||||
var checker = new UpdateChecker(app);
|
||||
checker.Start(); // starts periodic checks in RELEASE builds
|
||||
|
||||
// ... run Terminal.Gui main loop ...
|
||||
// Trigger a manual check from UI or command handler
|
||||
await checker.CheckNowAsync();
|
||||
|
||||
// After the main loop exits and the console is restored, run any pending update
|
||||
if (updateChecker.PendingUpdate != null)
|
||||
// After the Terminal.Gui main loop exits, the host should run any pending update
|
||||
if (checker.PendingUpdate != null)
|
||||
{
|
||||
await updateChecker.PendingUpdate();
|
||||
await checker.PendingUpdate(); // will download/extract and may restart the process
|
||||
}
|
||||
```
|
||||
|
||||
## Notes
|
||||
- Start only activates the background poller in RELEASE builds (the Start method is no-op in non-RELEASE builds).
|
||||
- PendingUpdate is deliberately set to a Task-returning delegate and intended to be invoked by the host after the TUI has fully stopped; running it while the TUI still owns the console can deadlock the restart flow.
|
||||
- ApplyUpdateAsync attempts to create a pre-update backup with UpdateBackupService.CreateBackup; backup creation failures are logged and the update continues.
|
||||
- ApplyUpdateAsync sets Console.OutputEncoding = UTF8 but swallows exceptions (useful when stdout is redirected or non-interactive).
|
||||
- CurrentVersion reads the assembly version and falls back to "0.0.0" if unavailable.
|
||||
- [`PendingUpdate`](../AppOrchestrator.cs.md) is only set when the user confirms an available update via `UpdateConfirmDialog.Show`; the host must check and invoke [`PendingUpdate`](../AppOrchestrator.cs.md) after the TUI main loop exits.
|
||||
- `Start()` is conditional on the `RELEASE` build symbol — in non-RELEASE builds the periodic checker does not run.
|
||||
- Invoking the [`PendingUpdate`](../AppOrchestrator.cs.md) delegate runs the updater on a plain console and may end by restarting the app (the code calls into the `Updater` which performs download/extract/restart). The host should not expect normal process continuation after the update completes.
|
||||
- `CurrentVersion` reads the assembly version and will return `"0.0.0"` if the assembly version cannot be determined.
|
||||
- Backup creation is attempted via `UpdateBackupService.CreateBackup()` before applying an update; failures are logged and the update continues without a backup.
|
||||
@@ -8,12 +8,7 @@ internal sealed class UserSession
|
||||
```
|
||||
|
||||
|
||||
Stores the current user's session state on the client, including username, online status, and an optional status message. Use this type as a lightweight, centralized container when you need to read or mutate the ephemeral session data for the active user, and call Reset to return all fields to their defaults (empty username, Online status, and no status message).
|
||||
Represents the current user\'s session state within the client, encapsulating the `Username`, the presence `Status` from [`UserStatus`](../../EchoHub.Core/Models/UserStatus.cs.md), and an optional `StatusMessage`. It is a lightweight in-memory container used by UI and networking layers to track who is logged in and how they present themselves. The `Reset` method reinitializes all fields to their defaults: `Username` to empty, `Status` to `UserStatus.Online`, and `StatusMessage` to `null`.
|
||||
|
||||
## Remarks
|
||||
Internally sealed and non-public, this class keeps the session representation stable within the client service layer and prevents inheritance. It relies on the UserStatus enum from the core models to express the user's current state consistently across the application.
|
||||
|
||||
## Notes
|
||||
- Not thread-safe by default; coordinate concurrent access if used from multiple threads.
|
||||
- Reset mutates state in place; if you require preserving data, capture it before calling Reset.
|
||||
- StatusMessage is nullable; null indicates that no message is provided.
|
||||
This small class centralizes session-related data so multiple components can read and update the user\'s identity and presence from a single source of truth. By being `internal` and `sealed`, it communicates that this is an implementation detail of the client assembly and should not be extended or exposed publicly.
|
||||
Reference in New Issue
Block a user