docs: Update documentation for 145 files

Generated by AurionDocs Job ID: c99fff50-67a3-4294-b4df-3e73f4f12de9 Source commit: 4dcb480
2026-09-05 15:46:01 +02:00 · 2026-07-23 08:10:35 +02:00
parent 4dcb480d1d
commit f8f4e03ddd
145 changed files with 22779 additions and 0 deletions
@@ -0,0 +1,99 @@
+# ServerLogsService.cs
+
+> **Source:** `src/EchoHub.Server/Services/ServerLogs/ServerLogsService.cs`
+
+*Figure: How ServerLogsService works.*
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'background':'#faf7ef','primaryColor':'#f0e2c2','primaryTextColor':'#1f2840','primaryBorderColor':'#8a7548','secondaryColor':'#d9efec','secondaryBorderColor':'#1d8a80','secondaryTextColor':'#1f2840','tertiaryColor':'#f2ebd8','tertiaryBorderColor':'#8a7548','tertiaryTextColor':'#1f2840','lineColor':'#1d8a80','titleColor':'#1f2840','fontSize':'14px','edgeLabelBackground':'#faf7ef','clusterBkg':'#f2ebd8','clusterBorder':'#8a7548','actorBkg':'#f0e2c2','actorBorder':'#8a7548','actorTextColor':'#1f2840','actorLineColor':'#8a7548','signalColor':'#1d8a80','signalTextColor':'#1f2840','activationBkgColor':'#d9efec','activationBorderColor':'#1d8a80','noteBkgColor':'#f2ebd8','noteBorderColor':'#8a7548','noteTextColor':'#1f2840','labelBoxBkgColor':'#f0e2c2','labelBoxBorderColor':'#8a7548','labelTextColor':'#1f2840','transitionColor':'#1d8a80','transitionLabelColor':'#1f2840','stateLabelColor':'#1f2840','altBackground':'#f2ebd8'}}}%%
+flowchart TB
+A[ServerLogsService ReadBacklog]
+A --> B[Resolve ServerLogsOptions LogDirectory]
+B --> Dir{Directory exists}
+Dir -->|Yes| C[Find newest file matching LogFilePattern]
+Dir -->|No| E[Return empty list]
+C --> F{Newest file found}
+F -->|No| E
+F -->|Yes| G[Open newest file with FileShare ReadWrite Delete then seek to tail when stream longer than TailReadBytes]
+G --> H[Read to end and split by newline into lines]
+H --> I[Group lines into LogBacklogEntry with skipLeadingContinuations if seeked and limit from ServerLogsOptions BacklogLines]
+I --> J[Return list of LogBacklogEntry]
+A -.-> E
+```
+
+## Contents
+
+- [ServerLogsService](#serverlogsservice)
+- [LogBacklogEntry](#logbacklogentry)
+
+---
+
+## ServerLogsService
+> **File:** `src/EchoHub.Server/Services/ServerLogs/ServerLogsService.cs`  
+> **Kind:** class
+
+```csharp
+public sealed class ServerLogsService
+```
+
+
+Provides the logic needed to present a read-only "live logs" room: it exposes the room identity, the role-based gate for who may join, and a best-effort reader that returns the most recent log entries from the active rolling Serilog file. Use this service when you need to show a live, read-only backlog of server log entries (rather than storing log lines as chat messages).
+
+## Remarks
+This class centralizes the concerns required for a live log room: determining the configured room name and sender, enforcing the minimum role required to view logs, and extracting a focused backlog from the current log file on disk. It treats the file sink as the single source of truth (Serilog keeps the file open and rolls it), reads only the tail of the newest file up to a bounded byte size, and groups raw lines into logical entries by detecting timestamp-prefixed lines. ReadBacklog is resilient: any I/O or parsing problem yields an empty backlog rather than propagating an error.
+
+## Example
+```csharp
+// 'options' is an existing ServerLogsOptions instance configured for the server.
+var service = new ServerLogsService(options);
+
+// Check whether a user role may view/join the live logs room
+if (service.CanView(userRole))
+{
+    // Read the most recent backlog entries (best-effort; may be empty on error)
+    var backlog = service.ReadBacklog();
+    foreach (var entry in backlog)
+    {
+        // LogBacklogEntry exposes a timestamp and the concatenated content
+        Console.WriteLine($"{entry.Timestamp:O} {entry.Content}");
+    }
+}
+
+// Room identity helpers
+var isLogs = service.IsLogsChannel("logs");
+var sender = ServerLogsService.SenderName; // "server"
+```
+
+## Notes
+- ReadBacklog swallows all exceptions and returns an empty list on any I/O problem; callers must tolerate an empty backlog as a sign of transient failure or missing files.
+- To avoid reading an arbitrarily large file, the reader seeks to the last TailReadBytes bytes; that can start the scan mid-entry, so the grouping logic optionally drops leading continuation lines when the tail was seeked.
+- The FileStream is opened with FileShare.ReadWrite | FileShare.Delete because the Serilog file sink typically keeps the file open for writing and may roll it; the service reads concurrently without taking exclusive locks.
+
+---
+
+## LogBacklogEntry
+> **File:** `src/EchoHub.Server/Services/ServerLogs/ServerLogsService.cs`  
+> **Kind:** record
+
+```csharp
+public record LogBacklogEntry(DateTimeOffset Timestamp, string Content)
+```
+
+**Parameters:**
+
+| Parameter | Type | Default |
+|-----------|------|---------|
+| `Timestamp` | `DateTimeOffset` | — |
+| `Content` | `string` | — |
+
+
+LogBacklogEntry is a tiny, immutable data container that models a single backlog item read from the server log file. It captures the timestamp of the original log line via Timestamp and the associated log text in Content, which may include the initial line plus any continuation lines (such as exception stack traces) that followed it. Use this type when you need to treat a complete backlog segment as a unit, instead of handling raw lines individually; it’s especially helpful for grouping, displaying, or analyzing backlog entries after parsing.
+
+## Remarks
+Because LogBacklogEntry is a record, it benefits from value-based equality and concise deconstruction, making it easy to compare backlog entries or to extract the fields in pattern-matching. The Content field holds a multi-line string that includes the initial line and any continuation text that followed it; consumers should be aware that the entry may span multiple lines. This type is commonly produced by the server log reader (e.g., ServerLogsService) when assembling backlog entries from the log file, serving as a stable data carrier between parsing and presentation layers.
+
+## Notes
+- When collecting backlog lines, ensure that each entry groups the initial timestamped line with its subsequent continuation lines exactly once; splitting or merging entries incorrectly can corrupt the log's temporal grouping.
+
+
+---
@@ -0,0 +1,19 @@
+# ServerLogsSink
+
+> **File:** `src/EchoHub.Server/Services/ServerLogs/ServerLogsSink.cs`  
+> **Kind:** class
+
+```csharp
+public sealed class ServerLogsSink : ILogEventSink
+```
+
+
+ServerLogsSink is a Serilog sink that feeds the live log room by buffering log events in a bounded channel and exposing them to the streaming pipeline without persisting them. It enforces a minimum log level, filters out internal sources to avoid feedback loops, and writes accepted events into a single-reader queue consumed by the live broadcast path. This sink thus serves as a lightweight, non-persistent conduit for real-time visibility of logging activity.
+
+## Remarks
+The sink decouples log emission from the live broadcast pathway, providing backpressure via a bounded channel (capacity 512) with drop-oldest semantics to prevent unbounded memory growth. Internal pipeline events are culled by inspecting the SourceContext and excluding known internal prefixes, which prevents the log → broadcast → log feedback loop. By not writing to a database, the component prioritizes timely visibility for operators and clients over long-term auditing.
+
+## Notes
+- When the channel is full, TryWrite may return false and the log event will be dropped, ensuring the application does not stall due to logging backpressure.
+- The channel is configured with SingleReader = true, so there is a single consumer in the streaming path; additional readers would not receive the full event sequence.
+- Only events that pass the MinLevel filter and do not originate from excluded internal sources are enqueued for broadcast.
@@ -0,0 +1,48 @@
+# ServerLogsStreamService
+
+> **File:** `src/EchoHub.Server/Services/ServerLogs/ServerLogsStreamService.cs`  
+> **Kind:** class
+
+```csharp
+public sealed class ServerLogsStreamService : BackgroundService
+```
+
+
+Streams queued log events to the live log room as ephemeral SignalR messages, never persisting them to the IRC gateway or a database, and with a guard against introducing new logging from the streaming path itself. It runs as a background service, ensuring the destination room exists before sending each event and recreating it if needed, so live viewers can always join the stream without manual intervention.
+
+## Remarks
+This symbol acts as a thin, resilient bridge between the server-side log sink and the real-time chat hub. It separates the streaming path from log persistence, enforcing a no-log-from-stream policy to avoid feedback loops where streaming would itself generate more log lines. By lazily resolving the hub context, it avoids tight coupling during service construction and ensures the ChatHub context is available when streaming begins. The class also enforces room existence in a lightweight, interval-bounded way to tolerate transient room removal without blocking the live stream.
+
+## Notes
+- The streaming path must never emit logs of its own activity; per-event logging is explicitly suppressed to prevent cascading streams.
+- TryEnsureRoomAsync re-checks the room at most once per EnsureInterval (15 seconds) to balance responsiveness with avoiding repeated recreation attempts.
+- Messages are formatted and then encrypted before sending; the client receives an encrypted payload and is responsible for decrypting it, mirroring the design that prioritizes privacy and transport safety. The public Format method is exposed for tests, reflecting a desire to validate formatting behavior in isolation.
+- If room recreation fails, events are streamed to a group with no members until the next interval, ensuring that the streaming pipeline remains non-blocking and resilient to transient failures.
+
+## Example
+- Not included: non-obvious usage from the signature; the behavior is exercised through the background streaming loop and the TryEnsureRoomAsync room-recovery logic. See the source for exact flow and state transitions. 
+
+## Dependency APIs (verified signatures)
+The REAL, parser-verified API surface of this symbol's collaborators:
+
+- MessageDto (src/EchoHub.Core/DTOs/ChatDtos.cs)
+- Reader (src/EchoHub.Server/Services/ServerLogs/ServerLogsSink.cs)
+- ServerLogsService (src/EchoHub.Server/Services/ServerLogs/ServerLogsService.cs)
+  - SenderName, RoomTopic, TimestampFormat, TailReadBytes
+  - ServerLogsService(ServerLogsOptions options)
+  - Options, IsLogsChannel, CanView(ServerRole)
+  - ReadBacklog(), GroupIntoEntries(`IReadOnlyList<string>`, bool, int)
+  - TryParseTimestamp(string, out DateTimeOffset, out string)
+- HubContext (src/EchoHub.Server/Services/ServerLogs/ServerLogsStreamService.cs)
+- HubConstants (src/EchoHub.Core/Constants/HubConstants.cs)
+  - ChatHubPath, DefaultChannel, IrcConnectionIdPrefix, DefaultHistoryCount, MaxMessageLength
+  - MaxImageSizeBytes, MaxAudioFileSizeBytes, MaxFileSizeBytes, MaxAvatarSizeBytes
+  - MaxMessageNewlines, MaxAttachmentsPerMessage, MaxConsecutiveNewlines
+  - …and 7 more member(s) not shown
+
+## Symbol To Document
+- Name: ServerLogsStreamService
+- Kind: class
+- File: src/EchoHub.Server/Services/ServerLogs/ServerLogsStreamService.cs
+- Language: csharp
+- ID: fe54ac96-642e-4dbe-af25-3d2559e01299