namespace SOR.Networking.WebSocket; using System.Buffers; using System.Net.WebSockets; using Microsoft.Extensions.Logging; using SOR.Networking.Abstractions.Messaging; using SOR.Networking.Abstractions.Transport; /// /// IClientConnection implementation backed by a System.Net.WebSockets.WebSocket. /// /// Key responsibilities: /// - Frame assembly: WebSocket messages can be split across multiple frames. /// ReceiveAsync loops until EndOfMessage = true, assembling into a MemoryStream. /// - Send serialization: only one send can be in flight at a time per WebSocket. /// SemaphoreSlim(1,1) acts as an async mutex on the send path. /// - Ping/pong heartbeat: a background task sends periodic ping frames so /// disconnected clients are detected within one PingIntervalMs cycle. /// /// Thread safety: /// - ReceiveAsync: called only by the ConnectionLoop — no concurrent receive. /// - SendBytesAsync: may be called concurrently (push delivery + reply at same time). /// The _sendLock serializes concurrent sends. /// /// Lifetime: created by WebSocketTransport per accepted connection. /// Disposed by ConnectionLoop.RunAsync() in its finally block. /// public sealed class WebSocketClientConnection : IClientConnection { private readonly System.Net.WebSockets.WebSocket _socket; private readonly WebSocketTransportOptions _options; private readonly ILogger _logger; // SemaphoreSlim(1, 1) is a lightweight async-compatible mutex. // Unlike 'lock', it can be awaited without blocking the thread. private readonly SemaphoreSlim _sendLock = new(1, 1); // CancellationTokenSource for the ping loop. Cancelled on dispose. private readonly CancellationTokenSource _pingSts = new(); // Signals the middleware that this connection's loop has finished, // so the middleware can release the HTTP request cleanly. private readonly TaskCompletionSource _connectionDone; private bool _disposed; public string ConnectionId { get; } public string RemoteAddress { get; } public bool IsConnected => !_disposed && _socket.State == WebSocketState.Open; public WebSocketClientConnection( System.Net.WebSockets.WebSocket socket, string connectionId, string remoteAddress, WebSocketTransportOptions options, ILogger logger, TaskCompletionSource connectionDone) { _socket = socket; ConnectionId = connectionId; RemoteAddress = remoteAddress; _options = options; _logger = logger; _connectionDone = connectionDone; // Start the ping loop in the background immediately. // '_ =' discards the Task intentionally — the loop runs fire-and-forget. // Exceptions inside are caught within the loop and logged. _ = RunPingLoopAsync(_pingSts.Token); } /// /// /// Assembles a complete WebSocket message from one or more frames. /// Returns null on clean close (WebSocketMessageType.Close received). /// Throws WebSocketException on unexpected disconnect — the caller handles it. /// /// ArrayPool{byte}.Shared is used to rent receive buffers from a reusable pool /// rather than allocating a new byte[] per receive. Buffers are returned in finally. /// This is a common pattern for high-throughput .NET networking code. /// public async Task ReceiveAsync(CancellationToken cancellationToken) { // Rent a buffer from the shared pool. The buffer may be larger than requested. // Always use ArrayPool.Return() in a finally block to avoid pool exhaustion. var buffer = ArrayPool.Shared.Rent(_options.MaxMessageSizeBytes); try { using var messageStream = new MemoryStream(); WebSocketReceiveResult result; do { // Receive one frame (may not be the complete message). result = await _socket.ReceiveAsync( new ArraySegment(buffer), cancellationToken); switch (result.MessageType) { case WebSocketMessageType.Close: // Client sent a close frame — clean disconnect. _logger.LogDebug( "WebSocket close received: ConnectionId={ConnectionId} Status={Status}", ConnectionId, result.CloseStatus); return null; case WebSocketMessageType.Text: case WebSocketMessageType.Binary: // Check if this frame would push us over the size limit. if (messageStream.Length + result.Count > _options.MaxMessageSizeBytes) { _logger.LogWarning( "Message too large: ConnectionId={ConnectionId} Limit={Limit}", ConnectionId, _options.MaxMessageSizeBytes); await CloseAsync("message_too_large", cancellationToken); return null; } // Append this frame's bytes to the message buffer. messageStream.Write(buffer, 0, result.Count); break; } // EndOfMessage = true when all frames of this message have arrived. } while (!result.EndOfMessage); // Return the assembled bytes as a RawClientMessage. // The serializer will parse the envelope (type, seq, payload) from these bytes. // We import RawClientMessage from SOR.Networking.Abstractions' concrete type // in SOR.Shared — but this project doesn't reference SOR.Shared. // Solution: return the bytes wrapped in a minimal internal implementation. return new ReceivedMessage(messageStream.ToArray()); } finally { // Always return the rented buffer, even if an exception is thrown. ArrayPool.Shared.Return(buffer); } } /// public async ValueTask SendBytesAsync(ReadOnlyMemory bytes, CancellationToken cancellationToken) { // Acquire the send lock. If another send is in progress, this awaits until it completes. await _sendLock.WaitAsync(cancellationToken); try { if (_socket.State != WebSocketState.Open) return; // Send as a binary frame. EndOfMessage = true (single-frame message). await _socket.SendAsync(bytes, WebSocketMessageType.Binary, true, cancellationToken); } finally { // Always release the lock, even if an exception occurs. _sendLock.Release(); } } /// public async Task CloseAsync(string reason, CancellationToken cancellationToken) { if (_socket.State != WebSocketState.Open) return; try { // Send a close frame with a normal closure status. // The client should respond with its own close frame, completing the handshake. await _socket.CloseAsync( WebSocketCloseStatus.NormalClosure, reason, cancellationToken); } catch (Exception ex) { // If the close handshake fails (client already gone), log and continue. _logger.LogDebug(ex, "Close handshake failed: ConnectionId={ConnectionId}", ConnectionId); } } // ── Ping/Pong Heartbeat ──────────────────────────────────────────────────── /// /// Sends periodic ping frames to detect stale connections. /// RFC 6455: the remote end must respond with a pong frame within a reasonable time. /// ASP.NET Core's WebSocket implementation handles pong responses automatically. /// If the connection drops between pings, the next send or receive will throw. /// private async Task RunPingLoopAsync(CancellationToken ct) { try { while (!ct.IsCancellationRequested) { await Task.Delay(_options.PingIntervalMs, ct); if (_socket.State != WebSocketState.Open) return; await _sendLock.WaitAsync(ct); try { // An empty binary frame acts as a ping in our protocol. // For full RFC 6455 ping/pong, WebSocketMessageType.Close is not applicable; // ASP.NET Core handles pong automatically at the Kestrel level. await _socket.SendAsync( ReadOnlyMemory.Empty, WebSocketMessageType.Binary, endOfMessage: true, ct); } finally { _sendLock.Release(); } } } catch (OperationCanceledException) { // Normal exit on dispose or shutdown. } catch (Exception ex) { // Log ping failures but don't crash — the connection loop will detect // the disconnection on the next ReceiveAsync call. _logger.LogDebug(ex, "Ping loop error: ConnectionId={ConnectionId}", ConnectionId); } } // ── IAsyncDisposable ────────────────────────────────────────────────────── public async ValueTask DisposeAsync() { if (_disposed) return; _disposed = true; // Stop the ping loop. await _pingSts.CancelAsync(); _pingSts.Dispose(); // Dispose the send lock. _sendLock.Dispose(); // Dispose the underlying WebSocket. _socket.Dispose(); // Signal the middleware that this connection's work is complete. // TrySetResult is used (not SetResult) because RequestAborted may have // already set it if the server is shutting down. _connectionDone.TrySetResult(); } // ── Inner type: minimal IClientMessage for raw received bytes ───────────── /// /// Lightweight IClientMessage carrying raw wire bytes. /// Type and Seq are populated after IMessageSerializer.Deserialize() is called. /// This inner class is private to SOR.Networking.WebSocket — external code /// only sees the IClientMessage interface. /// private sealed class ReceivedMessage : IClientMessage { // Before deserialization, Type and Seq are unknown. // They will be set by the serializer layer before dispatch. // We use a mutable design here because the serializer returns a new // RawClientMessage (from SOR.Shared) — this type is only an interim carrier // from ReceiveAsync up to the serializer call in ConnectionLoop. public string Type { get; init; } = string.Empty; public int Seq { get; init; } public ReadOnlyMemory Payload { get; } public ReceivedMessage(byte[] rawBytes) { // The full wire bytes (envelope + payload) are stored as Payload. // The serializer will parse the envelope out of these bytes. Payload = rawBytes; } } }