Skip to content

Connection

Connection is the default IConnection implementation used by Nalix.Network after a socket is accepted. It wraps the framed socket transport, owns connection identity and endpoint information, exposes TCP/UDP adapters, and bridges low-level transport callbacks into the higher-level events consumed by listeners, protocols, and dispatch code.

Source mapping

  • src/Nalix.Network/Connections/Connection.cs
  • src/Nalix.Network/Connections/Connection.Extensions.cs
  • src/Nalix.Network/Connections/Connection.Transmission.cs
  • src/Nalix.Network/Connections/Connection.EventArgs.cs
  • src/Nalix.Network/Connections/Connection.Endpoint.cs

Core state

Member Meaning
ID Snowflake session ID created at construction time.
NetworkEndpoint Remote endpoint resolved from the accepted socket.
TCP Always-present TCP transport facade backed by FramedSocketConnection.
UDP UDP transport facade when provisioned by the connection.
Secret Session secret / keying material.
Algorithm Current cipher suite, defaulting to CHACHA20_POLY1305.
Level Permission level for authorization-sensitive handlers.
BytesSent Total transmitted bytes, read atomically.
ErrorCount Number of transport / dispatch errors recorded for this connection.
UpTime, LastPingTime Metrics exposed through the framed socket cache.

Event bridges

The connection exposes three events:

  • OnCloseEvent
  • OnProcessEvent
  • OnPostProcessEvent

These are bridged from FramedSocketConnection.SetCallback(...):

  • close callbacks use AsyncCallback.InvokeHighPriority(...)
  • process and post-process callbacks use AsyncCallback.Invoke(...)

_closeSignaled ensures the close event is emitted only once.

Lifecycle

  • Construction creates the session ID, resolves the remote endpoint, creates ConnectionEventArgs, and initializes FramedSocketConnection.
  • Close(force = false) forwards to the close bridge.
  • Disconnect(reason) currently aliases Close(force: true).
  • Dispose() marks the instance disposed, disconnects, disposes the framed socket, and returns any pooled UDP transport to ObjectPoolManager.

Directive sending helper

ConnectionExtensions.SendAsync(...) sends a protocol Directive over TCP.

Current behavior:

  • rents a pooled Directive
  • serializes using either a small path or a rented BufferLease
  • sends through connection.TCP.SendAsync(...)
  • logs failures and returns the directive to the pool

Use this helper for throttle, fail, timeout, or other control replies.

Integration

  • TcpListenerBase subscribes protocol and limiter handlers to the connection events.
  • Protocol.ProcessMessage and Protocol.PostProcessMessage usually attach to the process events.
  • ConnectionLimiter.OnConnectionClosed should be attached to OnCloseEvent so per-endpoint counters stay accurate.

Basic usage

connection.OnProcessEvent += protocol.ProcessMessage;
connection.OnPostProcessEvent += protocol.PostProcessMessage;

await connection.TCP.SendAsync(new PingResponse(), ct);
connection.Close();