Documentation

Connection Contracts

Read time 5 minutes Package: Nalix.Abstractions
On this page

Namespace: Nalix.Abstractions.Networking (and Nalix.Abstractions.Networking.Protocols)
Assembly: Nalix.Abstractions

Nalix.Abstractions.Networking defines the transport-agnostic connection, hub, listener, and protocol contracts implemented by Nalix.Network and consumed by Nalix.Runtime and Nalix.Hosting.

Source Mapping

  • src/Nalix.Abstractions/Networking/IConnection.cs
  • src/Nalix.Abstractions/Networking/IConnection.ErrorTracked.cs
  • src/Nalix.Abstractions/Networking/IConnection.Hub.cs
  • src/Nalix.Abstractions/Networking/IConnection.Transmission.cs
  • src/Nalix.Abstractions/Networking/IConnection.TrafficMetrics.cs
  • src/Nalix.Abstractions/Networking/IConnectionEventArgs.cs
  • src/Nalix.Abstractions/Networking/INetworkEndpoint.cs
  • src/Nalix.Abstractions/Networking/IListener.cs
  • src/Nalix.Abstractions/Networking/IFrameProcessor.cs
  • src/Nalix.Abstractions/Networking/ITransportSequencer.cs
  • src/Nalix.Abstractions/Networking/TransportFraming.cs
  • src/Nalix.Abstractions/Networking/IProtocol.cs
  • src/Nalix.Abstractions/Networking/Protocols/IOpCodeExtractor.cs

IConnection

public interface IConnection : IConnectionErrorTracked, IDisposable represents an active client connection (TCP, UDP, or WebSocket).

MemberTypeDescription
ConnectionIdulongUnique 64-bit Snowflake identifier assigned to the connection.
UserIdstring?Optional application-assigned authenticated user identifier.
NetworkEndpointINetworkEndpointRemote client endpoint (string Address { get; }).
IsDisposedbooltrue once the connection has been closed and disposed.
UpTimelongElapsed connection uptime in milliseconds.
LastPingTimelongMost recent round-trip ping latency in milliseconds.
ExcludeFromIdleTimeoutboolWhen true, exempts the connection from TimingWheel idle timeout sweeps.
AttributesIObjectMap<AttributeKey, object>Thread-safe per-connection key-value metadata store.
LevelPermissionLevelCurrent authorization level (NONE, POW_VERIFIED, ESTABLISHED, USER, etc.).
AlgorithmCipherSuiteTypeNegotiated symmetric/AEAD cipher suite (Chacha20Poly1305, Salsa20Poly1305, etc.).
SecretBytes32Negotiated 32-byte session secret key (Bytes32, wiped on close).
IsUdpCreatedbooltrue once the connection has an active UDP transport binding.
PacketClassifierIOpCodeExtractorClassifier used to extract 16-bit opcodes from raw inbound frames.
TCPIConnection.ITransportStream/TCP (or WebSocket) transport interface.
UDPIConnection.ITransport?Datagram/UDP transport interface (null until UDP is bound).
ErrorCountintInherited from IConnectionErrorTracked — total protocol/framing errors recorded on this connection.
IncrementErrorCount()voidAtomically increments ErrorCount (checked by ConnectionGuard).
OnCloseEventevent EventHandler<IConnectionEventArgs>Fired when the connection closes.
OnProcessEventevent EventHandler<IConnectionEventArgs>Fired when a raw inbound frame is ready for IProtocol.ProcessMessage.
OnPostProcessEventevent EventHandler<IConnectionEventArgs>Fired after IProtocol.PostProcessMessage completes.
Disconnect(string? reason = null)voidImmediately closes and unregisters the connection.
UpdateIdleTimeout(int newTimeoutMs)voidDynamically updates the idle timeout budget for this connection in TimingWheel.

