Documentation

Transport Options

Read time 4 minutes Package: Nalix.SDK
On this page

Namespace: Nalix.SDK.Options
Assembly: Nalix.SDK

TransportOptions (public sealed partial class TransportOptions : ConfigurationLoader) configures client-side connectivity, socket buffers, AEAD cipher suite, LZ4 compression, Ed25519 server key pinning / Trust-On-First-Use (TOFU), 0-RTT session resumption, ReconnectSupervisor backoff, keepalive probing, and clock synchronization across TcpSession, UdpSession, and WebSocketSession.

Source Mapping

  • src/Nalix.SDK/Options/TransportOptions.cs
  • src/Nalix.SDK/Transport/TransportSession.cs
  • src/Nalix.SDK/Transport/Internal/ReconnectSupervisor.cs
  • src/Nalix.SDK/Transport/Extensions/HandshakeExtensions.cs
  • src/Nalix.SDK/Transport/Extensions/ResumeExtensions.cs

Complete Property Reference

Loaded from the [Transport] section of default.ini via ConfigurationManager.Instance.Get<TransportOptions>() or constructed directly with new TransportOptions():

1. Endpoint & Socket Tuning

PropertyTypeDefaultValidationDescription
Portushort57206[ValueRange(1, 65535)]Default server port used by ConnectAsync() when no port override is passed.
Addressstring"127.0.0.1"[Length(1)]Default server IP address or hostname used by ConnectAsync().
ConnectTimeoutMillisint30000 (30s)[ValueRange(0, int.MaxValue)]Timeout in milliseconds for socket/WebSocket connect attempts (0 = no timeout).
NoDelaybooltrue—Controls Socket.NoDelay (TCP_NODELAY) on TcpSession.
BufferSizeint65536 (64 KB)[ValueRange(2048, 1048576)]Socket send and receive buffer size in bytes (2 KB..1 MB).
MaxUdpDatagramSizeint1400[ValueRange(64, 65507)]Maximum allowed UDP datagram size in bytes (including the 8-byte SessionToken and 4-byte XxHash32 MAC trailer).
AsyncQueueCapacityint1024[ValueRange(1, 65536)][Reserved] Asynchronous message processing queue capacity (currently not consumed).

2. Encryption, Compression & Server Identity (TOFU / Pinning)

PropertyTypeDefaultValidationDescription
AlgorithmCipherSuiteTypeCipherSuiteType.Chacha20Poly1305—Symmetric cipher suite used when encrypting frames after HandshakeAsync.
CompressionEnabledbooltrue—Enables automatic LZ4 compression on outbound frames meeting CompressionThreshold.
CompressionThresholdint512—Minimum payload size in bytes before outbound LZ4 compression is applied.
ServerPublicKeystring?null—Hex-encoded 32-byte static X25519 server identity public key for MitM-proof authentication during HandshakeAsync.
AllowTofubooltrue—Allows Trust-On-First-Use (PUBLIC_KEY_REQUEST $\rightarrow$ SessionTofu) discovery when ServerPublicKey is null or empty.
PersistTofuKeyboolfalse—When true, persists a TOFU-fetched ServerPublicKey to configuration storage after a verified handshake.

3. 0-RTT Session Resumption & Auto-Reconnect (ReconnectSupervisor)

PropertyTypeDefaultValidationDescription
ResumeEnabledbooltrue—Attempts 0-RTT ResumeSessionAsync before falling back to a fresh handshake during ConnectWithResumeAsync / auto-reconnect.
ResumeTimeoutMillisint3000 (3s)[ValueRange(100, int.MaxValue)]Timeout in milliseconds for session resume requests.
ResumeFallbackToHandshakebooltrue—Automatically falls back to HandshakeAsync when ResumeSessionAsync returns a non-NONE ProtocolReason.
AutoReconnectEnabledboolfalse—Enables automatic background reconnection via ReconnectSupervisor when a connection drops unexpectedly.
ReconnectBaseDelayMillisint500[ValueRange(1, int.MaxValue)]Initial delay in milliseconds before the first reconnect attempt.
ReconnectMaxDelayMillisint30000 (30s)[ValueRange(1, int.MaxValue)]Maximum delay cap in milliseconds for exponential reconnect backoff.
ReconnectMaxAttemptsint0[ValueRange(0, int.MaxValue)]Maximum consecutive reconnect attempts before giving up (0 = unlimited).

4. Keepalive Probing & Clock Synchronization

PropertyTypeDefaultValidationDescription
KeepAliveIntervalMillisint0 (disabled)[ValueRange(0, int.MaxValue)]Periodic PingAsync interval in milliseconds (0 disables keepalive probing).
KeepAliveTimeoutMillisint5000 (5s)[ValueRange(100, int.MaxValue)]Timeout in milliseconds for each keepalive PONG reply.
KeepAliveMissThresholdint3[ValueRange(1, int.MaxValue)]Consecutive missed keepalive PONG responses before the socket is faulted and handed to ReconnectSupervisor.
TimeSyncEnabledbooltrue—Allows SyncTimeAsync to synchronize the client clock with server time.
TimeOffsetMsdouble0—Current time offset in milliseconds applied by clock synchronization.

Configuration Examples

Programmatic Configuration

using Nalix.Abstractions.Security;
using Nalix.SDK.Options;
using Nalix.SDK.Transport;

TransportOptions options = new()
{
    Address = "game.example.com",
    Port = 57206,
    ConnectTimeoutMillis = 10_000,
    Algorithm = CipherSuiteType.Chacha20Poly1305,
    AllowTofu = true,
    AutoReconnectEnabled = true,
    ReconnectBaseDelayMillis = 500,
    ReconnectMaxDelayMillis = 15_000,
    KeepAliveIntervalMillis = 15_000,
    KeepAliveTimeoutMillis = 5_000,
    KeepAliveMissThreshold = 3
};

using TcpSession session = new(options);

INI Configuration (default.ini)

[Transport]
Port = 57206
Address = 127.0.0.1
ConnectTimeoutMillis = 30000
NoDelay = true
BufferSize = 65536
Algorithm = Chacha20Poly1305
CompressionEnabled = true
CompressionThreshold = 512
MaxUdpDatagramSize = 1400
AllowTofu = true
PersistTofuKey = false
ResumeEnabled = true
ResumeTimeoutMillis = 3000
ResumeFallbackToHandshake = true
AutoReconnectEnabled = false
ReconnectBaseDelayMillis = 500
ReconnectMaxDelayMillis = 30000
ReconnectMaxAttempts = 0
KeepAliveIntervalMillis = 0
KeepAliveTimeoutMillis = 5000
KeepAliveMissThreshold = 3
TimeSyncEnabled = true