SDK Overview¶

Nalix.SDK is the client transport package for Nalix. It provides session lifecycle APIs (TransportSession, TcpSession, UdpSession), request/response helpers, handshake and resume extensions, and subscription helpers.

Client-side package

Nalix.SDK is for client applications only. Server projects should not create TcpSession, UdpSession, or SDK extension helpers. Server-side code should use Nalix.Network, Nalix.Hosting, and Nalix.Runtime listener/runtime APIs instead.

Source Mapping¶

src/Nalix.SDK/Transport
src/Nalix.SDK/Transport/Extensions
src/Nalix.SDK/Extensions
src/Nalix.SDK/Options
src/Nalix.SDK/InlineDispatcher.cs
src/Nalix.SDK/IThreadDispatcher.cs
src/Nalix.SDK/Bootstrap.cs
src/Nalix.SDK/TimeSyncCalculator.cs

Why This Package Exists¶

Client concerns differ from server runtime concerns. Nalix.SDK gives applications a stable client-facing API while keeping server execution details in Nalix.Runtime and Nalix.Network.

Core API Areas¶

High-level APIs¶

Use these pages when writing application/client code:

TcpSession: stream transport over TCP.
UdpSession: datagram transport over UDP.
Handshake Extensions: HandshakeAsync for secure session setup.
Resume Extensions: session resume flow.
Session Extensions: aggregate entry point for request, control, cipher, and subscription helpers.
Cipher Extensions: live cipher update helpers.
Control Utilities: PingAsync, DisconnectGracefullyAsync, and SyncTimeAsync convenience helpers.
Session Diagnostics: session diagnostics and observable runtime state.
Subscriptions: typed packet subscription APIs.

Low-level primitives¶

Use these pages when working on SDK internals, custom transports, or protocol tooling:

Thread Dispatching: IThreadDispatcher and InlineDispatcher.
Frame Reader and Sender: TCP frame parsing, send serialization, and fragmentation internals.
TransportSession: abstract base contract behind concrete sessions.
Protocol String Extensions: protocol-to-string helpers from src/Nalix.SDK/Extensions.

Options¶

Mental Model¶

Configure transport with TransportOptions and packet registry.
Connect with TcpSession or UdpSession.
Optionally perform HandshakeAsync or use ConnectWithResumeAsync on TcpSession.
Send packets directly or use RequestAsync<TResponse>.
Receive via event/subscription APIs.

Practical Example (From Current API)¶

TransportOptions options = new();
IPacketRegistry catalog = /* resolve registry */;

using TcpSession session = new(options, catalog);
await session.ConnectAsync();

await session.HandshakeAsync();

MyResponse response = await session.RequestAsync<MyResponse>(
    new MyRequest(),
    RequestOptions.Default.WithTimeout(3_000).WithRetry(1));

Best Practices¶

Prefer RequestAsync<TResponse> over manual subscribe/send/wait to avoid response race windows.
Handle OnError and OnDisconnected for production resilience.
Keep packet registry consistent between client and server packet contracts.