Nested Transport Contracts (IConnection.ITransport & IConnection.ISocketTransport)

  • IConnection.ITransport : ITransportSequencer:
    • TransportFraming Framing { get; } (None, UInt16LengthPrefixed, VarIntLengthPrefixed)
    • void UseFraming(TransportFraming newFraming)
    • void Send(ReadOnlySpan<byte> message)
    • ValueTask SendAsync(ReadOnlyMemory<byte> message, CancellationToken cancellationToken = default)
    • void BeginReceive(CancellationToken cancellationToken = default)
    • ValueTask<IAsyncDisposable> AcquireSendLockAsync(CancellationToken cancellationToken = default)
    • ValueTask SendAsyncCore(ReadOnlyMemory<byte> data, CancellationToken cancellationToken = default)
    • ValueTask SendAsyncCore(IBufferLease lease, CancellationToken cancellationToken = default)
  • IConnection.ISocketTransport : ITransport:
    • Socket Socket { get; }
    • Task? ReceiveLoopTask { get; }
    • byte[]? StolenData { get; }
    • Socket Unwrap()

IConnectionTrafficMetrics

Implemented by Connection, WebSocketConnection, and PassthroughConnection to expose atomic traffic counters:

MemberTypeDescription
BytesSentlongTotal wire bytes transmitted on this connection.
BytesReceivedlongTotal wire bytes received on this connection.
PacketsDroppedlongTotal packets dropped due to queue overflow or rate limiting.
IncrementBytesSent(int bytes)voidAtomically adds bytes to BytesSent.
IncrementBytesReceived(int bytes)voidAtomically adds bytes to BytesReceived.
IncrementPacketsDropped()voidAtomically increments PacketsDropped.

IConnectionHub

public interface IConnectionHub : IReportable, IDisposable is the sharded, thread-safe registry of all active server connections:

MemberSignatureDescription
Countint Count { get; }Total number of currently registered connections.
ConnectionUnregisteredevent Action<IConnection>?Raised when a connection is removed from the hub.
RegisterConnectionvoid RegisterConnection(IConnection connection)Registers a newly accepted connection.
UnregisterConnectionvoid UnregisterConnection(IConnection connection)Removes a connection from the hub.
GetConnection(ulong)IConnection? GetConnection(ulong id)Looks up an active connection by its 64-bit ConnectionId.
GetConnection(ReadOnlySpan<byte>)IConnection? GetConnection(ReadOnlySpan<byte> id)Looks up an active connection by its 8-byte little-endian Snowflake span.
ListConnections()IReadOnlyCollection<IConnection> ListConnections()Returns a snapshot of all active connections.
ListConnections(INetworkEndpoint)IReadOnlyCollection<IConnection> ListConnections(INetworkEndpoint endPoint)Returns all active connections matching endPoint.

IProtocol & Supporting Pipeline Contracts

  • IProtocol : IDisposable, IReportable (Nalix.Abstractions.Networking):
    • bool KeepConnectionOpen { get; }
    • IFrameProcessor FrameProcessor { get; }
    • IOpCodeExtractor OpCodeExtractor { get; }
    • void OnAccept(IConnection connection, CancellationToken cancellationToken = default)
    • void ProcessMessage(object? sender, IConnectionEventArgs args)
    • void PostProcessMessage(object? sender, IConnectionEventArgs args)
  • IListener : IActivatable, IReportable:
    • void Activate(CancellationToken cancellationToken = default) (inherited from IActivatable)
    • void Deactivate(CancellationToken cancellationToken = default) (inherited from IActivatable)
  • IFrameProcessor:
    • bool SupportsInlineProcessing => false
    • void ProcessFrame(object? sender, IConnectionEventArgs args)
  • IOpCodeExtractor:
    • ushort Extract(ReadOnlySpan<byte> payload)
  • ITransportSequencer:
    • ISequenceCounter SendSequence { get; }
    • ISequenceCounter ReceiveSequence { get; }
    • uint CurrentSendSequence { get; }
    • uint CurrentReceiveSequence { get; }
    • uint NextSendSequence()
    • uint NextReceiveSequence()