Skip to content

Nalix.Network

Nalix.Network is the runtime package for listeners, connections, protocol flow, packet dispatch, middleware, and network-facing safeguards.

If you are building the server side of a Nalix-based system, this is usually the package you live in most.

What it gives you

Listener runtime

Core entry points:

  • TcpListenerBase
  • UdpListenerBase
  • Protocol

These types let you:

  • accept TCP or UDP traffic
  • keep connection/session state
  • bridge traffic into dispatch

Dispatch and handlers

Core entry points:

  • PacketDispatchChannel
  • PacketContext<TPacket>
  • packet attributes
  • handler controllers with [PacketController] and [PacketOpcode]

This is the part most application logic plugs into.

Connection management

Core entry points:

  • Connection
  • ConnectionHub
  • ConnectionHubOptions
  • ConnectionLimiter

Use these when you need:

  • live connection tracking
  • user/session lookup
  • forced disconnects
  • per-endpoint admission control

Middleware and safeguards

Core entry points:

  • packet middleware
  • buffer middleware
  • ConcurrencyGate
  • TokenBucketLimiter
  • PolicyRateLimiter

Use these to keep the server stable under real traffic.

Runtime tuning

Core option types:

  • NetworkSocketOptions
  • DispatchOptions
  • ConnectionLimitOptions
  • ConnectionHubOptions
  • TimingWheelOptions
  • PoolingOptions
  • NetworkCallbackOptions

Suggested reading order for clients

If you are new to the package, read in this order:

  1. TCP Listener
  2. Protocol
  3. Packet Dispatch
  4. Packet Context
  5. Connection
  6. Connection Hub
  7. Network Options

Then continue with the guides:

Minimal server shape

Quick example

PacketDispatchChannel dispatch = new(options =>
{
    options.WithLogging(logger)
           .WithHandler(() => new SamplePingHandlers());
});

[PacketController("SamplePingHandlers")]
public sealed class SamplePingHandlers
{
    [PacketOpcode(0x1001)]
    public ValueTask<PingResponse> Handle(PingRequest request, IConnection connection)
        => ValueTask.FromResult(new PingResponse { Message = $"pong:{request.Message}" });
}

public sealed class SampleProtocol : Protocol
{
    private readonly PacketDispatchChannel _dispatch;

    public SampleProtocol(PacketDispatchChannel dispatch) => _dispatch = dispatch;

    public override void ProcessMessage(object sender, IConnectEventArgs args)
        => _dispatch.HandlePacket(args.Lease, args.Connection);
}

public sealed class SampleTcpListener : TcpListenerBase
{
    public SampleTcpListener(ushort port, IProtocol protocol) : base(port, protocol) { }
}

Where metadata fits

Packet metadata is a real part of the package design, not just decoration.

It drives:

  • permissions
  • timeout behavior
  • rate limiting
  • concurrency limits
  • custom conventions through metadata providers