Nalix.Runtime¶

Nalix.Runtime is the high-performance orchestration layer of the Nalix framework, specifically designed to power Server-Side packet processing. It provides the multi-threaded dispatch pipeline, middleware execution engine, handler compilation, and session state infrastructure.

Source Mapping¶

• src/Nalix.Runtime/Dispatching/PacketDispatchChannel.cs
• src/Nalix.Runtime/Internal/Routing/DispatchChannel.cs
• src/Nalix.Runtime/Dispatching/PacketDispatcherBase.cs
• src/Nalix.Runtime/Handlers/SessionHandlers.cs
• src/Nalix.Runtime/Handlers/HandshakeHandlers.cs

Where It Fits¶

flowchart LR
    A["Nalix.Network (Transport)"] --> B["Nalix.Runtime (Dispatch)"]
    B --> C["Nalix.Codec (Serialization)"]
    B --> D["Nalix.Framework (Registry)"]
    B --> E["Nalix.Abstractions (Contracts)"]
    B --> F["Handler Logic"]

Core Components¶

Packet Dispatch¶

PacketDispatchChannel is the engine that processes all incoming network traffic. It manages:

• Shard-aware worker loops — Multiple workers (scaled to CPU core count) pull from the dispatch queue in parallel, preventing head-of-line blocking.
• Priority queueing — Packets are prioritized by PacketPriority (URGENT, HIGH, MEDIUM, LOW, NONE).
• Deserialization — Uses the PacketRegistry to convert raw bytes into typed packet instances.
• Packet middleware execution — Runs the configured middleware chain before handler invocation.
• Handler invocation — Calls the matched handler method with the appropriate context.
• Return handling — Translates handler return values into outbound network responses.

PacketDispatchChannel dispatch = new(options =>
{
    options.WithLogging(logger)
           .WithErrorHandling((ex, opcode) =>
           {
               logger.LogError(ex, "dispatch-error opcode=0x{Opcode:X4}", opcode);
           })
           .WithMiddleware(new MyAuditMiddleware<IPacket>())
           .WithHandler(() => new AccountHandlers())
           .WithHandler(() => new MatchHandlers());
});

dispatch.Activate();

Middleware Pipeline¶

The runtime supports specialized middleware that executes before high-level handler invocation. Nalix.Runtime includes several built-in protection and utility middleware:

Protection Primitives¶

The runtime includes advanced throttling and protection primitives used by the middleware:

• TokenBucketLimiter: Tracks per-endpoint token state for traffic shaping.
• PolicyRateLimiter: Evaluates handler-specific policy from [PacketRateLimit] metadata.
• ConcurrencyGate: Manages per-opcode execution slots and circuit breaking.
• DirectiveGuard: Protects against response directive spamming for failed requests.

Handler Compilation¶

Handler methods are discovered and compiled during Build():

• Methods annotated with [PacketOpcode] are matched to packet types
• Handler delegates are pre-compiled using expression trees or IL emit to avoid reflection during the hot path
• Handler metadata (permissions, timeouts, rate limits) is resolved once and cached in PacketMetadata

Session Resume¶

The built-in session resume flow is handled by SessionHandlers and backed by ISessionStore. It uses the unified SessionResume packet with SessionResumeStage to manage request/response stages:

1. Client sends a SessionResume with Stage = REQUEST and a session token
2. Server validates the token against ISessionStore
3. Server restores connection state and sends SessionResume with Stage = RESPONSE

In the current source, src/Nalix.Runtime/Handlers/SessionHandlers.cs validates proof-of-possession with HmacKeccak256, restores the snapshot onto the live connection, stores the connection back into the session store, and returns a fresh session token for the next reconnect.

Routing¶

Attribute-based routing maps opcodes to handler methods:

[PacketController("AccountHandlers")]
public sealed class AccountHandlers
{
    [PacketOpcode(0x2001)]
    [PacketPermission(PermissionLevel.USER)]
    [PacketTimeout(5000)]
    public async ValueTask<AccountResponse> Login(
        IPacketContext<LoginRequest> context)
    {
        // Handler logic
    }
}

Time Synchronization¶

TimeSynchronizer is an optional service that emits TimeSynchronized events at a default period of 16 ms (~60 Hz), designed for clock synchronization and periodic tick consumers.

Handler Return Types¶

The dispatch pipeline supports multiple return shapes. The internal return handler converts each into the appropriate outbound behavior:

Diagnostics¶

Call dispatch.GenerateReport() to inspect runtime state:

• Number of active workers
• Queue depth and ready-connection state
• Wake-signal counters
• Top pending connections and per-priority readiness

Related Packages¶

• Nalix.Network — Transport and listeners
• Nalix.Hosting — Fluent bootstrap
• Nalix.Framework — Packet registry and serialization
• Nalix.Abstractions — Shared contracts and primitives

Key API Pages¶

• Packet Dispatch
• Packet Dispatch Options
• Middleware Pipeline
• Concurrency Gate
• Policy Rate Limiter
• Token Bucket Limiter
• Permission Middleware
• Timeout Middleware
• Packet Attributes
• Handler Return Types
• Dispatch Options
• Session Resume