Add networking foundation — 9-project C# solution (compiles clean)

Implements the modular networking layer for SOR Server:
- SOR.Networking.Abstractions: pure interfaces (ITransport, IClientConnection,
  IMessageSerializer, IMessageDispatcher, IMessageHandler, IEventBus, IClientPush)
- SOR.Networking.WebSocket: ITransport + IClientConnection over System.Net.WebSockets
- SOR.Networking.Nats: IEventBus over NATS.Net (INatsConnection)
- SOR.Networking.Redis: IClientPush over Redis Pub/Sub
- SOR.Shared: ServiceResult<T>, RedisKeys, NatsSubjects, ServerMessage, JSON serializer
- SOR.Shared.Proto: auth.proto with gRPC AuthService contract
- SOR.Gateway: accept loop, auth handshake, dispatcher, Redis push subscriber
- SOR.Auth: stub gRPC handler (placeholder responses)
- SOR.Host: multi-service runner via ENABLED_SERVICES env var; wires all DI

All concrete implementations are wired exclusively in SOR.Host — every transport,
broker, and push implementation can be swapped by changing only Program.cs.

dotnet build SOR.slnx → 0 errors, 0 warnings

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
This commit is contained in:
dingo
2026-02-24 21:01:38 -05:00
co-authored by Claude Happy
parent 0f95a0721b
commit d21adbc8d0
52 changed files with 3522 additions and 0 deletions
@@ -0,0 +1,281 @@
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;
/// <summary>
/// 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.
/// </summary>
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);
}
/// <inheritdoc/>
/// <remarks>
/// 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.
/// </remarks>
public async Task<IClientMessage?> 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<byte>.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<byte>(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<byte>.Shared.Return(buffer);
}
}
/// <inheritdoc/>
public async ValueTask SendBytesAsync(ReadOnlyMemory<byte> 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();
}
}
/// <inheritdoc/>
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 ────────────────────────────────────────────────────
/// <summary>
/// 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.
/// </summary>
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<byte>.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 ─────────────
/// <summary>
/// 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.
/// </summary>
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<byte> 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;
}
}
}