Documentation

Glossary

Read time 3 minutes
On this page

This page defines the core Nalix terms that appear across the documentation. Use it as a quick reference when API pages become implementation-heavy.

BufferLease

A pooled byte buffer rented from BufferPoolManager. Must be disposed after use to return the buffer to the pool. Used throughout the hot path to avoid byte[] allocation.

Connection

Connection is the runtime session object for one remote client. It holds:

  • Connection ID
  • Remote endpoint
  • TCP/UDP transport adapters
  • Permission level
  • Cipher and secret state
  • Runtime counters (bytes sent, uptime, ping time, error count)

ConnectionHub

ConnectionHub is the in-memory registry of active connections. Use it for:

  • Connection lookup by ID or username
  • Forced disconnects
  • Bulk broadcast
  • Connection-level reporting via GenerateReport()

Dispatch

In the docs, “dispatch” usually means PacketDispatchChannel and its associated options and runtime. This is the component that:

  • Queues incoming work across sharded workers
  • Deserializes packets via the packet registry
  • Runs middleware chains
  • Invokes handlers
  • Processes supported return types

InstanceManager

The runtime service registry used across the Nalix stack. A service-locator pattern optimized for allocation-free resolution. Not a traditional DI container — designed for performance on the networking hot path.

Metadata Provider

Handler metadata (PacketMetadata) is now resolved at compile time by the PacketHandlerGenerator source generator, which reads the attributes on handler methods. Custom attributes on handler methods are stored in PacketMetadata.CustomAttributes and can be read from middleware via context.Attributes.GetCustomAttribute<T>().

Middleware

Logic inserted before or around handler execution using the MiddlewarePipeline. It operates on IPacketContext<TPacket> after packet deserialization, with full access to the packet and handler metadata.

PacketBase<T>

The base class for all Nalix packets. Provides system header management (opcode, flags, priority, sequence id) and pooling support via ResetForPool(). PacketBase instances are recycled through the object pool to avoid per-packet allocations.

PacketContext

PacketContext<TPacket> is the pooled concrete per-request runtime object behind IPacketContext<TPacket>. It provides access to:

  • The deserialized packet
  • The current connection
  • Resolved packet metadata (attributes)
  • Cancellation token
  • A pooled sender for manual replies

Packet Registry

A process-wide catalog of packet deserializers. It is populated automatically by Source Generators and finalized via PacketRegistry.Build(). Provides O(1) lookup by OpCode using a direct-indexed table.

PacketBase.Create()

The static factory pattern used to rent a packet from the object pool. The returned instance is wrapped in a using block and automatically returns to the pool on dispose.

Protocol

Protocol is the bridge between a live connection and the dispatch pipeline. In practice it:

  • Accepts or rejects new connections via ValidateConnection()
  • Starts receive loops
  • Forwards incoming message frames into dispatch via ProcessMessage()
  • Controls whether connections stay open after processing

Return Handler

The source-generated invoker translates a handler’s return type into a send action. Supported return types include:

  • TPacket / Task<TPacket> / ValueTask<TPacket>
  • byte[] / Memory<byte> / ReadOnlyMemory<byte>
  • void / Task / ValueTask (no response)

Snowflake

A customized 64-bit distributed identifier used for internal task tracking and packet correlation. Uses 32-bit Unix seconds timestamp, 14-bit sequence (16,384 IDs per second per node), and 10-bit machine ID (1,024 nodes).

TCP vs UDP

TransportUse when
TCPReliable, ordered request/response. The default and recommended starting point.
UDPLow-latency datagrams where packet loss is acceptable. Requires pre-established session identity and authentication.

TimingWheel

The idle-timeout scheduler used by the network layer. Manages connection timeouts with O(1) scheduling complexity. Detects and closes dead or inactive connections efficiently.