583 lines
41 KiB
Markdown
583 lines
41 KiB
Markdown
# EonaCat.Connections
|
|
|
|
`EonaCat.Connections` is an asynchronous .NET library for building TCP and UDP clients and servers. It provides connection lifecycle management, message framing, optional encryption, events, heartbeat handling, diagnostics, and configurable server-side protections.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
dotnet add package EonaCat.Connections
|
|
```
|
|
|
|
Or use the NuGet Package Manager:
|
|
|
|
```powershell
|
|
Install-Package EonaCat.Connections
|
|
```
|
|
|
|
The main types are in the `EonaCat.Connections` namespace. Configuration and protocol enums are in `EonaCat.Connections.Models`.
|
|
|
|
## Features
|
|
|
|
- TCP and UDP clients and servers.
|
|
- Async connect, send, disconnect, start, and stop APIs, with cancellation-token overloads for send operations.
|
|
- String (UTF-8) and binary payloads.
|
|
- Optional delimiter and length-prefixed message framing.
|
|
- Optional TLS and AES payload encryption.
|
|
- Client automatic reconnect, configurable SSL retries, TCP keep-alive, and optional ping/pong heartbeat.
|
|
- Events for connection lifecycle, data, errors, client nicknames, and heartbeat responses.
|
|
- Server unicast, broadcast, client-to-client forwarding, and request/response helpers.
|
|
- Server connection limits, statistics, security metrics, health/status reporting, and optional HTML reports.
|
|
- Configurable server-side rate limiting, payload validation, IP filtering, DDoS and Slowloris detection.
|
|
- TCP/UDP protocol implementations plus a low-level named protocol factory for custom transport code.
|
|
|
|
## Quick Start
|
|
|
|
The following examples use TCP, UTF-8 messages, and no transport encryption. Start the server before connecting the client.
|
|
|
|
### Server
|
|
|
|
```csharp
|
|
using EonaCat.Connections;
|
|
using EonaCat.Connections.Models;
|
|
|
|
var configuration = new Configuration
|
|
{
|
|
Protocol = ProtocolType.TCP,
|
|
Host = "127.0.0.1",
|
|
Port = 5050
|
|
};
|
|
|
|
using var server = new NetworkServer(configuration);
|
|
|
|
server.OnConnected += (_, connection) =>
|
|
Console.WriteLine($"Connected: {connection.ClientId} from {connection.RemoteEndPoint}");
|
|
|
|
server.OnDataReceived += async (_, message) =>
|
|
{
|
|
Console.WriteLine($"Received from {message.ClientId}: {message.StringData}");
|
|
await server.SendToClientAsync(message.ClientId, $"Echo: {message.StringData}");
|
|
};
|
|
|
|
server.OnDisconnected += (_, connection) =>
|
|
Console.WriteLine($"Disconnected: {connection.ClientId} ({connection.Reason})");
|
|
|
|
await server.StartAsync();
|
|
Console.WriteLine("Listening. Press Ctrl+C to stop.");
|
|
|
|
using var stop = new CancellationTokenSource();
|
|
Console.CancelKeyPress += (_, eventArgs) =>
|
|
{
|
|
eventArgs.Cancel = true;
|
|
stop.Cancel();
|
|
};
|
|
|
|
try
|
|
{
|
|
await Task.Delay(Timeout.Infinite, stop.Token);
|
|
}
|
|
catch (OperationCanceledException)
|
|
{
|
|
// Ctrl+C requested shutdown.
|
|
}
|
|
finally
|
|
{
|
|
await server.StopAsync();
|
|
}
|
|
```
|
|
|
|
`StartAsync()` starts the listener and returns; it does not block until the server stops. Use `StopAsync()` for an awaited shutdown.
|
|
|
|
### Client
|
|
|
|
```csharp
|
|
using EonaCat.Connections;
|
|
using EonaCat.Connections.Models;
|
|
|
|
var configuration = new Configuration
|
|
{
|
|
Protocol = ProtocolType.TCP,
|
|
Host = "127.0.0.1",
|
|
Port = 5050,
|
|
EnableAutoReconnect = true
|
|
};
|
|
|
|
using var client = new NetworkClient(configuration);
|
|
|
|
client.OnConnected += (_, connection) =>
|
|
Console.WriteLine($"Connected to {connection.RemoteEndPoint}");
|
|
|
|
client.OnDataReceived += (_, message) =>
|
|
Console.WriteLine($"Server replied: {message.StringData}");
|
|
|
|
client.OnDisconnected += (_, connection) =>
|
|
Console.WriteLine($"Disconnected: {connection.Reason}");
|
|
|
|
if (await client.ConnectAsync())
|
|
{
|
|
await client.SendAsync("Hello from the client");
|
|
}
|
|
|
|
await client.DisconnectAsync();
|
|
```
|
|
|
|
`ConnectAsync()` returns whether the connection succeeded. `WaitForConnectedAsync(timeout, cancellationToken)` can be used to await the next successful connection event. Dispose clients when finished.
|
|
|
|
## Sending and Receiving
|
|
|
|
### Text and binary data
|
|
|
|
String overloads encode and decode UTF-8. Use byte-array overloads for binary protocols or when the application owns serialization:
|
|
|
|
```csharp
|
|
byte[] payload = [0x01, 0x02, 0x03];
|
|
await client.SendAsync(payload, cancellationToken);
|
|
|
|
await server.SendToClientAsync(clientId, payload, cancellationToken);
|
|
await server.BroadcastAsync("Service maintenance in five minutes");
|
|
```
|
|
|
|
`DataReceivedEventArgs` provides `Data` (raw bytes), `StringData` (UTF-8 text), `IsBinary`, `ClientId`, `Nickname`, `RemoteEndPoint`, and `Timestamp`.
|
|
|
|
### Request and response
|
|
|
|
The convenience methods send data and wait for the next matching received message. The default timeout is 30 seconds; pass a timeout and cancellation token to override it.
|
|
|
|
```csharp
|
|
var response = await client.SendAndWaitForResponseAsync(
|
|
"status",
|
|
timeout: TimeSpan.FromSeconds(5),
|
|
cancellationToken);
|
|
|
|
if (response is not null)
|
|
{
|
|
Console.WriteLine(response.StringData);
|
|
}
|
|
```
|
|
|
|
On the server, use `SendToClientAndWaitForResponseAsync`, `SendFromClientToClientAndWaitForResponseAsync`, or `BroadcastAndWaitForResponsesAsync`. These helpers do not define application-level request IDs. If concurrent requests can overlap, include a correlation ID in your protocol and match responses in your application.
|
|
|
|
### Nicknames and client addressing
|
|
|
|
Clients can send or update a nickname with `SendNicknameAsync("worker-1")`. The server raises `OnConnectedWithNickname` when it receives a nickname. Server send methods can address a client by its client ID, endpoint, or nickname. `GetClient(clientId)` returns the connected client matches; `GetClients()` returns the client registry.
|
|
|
|
```csharp
|
|
await client.SendNicknameAsync("worker-1");
|
|
await server.SendToClientAsync("worker-1", "You are registered");
|
|
```
|
|
|
|
The server can also forward data to another client with `SendFromClientToClientAsync(fromClientId, toClientId, data)`. The server sends to the destination; the `fromClientId` identifies the source for missing-client diagnostics.
|
|
|
|
### Connection management
|
|
|
|
`ConnectAsync()` returns `true` when the initial connection succeeds. `WaitForConnectedAsync(timeout, cancellationToken)` waits for a successful client connection event and returns `false` if the wait ends without a connection. `IsConnected`, `ConnectionTime`, `Uptime`, `LastActive`, `LastDataSent`, `LastDataReceived`, `BytesSent`, `BytesReceived`, `MessagesSent`, and `MessagesReceived` expose client state and counters. Idle and connected durations are also available as `TimeSpan`, integer units, or formatted strings.
|
|
|
|
When enabled, client auto-reconnect starts after a client has connected once and a later connection is lost. A client-requested disconnect stops reconnecting. `MaxReconnectAttempts = 0` removes the configured attempt limit for a reconnect sequence; repeated sequences are still bounded by the client's consecutive-failure protection. SSL/TLS connection retries are controlled separately by `SSLMaxRetries`, `SSLRetryDelayInSeconds`, and the retry-delay settings. A zero SSL retry count means the retry loop has no configured maximum, so use cancellation or a finite limit when indefinite retries are not appropriate.
|
|
|
|
On the server, `WaitForClientAsync(clientId, timeout, cancellationToken)` waits for a client with that exact ID. `DisconnectClientAsync` removes a client and records the supplied `DisconnectReason`. `GetClient(clientId)` can resolve a client ID, nickname, or remote endpoint; endpoint hostnames are resolved to addresses, and a nickname shared by multiple clients can return more than one result. `GetClients()` returns the registry. Send methods return `false` when there is no matching connected client or when no send succeeds; a missing target also raises `OnClientMissing`.
|
|
|
|
Server unicast, broadcast, and client-to-client forwarding have byte and UTF-8 string overloads. Send and response helpers accept timeouts and cancellation tokens. `BroadcastAndWaitForResponsesAsync` collects responses until the timeout or expected response count; these helpers do not correlate overlapping application requests, so include your own request ID when concurrent calls are possible. With UDP, a client registry entry is keyed by its endpoint and exists after the first datagram; UDP still does not provide a reliable session or delivery guarantee.
|
|
|
|
## Message Framing
|
|
|
|
TCP is a byte stream; a single send is not guaranteed to arrive as one receive operation. `MessageFraming.None` (the default) forwards received data without reconstructing application message boundaries. Choose framing when each received event must represent one complete message, and configure both ends consistently.
|
|
|
|
```csharp
|
|
var configuration = new Configuration
|
|
{
|
|
Protocol = ProtocolType.TCP,
|
|
Host = "127.0.0.1",
|
|
Port = 5050,
|
|
MessageFraming = FramingMode.LengthPrefixed,
|
|
LengthPrefixedLength = 4,
|
|
UseBigEndian = true,
|
|
MAX_MESSAGE_SIZE = 1024 * 1024
|
|
};
|
|
```
|
|
|
|
Available modes:
|
|
|
|
- `FramingMode.None`: no message-boundary reconstruction.
|
|
- `FramingMode.LengthPrefixed`: a length header followed by the payload. Prefix sizes from 1 to 8 bytes are supported. The default is 4 bytes; `UseBigEndian` controls byte order and defaults to `false` (little-endian).
|
|
- `FramingMode.Delimiter`: payloads end at a delimiter. The default delimiter is `%`. Servers also expose `SetSeparator(string)` and `SetSeparator(byte[])`; configure the same delimiter on both peers.
|
|
|
|
`MAX_MESSAGE_SIZE` limits message payload size. It is not a substitute for application-level validation.
|
|
|
|
## Protocols and Encryption
|
|
|
|
### TCP and UDP
|
|
|
|
Set `Configuration.Protocol` to `ProtocolType.TCP` or `ProtocolType.UDP`. TCP supports stream-oriented communication and the library's TLS option. UDP is datagram-oriented and does not provide TCP's delivery or ordering guarantees. For UDP broadcast, set `EnableBroadcast = true` where applicable.
|
|
|
|
### TLS
|
|
|
|
TLS is enabled by configuring an `X509Certificate2` on `Configuration`; certificate validation and client-certificate behavior are controlled by the certificate and TLS settings. Configure valid certificates and trust on the communicating peers. Do not enable `IsSelfSignedEnabled` in production: it accepts certificates without normal certificate validation. `TrustedThumbprints`, `CheckCertificateRevocation`, `MutuallyAuthenticate`, `AdditionalCertificates`, and `AllowTlsRenegotiation` provide additional certificate and handshake controls.
|
|
|
|
### AES encryption
|
|
|
|
Set `UseAesEncryption = true` and provide an `AesPassword` on both peers to enable the library's AES key exchange and payload encryption. Keep the password secret and deliver it through a secure configuration mechanism; do not commit it to source control. TLS is generally preferable for protecting data in transit and authenticating the remote endpoint.
|
|
|
|
### Custom protocol abstractions
|
|
|
|
`NetworkClient` and `NetworkServer` currently select only `ProtocolType.TCP` or `ProtocolType.UDP`; they do not call `Configuration.GetProtocol()` or use `ProtocolFactory` to replace their transport. The protocol interface and registry are available for applications that create and manage protocol instances directly. `Configuration.GetProtocol()` creates an instance from `ProtocolFactory` or the built-in registry and applies the configured buffer, Nagle, reset, broadcast, keep-alive, and SSL options.
|
|
|
|
To register and create a protocol instance:
|
|
|
|
```csharp
|
|
using EonaCat.Connections.Models;
|
|
using EonaCat.Connections.Protocols;
|
|
|
|
ProtocolFactory.RegisterProtocol("CUSTOM", () => new MyNetworkProtocol());
|
|
|
|
var configuration = new Configuration
|
|
{
|
|
Host = "example.net",
|
|
Port = 7000,
|
|
ProtocolFactory = () => ProtocolFactory.CreateProtocol("CUSTOM")
|
|
};
|
|
|
|
using var protocol = configuration.GetProtocol();
|
|
byte[] payload = [0x01, 0x02, 0x03];
|
|
using var cancellation = new CancellationTokenSource();
|
|
var cancellationToken = cancellation.Token;
|
|
if (await protocol.ConnectAsync(configuration.Host, configuration.Port, cancellationToken))
|
|
{
|
|
await protocol.SendAsync(payload, cancellationToken);
|
|
}
|
|
```
|
|
|
|
`INetworkProtocol` defines connection, send/receive, cleanup, configuration, and endpoint/socket access members. `ProtocolFactory` can register, create, query, list, and unregister custom registrations; built-in TCP and UDP registrations cannot be removed. Return a fresh disposable instance for each independent connection. Implement the configuration hooks your protocol supports; `IBroadcastConfigurableProtocol` adds the optional broadcast hook. This low-level API does not automatically add core message framing, lifecycle events, client registry, reconnect, or server send helpers to the custom transport. See [Custom Crap/CUSTOMPROTOCOLS.md](Custom%20Crap/CUSTOMPROTOCOLS.md) for the interface implementation example.
|
|
|
|
## Server Protections
|
|
|
|
Server controls are configured through `Configuration.Security` (`SecurityOptions`). Implemented protections include:
|
|
|
|
- Global and per-connection message rate limits.
|
|
- Payload size, empty-message, null-byte, and suspicious-content checks.
|
|
- DDoS and Slowloris detection.
|
|
- IP allow/deny lists, temporary blocking, and automatic blocking after violations.
|
|
- Security logging and counters for enabled protections.
|
|
|
|
Example:
|
|
|
|
```csharp
|
|
var configuration = new Configuration
|
|
{
|
|
Host = "0.0.0.0",
|
|
Port = 5050,
|
|
Security = new SecurityOptions
|
|
{
|
|
EnableGlobalRateLimiting = true,
|
|
GlobalMessagesPerSecond = 20_000,
|
|
EnablePerConnectionRateLimiting = true,
|
|
ConnectionMessagesPerSecond = 2_000,
|
|
EnablePayloadValidation = true,
|
|
MaxPayloadSize = 1024 * 1024,
|
|
EnableIPFiltering = true,
|
|
WhitelistedIPs = new HashSet<string> { "127.0.0.1" }
|
|
}
|
|
};
|
|
```
|
|
|
|
`SecurityOptions` enables global and per-connection rate limiting, security logging, and null-byte blocking by default. Payload validation, suspicious-content detection, DDoS detection, Slowloris detection, and IP filtering default to disabled. The controls apply to server-side incoming connections and messages; they do not provide user authentication or authorization. Tune limits for the expected traffic and payload profile. These controls complement, but do not replace, operating-system firewalls, network-layer protections, or application authorization.
|
|
|
|
| Security setting | Default | Effect when implemented |
|
|
| --- | ---: | --- |
|
|
| `EnableGlobalRateLimiting`, `GlobalMessagesPerSecond` | `true`, `50000` | Caps the aggregate incoming message rate. |
|
|
| `EnablePerConnectionRateLimiting`, `ConnectionMessagesPerSecond` | `true`, `10000` | Caps messages per client connection. |
|
|
| `EnablePayloadValidation`, `MaxPayloadSize` | `false`, 50 MiB | Rejects payloads above this configured size when validation is enabled. The core `MAX_MESSAGE_SIZE` remains a separate limit. |
|
|
| `ValidateMessageNotEmpty` | `false` | Rejects empty payloads independently of the size-validation toggle. |
|
|
| `BlockNullBytePayloads` | `true` | Rejects payloads containing a zero byte. Disable it for binary protocols that legitimately use zero bytes. |
|
|
| `EnableSuspiciousContentDetection` | `false` | Checks valid UTF-8 text for SQL-like, script, and path-traversal patterns. Invalid UTF-8 binary payloads are not scanned. Pattern matching is heuristic, not application-level validation. |
|
|
| `EnableDDoSDetection`, `MaxConnectionsPerSecondPerIp`, `ConnectionSpamThreshold`, `SpamDetectionWindowSeconds` | `false`, `100`, `10`, `5` | Tracks connection attempts by IP and can reject traffic classified as suspicious. |
|
|
| `EnableSlowlorisDetection`, `SlowlorisMinBytesPerSecond`, `SlowlorisDetectionWindowSeconds` | `false`, `1024`, `30` | Detects clients whose received-byte rate falls below the configured threshold. |
|
|
| `EnableIPFiltering`, `WhitelistedIPs`, `BlacklistedIPs` | `false`, empty, empty | Enables IP allow/deny lists. Explicitly configure the lists before enabling filtering. |
|
|
| `AutoBlockIPAfterViolations`, `IPBlockDurationSeconds` | `0`, `300` | A positive violation threshold temporarily blocks an IP when IP filtering is enabled; zero disables automatic blocking. |
|
|
| `EnableSecurityLogging` | `true` | Emits logs when security checks reject or limit traffic. |
|
|
|
|
The following properties are present in `SecurityOptions` but are not currently enforced by the core network paths: `EnableHTTPAttackDetection`, `MaxHTTPHeaderSize`, `MaxHTTPHeaders`, `EnableSYNFloodDetection`, `MaxHalfOpenConnectionsPerIp`, `EnableRequestDeduplication`, `DeduplicationWindowSeconds`, `EnableSecurityMetrics`, and `MessageTimeoutSeconds`. Setting them does not activate the named behavior. `GetSecurityMetrics()` reports counters for implemented protections regardless of `EnableSecurityMetrics`.
|
|
|
|
The lower-level `RateLimiter`, `PerConnectionRateLimiter`, `DDoSDetector`, `SlowlorisDetector`, `IPBlocklist`, and `PayloadValidator` classes can also be used directly. `RequestDeduplicator` hashes payloads and tracks repeated hashes in a time window, but it is not currently connected to `NetworkServer` message processing.
|
|
|
|
## Configuration Reference
|
|
|
|
`Configuration` is shared by the client or server created from it. The defaults below are from the core package; separate transports use only the settings relevant to their transport.
|
|
|
|
| Setting | Purpose |
|
|
| --- | --- |
|
|
| `Protocol`, `Host`, `Port` | Select TCP/UDP and the endpoint. The default protocol is TCP; the default endpoint is `127.0.0.1:8080`. |
|
|
| `ProtocolFactory` | Optional custom `INetworkProtocol` factory used by `Configuration.GetProtocol()`. It does not replace the transports in `NetworkClient` or `NetworkServer`. |
|
|
| `MaxConnections` | Maximum server connection limit. |
|
|
| `BufferSize`, `MAX_MESSAGE_SIZE` | I/O buffer and maximum accepted message size. The defaults are `BufferSizeMaximum.Huge` and `MessageSizeMaximum.Default`. |
|
|
| `MessageFraming`, `Delimiter`, `LengthPrefixedLength`, `UseBigEndian` | TCP message framing and length-prefix format. `Delimiter` defaults to `%`; the default prefix length is 4 bytes and default byte order is little-endian. |
|
|
| `EnableAutoReconnect`, `MaxReconnectAttempts` | Client reconnect policy. Auto-reconnect defaults on; a maximum of zero means no configured per-sequence attempt limit. Repeated retry sequences stop after the internal consecutive-failure cutoff. |
|
|
| `ReconnectDelayInSeconds` | Public setting currently not read by the core reconnect loop; retries use its implemented backoff instead. |
|
|
| `SSLMaxRetries`, `SSLRetryDelayInSeconds`, `UseExponentialBackoffForSslRetries`, `SSLRetryDelayMaxSeconds` | Connect/TLS retry policy. Zero retry count means no configured maximum. The exponential delay helper is used by the server handshake path; the TCP client currently uses the fixed delay. |
|
|
| `SSLTimeoutInSeconds` | Public setting currently not read by the core connection paths. Use `ConnectionTimeout` and cancellation for actual connection timeout behavior. |
|
|
| `EnableKeepAlive`, `KeepAliveTimeSeconds`, `KeepAliveIntervalSeconds`, `KeepAliveRetryCount` | TCP keep-alive behavior. |
|
|
| `EnableHeartbeat`, `HeartbeatIntervalSeconds`, `DisconectOnMissedPong` | Application-level ping/pong heartbeat behavior. |
|
|
| `ConnectionTimeout`, `ReadTimeoutSeconds`, `WriteTimeoutSeconds` | Connection and I/O timeouts. |
|
|
| `Certificate`, `AdditionalCertificates`, `TrustedThumbprints`, `CheckCertificateRevocation`, `MutuallyAuthenticate`, `AllowTlsRenegotiation`, `IsSelfSignedEnabled` | TLS certificate and trust controls. `UseSsl` is derived from whether `Certificate` is set; `AdditionalCertificates` supplies chain certificates and `TrustedThumbprints` provides explicit thumbprint trust. Revocation checks and renegotiation are off by default. `MutuallyAuthenticate` enables client-certificate authentication. `IsSelfSignedEnabled` bypasses normal validation and is unsafe in production. |
|
|
| `UseAesEncryption`, `AesPassword` | Optional AES payload encryption. |
|
|
| `EnableNagle`, `EnableRST`, `EnableDualStack`, `EnableBroadcast` | `EnableNagle` controls TCP Nagle buffering; `EnableRST` configures reset-on-close; `EnableDualStack` enables IPv4/IPv6 server listeners where supported; `EnableBroadcast` enables UDP broadcast. All default to `false`. |
|
|
| `EnableConnectionDebugLogs`, `EnablePingPongLogs`, `EnableSslDiagnostics` | Diagnostic logging options. |
|
|
| `EnableHealthApi`, `HealthApiPort`, `HealthApiBindAddress` | Optional health/status listener. Port `0` asks the OS for an available port; the default bind address is loopback. |
|
|
| `EnableAutoHtmlReports`, `HtmlReportOutputDirectory`, `HtmlReportIntervalSeconds` | Periodic socket diagnostic HTML reports. |
|
|
| `EnableServerStatusPage`, `ServerStatusPageIntervalSeconds` | Periodic server status report. |
|
|
| `IsRunningInContainer`, `DisableInternalCertificateCheck()` | Runtime/container detection and an option to disable the library's built-in trusted-thumbprint check. This does not make an untrusted certificate safe to accept. |
|
|
|
|
Convenience methods `UseContainerDefaults()`, `UseHighScaleProduction()`, and `UseDistributedProduction()` adjust selected defaults. Review their values against your deployment rather than treating them as universal tuning profiles.
|
|
|
|
`UseContainerDefaults()` binds the primary endpoint and health listener to all interfaces. `UseHighScaleProduction()` raises the connection limit, disables verbose connection/ping logging, and adjusts TCP keep-alive intervals. `UseDistributedProduction()` changes the connection limit and socket options. These methods do not configure certificates, secrets, firewall rules, or application authorization.
|
|
|
|
## Events and Monitoring
|
|
|
|
### Client events
|
|
|
|
`NetworkClient` exposes `OnConnected`, `OnDisconnected`, `OnDataReceived`, `OnNicknameSend`, `OnSslError`, `OnEncryptionError`, `OnGeneralError`, `OnSocketError`, `OnPingResponse`, and `OnPongResponse`.
|
|
|
|
### Server events
|
|
|
|
`NetworkServer` exposes `OnConnected`, `OnConnectedWithNickname`, `OnDisconnected`, `OnDataReceived`, `OnClientMissing`, `OnSslError`, `OnEncryptionError`, `OnGeneralError`, `OnSocketError`, `OnClientPingResponse`, and `OnPongMissed`.
|
|
|
|
`OnConnected` and `OnDisconnected` report lifecycle changes; nickname events report a nickname being sent or registered; `OnDataReceived` reports each payload delivered by the configured framing mode. Errors are separated by TLS, AES, socket, and general failures. Server `OnClientMissing` reports failed addressing, and ping/pong events report heartbeat responses or missed responses. Event handlers should return quickly; queue longer work elsewhere so receive processing is not delayed.
|
|
|
|
Both types expose byte/message counters, connection state, and a `StatusPage` for socket diagnostics. The server additionally provides `ActiveConnections`, `TotalConnections`, `DroppedConnections`, `DroppedPackets`, `MessagesPerSecond`, `Uptime`, `GetStats()`, and `GetSecurityMetrics()`. `HealthApi` is available on both types; configure `EnableHealthApi` and its bind address to enable the optional API. Server status reporting is controlled by `EnableServerStatusPage`.
|
|
|
|
`Stats.MessagesPerSecond` is the cumulative number of received messages divided by uptime, not a short-window throughput gauge. `ConnectionEventArgs` carries client ID, nickname, endpoint, timestamp, disconnect reason, exception, initiator, reason details, and diagnostic context. `DataReceivedEventArgs` carries raw bytes and metadata; `StringData` decodes those bytes as UTF-8 even when `IsBinary` is true. `ErrorEventArgs` carries the exception and message. Ping event args identify the peer and response time.
|
|
|
|
Disconnect reasons distinguish local/remote closure, timeout, TLS or encryption failure, missed pong, protocol error, buffer overflow, common socket failures such as reset/refused/unreachable, and server shutdown. `ConnectionEventArgs.Determine` maps common socket and transport exceptions to a reason. Inspect `Exception` and diagnostic context as well as the enum when handling disconnects.
|
|
|
|
The static `NetworkClient.OnLog` and `NetworkServer.OnLog` events publish library log messages. `DEBUG_DATA_SEND` and `DEBUG_DATA_RECEIVED` enable payload-level debug output on instances; avoid verbose payload logging for sensitive data or high-volume production traffic.
|
|
|
|
### Health and diagnostic reports
|
|
|
|
When `EnableHealthApi` is enabled, the client or server starts a small HTTP listener. It accepts `GET` requests at `/health` and `/status` for JSON health/state, `/dashboard` for the built-in traffic dashboard, and `/` for the endpoint index. The default bind address is loopback; the listener does not provide authentication or HTTPS, so do not bind it to an untrusted network. When `HealthApiPort` is `0`, read the selected port from `HealthApi.Port` after startup.
|
|
|
|
`StatusPage` is a bounded in-memory history of socket, general, and TLS errors. It exposes recent/all errors and filters by time, source, socket code, socket exception, or TLS error; it can also generate a periodic HTML report. `ServerStatus` generates a separate HTML snapshot of server connection counts, traffic counters, connected clients, and recent TLS errors. Both reports write files to `HtmlReportOutputDirectory`; configure permissions and storage retention for the host.
|
|
|
|
## Utility Types
|
|
|
|
### JSON stream processing
|
|
|
|
`JsonDataProcessor<TData>` accepts arbitrary byte or string chunks and keeps an incremental JSON parser per client name. It emits `OnProcessMessage` for complete JSON values deserialized to `TData`, and `OnProcessTextMessage` for non-JSON text between JSON values. `OnError` reports invalid input or parse failures. `RemoveClient` discards one parser context; idle contexts are periodically removed unless `KeepIdleClients` is true. `MaxAllowedBufferSize` limits parser buffering and `IdleTimeout` controls cleanup. Dispose the processor to stop its cleanup timer and release parser state.
|
|
|
|
### Network monitoring
|
|
|
|
`NetworkMonitor` periodically pings a target host, stores a bounded history of samples, and raises sample, outage-detected, and outage-recovered events. `GetHealthReport()` summarizes reachability, uptime percentage, average/min/max latency, jitter, outage windows, and current system network-interface byte rates. Those byte-rate values describe active host interfaces, not traffic for a particular `NetworkClient`. `StartAutoHtmlReport()` periodically writes the health report as HTML. ICMP may be blocked or deprioritized even when the application's TCP/UDP endpoint is reachable.
|
|
|
|
### Load and stress testing
|
|
|
|
`LoadTester` repeatedly creates core `NetworkClient` instances up to a target connection count, sends a fixed test message at the configured rate, logs progress, and closes its clients when the duration ends. `RunAsync(duration, connectionRatePerSecond, messageRate)` runs the workload; `GetReport()` returns connection, send-volume, error, and throughput fields. Use it against an explicitly authorized test server; the configured connection and send rates can consume substantial local and remote resources.
|
|
|
|
`StressTest` creates a fixed number of clients, sends a configured number of messages per client, records replies and per-client errors, and exposes a `StressTestResult` with summary and CSV export. `StressTestRunner.RunQuickTestAsync` provides a smaller convenience run. These tools exercise the core `NetworkClient`; they are not protocol-independent load generators.
|
|
|
|
### Certificates and protocols
|
|
|
|
`CertificateHelper` loads certificates from supported files or the local certificate store and provides install/remove helpers. **Do not use `CertificateHelper.CheckCertificate` for trust validation:** its current callback accepts all server certificates. Use the normal `Configuration` certificate validation path and an explicit trust configuration instead.
|
|
|
|
`ProtocolFactory` can register named protocol factories, create by name or `ProtocolType`, query whether a name is registered, list registrations, and unregister custom registrations. The built-in TCP and UDP registrations cannot be removed. `INetworkProtocol` defines the transport lifecycle, send/receive, socket/stream access, and configuration hooks; custom implementations should return a fresh disposable instance and honor the hooks they support. `IBroadcastConfigurableProtocol` adds the optional UDP broadcast configuration hook.
|
|
|
|
`TcpSeparators` provides common delimiter byte sequences. `Connection` represents a server-side peer and exposes its ID, endpoint, nickname, times, byte counters, security flags, metadata dictionary, and connection state. `Stats` holds aggregate counts. `DisconnectionDiagnostics`, `ConnectionLogger`, and `ConnectionLogManager` provide disconnect-cause analysis and connection/error logging; `SslHandshakeDiagnostics` and `SslMetrics` expose TLS handshake stages and negotiated details.
|
|
|
|
`AesKeyExchange` contains the low-level AES key-exchange and payload encrypt/decrypt helpers used by the built-in encryption flow. `StringHelper.GetTextBetweenTags` extracts text between markers and `SanitizeUsername` normalizes a username. `ConnectionTimeFormatter` formats elapsed durations, while `HandlingHelpers` provides guarded event invocation, fire-and-forget task handling, and safe disposal helpers.
|
|
|
|
## Related Packages
|
|
|
|
`EonaCat.Connections` provides TCP and UDP. The transports and integrations below are separate NuGet packages with their own entry-point types; installing one does not replace `NetworkClient` or `NetworkServer` automatically.
|
|
|
|
| Package | Client and server types | Framework |
|
|
| --- | --- | --- |
|
|
| `EonaCat.Connections` | `NetworkClient`, `NetworkServer` (TCP/UDP) | .NET Framework 4.8.1 and .NET 8 |
|
|
| `EonaCat.Connections.gRPC` | `GrpcNetworkClient`, `GrpcNetworkServer` | .NET 8 |
|
|
| `EonaCat.Connections.Quic` | `QuicNetworkClient`, `QuicNetworkServer` | .NET 8; preview-feature opt-in |
|
|
| `EonaCat.Connections.REST` | `RestNetworkClient`, `RestNetworkServer` | .NET 8 |
|
|
| `EonaCat.Connections.OpcUa` | `OpcUaNetworkClient`, `OpcUaNetworkServer` | .NET 8 |
|
|
|
|
Install only the packages needed by the application:
|
|
|
|
```bash
|
|
dotnet add package EonaCat.Connections.gRPC
|
|
dotnet add package EonaCat.Connections.Quic
|
|
dotnet add package EonaCat.Connections.REST
|
|
dotnet add package EonaCat.Connections.OpcUa
|
|
```
|
|
|
|
### gRPC
|
|
|
|
The gRPC integration provides a bidirectional streaming RPC. It supports text and byte payloads, nicknames, client events, per-client sends, broadcasts, optional heartbeat, automatic reconnect, statistics, and the optional health API. The server exposes an HTTP/2 endpoint and enforces `MAX_MESSAGE_SIZE` for received and sent gRPC messages. TLS 1.2/1.3 is enabled when a certificate is configured on the shared `Configuration`.
|
|
|
|
The `ConnectorService.Connect` RPC reads and writes `ConnectorMessage` values. `DATA` carries the application bytes in `Data`; `NICKNAME` carries a nickname in `Text`; `PING` and `PONG` are heartbeat controls; and `DISCONNECT` closes the stream. Heartbeat controls are exchanged when `EnableHeartbeat` is enabled. Applications normally use `GrpcNetworkClient` and `GrpcNetworkServer` rather than constructing these protobuf messages directly.
|
|
|
|
```csharp
|
|
using EonaCat.Connections.Models;
|
|
using EonaCat.Connections.gRPC;
|
|
|
|
var serverConfig = new Configuration { Host = "0.0.0.0", Port = 5051 };
|
|
using var server = new GrpcNetworkServer(serverConfig);
|
|
server.OnDataReceived += async (_, message) =>
|
|
await server.SendToClientAsync(message.ClientId, message.Data);
|
|
await server.StartAsync();
|
|
|
|
var clientConfig = new Configuration { Host = "127.0.0.1", Port = 5051 };
|
|
using var client = new GrpcNetworkClient(clientConfig);
|
|
client.OnDataReceived += (_, message) => Console.WriteLine(message.StringData);
|
|
|
|
if (await client.ConnectAsync())
|
|
{
|
|
await client.SendAsync("Hello over gRPC");
|
|
}
|
|
```
|
|
|
|
Configure the same TLS certificate/trust expectations on both sides when securing the endpoint. As with the core client, configure certificate validation deliberately; `IsSelfSignedEnabled` disables normal certificate validation and is unsuitable for production.
|
|
|
|
### QUIC
|
|
|
|
QUIC uses a TLS-protected connection with a bidirectional stream. The client and server provide connect, send, disconnect, lifecycle/data/error events, connection limits on the server, counters, and server broadcasts. The server requires `Configuration.Certificate`; configure the client to trust that certificate. QUIC support depends on the operating system and runtime, and the implementation is annotated as using preview features. The current client expects `Configuration.Host` to be an IP address because it parses the value directly.
|
|
|
|
The QUIC stream is byte-oriented: a receive event reflects a stream read, not an application message boundary. Add application framing when the protocol needs discrete messages. Client and server must use the same `PROTOCOL_CONNECTION_NAME` for ALPN negotiation; inbound stream limits and default stream/connection close error codes are also configurable on the QUIC types.
|
|
|
|
```csharp
|
|
using EonaCat.Connections.Models;
|
|
using EonaCat.Connections.Quic;
|
|
|
|
var serverConfig = new Configuration
|
|
{
|
|
Host = "0.0.0.0",
|
|
Port = 5052,
|
|
Certificate = serverCertificate
|
|
};
|
|
using var server = new QuicNetworkServer(serverConfig);
|
|
server.OnDataReceived += async (_, message) =>
|
|
await server.SendToClientAsync(message.ClientId, message.Data);
|
|
await server.StartAsync();
|
|
|
|
var clientConfig = new Configuration { Host = "127.0.0.1", Port = 5052 };
|
|
await using var client = new QuicNetworkClient(clientConfig);
|
|
if (await client.ConnectAsync())
|
|
{
|
|
await client.SendAsync("Hello over QUIC");
|
|
}
|
|
```
|
|
|
|
QUIC is a separate API, not a `ProtocolType` option for `NetworkClient` or `NetworkServer`. Confirm `QuicConnection.IsSupported` on the deployment platform and enable preview features in applications that consume the package.
|
|
|
|
### REST and webhooks
|
|
|
|
The REST package hosts an HTTP API and represents each connected client with a generated client ID. `RestNetworkClient.ConnectAsync()` registers the client; it sends data using HTTP POST and receives queued server messages by polling. The server supports these routes:
|
|
|
|
| Method and route | Purpose |
|
|
| --- | --- |
|
|
| `POST /api/connect` | Creates a client record and returns its generated `clientId`; returns `429` when the connection limit is reached. |
|
|
| `POST /api/disconnect` | Disconnects the client named by `clientId`. |
|
|
| `POST /api/send` | Sends a client's payload to the server-side `OnDataReceived` event. Clients send payloads as Base64 in the `data` field. |
|
|
| `GET /api/poll/{clientId}` | Drains that client's pending server messages and returns them as Base64 strings in `messages`. |
|
|
| `POST /api/broadcast` | Broadcasts `data` to all clients except the optional sender `clientId`. |
|
|
| `POST /api/nickname` | Sets the supplied `nickname` on the identified client. |
|
|
| `GET /api/ping/{clientId}` | Updates activity/pong time and returns a pong response. |
|
|
| `POST /api/webhooks/register` | Sets the client's callback URL used for server-to-client message delivery. |
|
|
| `POST /api/webhooks/unregister` | Clears the client's callback URL so queued polling is used again. |
|
|
| `POST /api/aes/init/{clientId}` | Initializes a client's AES state from supplied salt/IV when AES is enabled on the server. |
|
|
|
|
REST client/server also expose lifecycle and data events, counters, connection limits, optional TLS, and optional AES payload encryption. The routes do not implement authentication or authorization; put the server behind an authenticated gateway or restrict network access before exposing it beyond a trusted network.
|
|
|
|
```csharp
|
|
using EonaCat.Connections.Models;
|
|
using EonaCat.Connections.REST;
|
|
|
|
var serverConfig = new Configuration { Host = "0.0.0.0", Port = 5053 };
|
|
using var server = new RestNetworkServer(serverConfig);
|
|
server.OnDataReceived += async (_, message) =>
|
|
await server.SendToClientAsync(message.ClientId, $"Echo: {message.StringData}");
|
|
await server.StartAsync();
|
|
|
|
var clientConfig = new Configuration { Host = "127.0.0.1", Port = 5053 };
|
|
using var client = new RestNetworkClient(clientConfig);
|
|
client.OnDataReceived += (_, message) => Console.WriteLine(message.StringData);
|
|
if (await client.ConnectAsync())
|
|
{
|
|
await client.SendAsync("Hello over REST");
|
|
}
|
|
```
|
|
|
|
For callback delivery, `RestNetworkServer.Webhooks` registers event names and destination URLs, for example `connected`, `data_received`, and `broadcast`. A REST client can also start a local webhook listener with `StartWebhookListenerAsync(port)` and register it with `RegisterWebhookAsync`; the built-in listener binds to loopback, so it is intended for local callback delivery unless the application provides another reachable endpoint. Webhook delivery is outbound HTTP POST, sequential, best-effort, and has no retry; outbound failures are swallowed. Protect and monitor the callback targets like any other outbound integration.
|
|
|
|
REST provides HTTP request/response semantics rather than TCP-style stream delivery: clients poll for messages when webhooks are not used, so account for polling latency and HTTP overhead when choosing it.
|
|
|
|
### OPC UA
|
|
|
|
The OPC UA package is a separate industrial interoperability API, not a byte-message transport. `OpcUaNetworkServer` publishes a configured address space under an `EonaCat` folder; register variables and callable methods before starting it. Variables have scalar data types, initial values, access levels, and optional descriptions. `TrySetValue` updates a registered variable and raises `ValueChanged`; client writes to a writable variable also raise that event. Methods declare typed input/output arguments and invoke the supplied handler when called.
|
|
|
|
`OpcUaNetworkClient` connects to an endpoint, browses hierarchical references from `ObjectsFolder`, reads and writes variable values, calls methods, and subscribes to monitored value changes. Subscriptions default to 1000 ms publishing/sampling intervals, queue up to 10 values per item, and discard the oldest queued value when full. The client can reconnect after a session keep-alive failure, and both client and server expose lifecycle/error events.
|
|
|
|
```csharp
|
|
using EonaCat.Connections.OpcUa.Configuration;
|
|
using EonaCat.Connections.OpcUa.Models;
|
|
using EonaCat.Connections.OpcUa.Server;
|
|
using Opc.Ua;
|
|
|
|
var server = new OpcUaNetworkServer(new OpcUaServerOptions
|
|
{
|
|
BaseAddress = "opc.tcp://localhost:4840/EonaCat/Connector",
|
|
NamespaceUri = "urn:example:machine"
|
|
});
|
|
server.AddVariable(new OpcUaNodeDefinition(
|
|
Identifier: "Temperature",
|
|
DisplayName: "Temperature",
|
|
DataType: DataTypeIds.Double,
|
|
InitialValue: 20.0));
|
|
server.AddMethod(new OpcUaMethodDefinition(
|
|
Identifier: "Add",
|
|
DisplayName: "Add",
|
|
InputArguments:
|
|
[
|
|
new OpcUaMethodArgument("left", DataTypeIds.Double),
|
|
new OpcUaMethodArgument("right", DataTypeIds.Double)
|
|
],
|
|
OutputArguments: [new OpcUaMethodArgument("sum", DataTypeIds.Double)],
|
|
Handler: arguments => new object?[] { (double)arguments[0]! + (double)arguments[1]! }));
|
|
await server.StartAsync();
|
|
|
|
// Update a published variable by its registered identifier.
|
|
server.TrySetValue("Temperature", 21.5);
|
|
```
|
|
|
|
```csharp
|
|
using EonaCat.Connections.OpcUa.Client;
|
|
using EonaCat.Connections.OpcUa.Configuration;
|
|
|
|
await using var client = new OpcUaNetworkClient(new OpcUaClientOptions
|
|
{
|
|
EndpointUrl = "opc.tcp://localhost:4840/EonaCat/Connector"
|
|
});
|
|
|
|
if (await client.ConnectAsync())
|
|
{
|
|
const string namespaceUri = "urn:example:machine";
|
|
var temperatureNode = client.GetNodeId(namespaceUri, "Temperature");
|
|
Console.WriteLine((await client.ReadAsync(temperatureNode)).Value);
|
|
await client.WriteAsync(temperatureNode, 22.0);
|
|
|
|
var sum = await client.CallAsync(
|
|
client.GetNodeId(namespaceUri, "EonaCat"),
|
|
client.GetNodeId(namespaceUri, "Add"),
|
|
new object?[] { 2.0, 3.0 });
|
|
Console.WriteLine(sum[0]);
|
|
|
|
await using var subscription = await client.SubscribeAsync(
|
|
new[] { temperatureNode },
|
|
(_, change) => Console.WriteLine($"Temperature: {change.Value}"));
|
|
}
|
|
```
|
|
|
|
The corresponding client uses `OpcUaClientOptions.EndpointUrl` and `ConnectAsync()`. Resolve a node using `GetNodeId(namespaceUri, identifier)` or browse from `ObjectsFolder`, then use `ReadAsync`, `WriteAsync`, `CallAsync`, or `SubscribeAsync`. `CallAsync` takes both the containing object node ID and method node ID plus ordered input values. Dispose the returned subscription when it is no longer needed. Server security defaults enable a secure endpoint and also allow an unsecured endpoint; client security defaults on, untrusted certificates are not automatically accepted, and revocation checking is on. Server options control endpoint/namespace, certificate policy, session count, and subscription count. Client options control endpoint security, optional username/password identity, certificate checks, operation/session timeouts, and reconnect behavior. Disable unsecured endpoints unless required and configure trust before exposing an OPC UA endpoint.
|
|
|
|
All transports and integrations should be stopped and disposed explicitly. For TCP, UDP, gRPC, and REST servers, `StartAsync()` starts listening and returns; await `StopAsync()` during graceful shutdown. QUIC and OPC UA have their own client/server lifecycle methods as described above.
|
|
|
|
## Resource Cleanup
|
|
|
|
Dispose clients and servers when finished. On servers, use `await StopAsync()` when shutdown should complete before the application exits; `Stop()` is a fire-and-forget convenience method. `Configuration` implements `IDisposable` and disposes its configured certificate, so avoid sharing a certificate-owning configuration across components with unrelated lifetimes.
|
|
|
|
## License
|
|
|
|
See the [LICENSE](LICENSE) file.
|