Documentation

Configuration System

Read time 3 minutes
On this page

This page explains how configuration becomes a running Nalix server. It covers the startup wiring sequence, option validation, service registration, and the relationship between configuration, dispatch, and transport.

Source Mapping

  • src/Nalix.Environment/Configuration/ConfigurationManager.cs
  • src/Nalix.Hosting/Bootstrap.cs
  • src/Nalix.Hosting/NetworkApplicationBuilder.cs

The Short Version

Nalix startup follows a strict deterministic sequence to ensure that shared infrastructure is ready before traffic starts.

Environment-Aware Bootstrapping

Nalix configuration is centered around ConfigurationManager and the active INI file under Directories.ConfigurationDirectory. The exact file path can be changed with SetConfigFilePath(...), and the current implementation constrains that path to the configuration directory.

Architecture Diagram
flowchart LR
    A["Configuration Files"] --> B["ConfigurationManager"]
    B --> C["Options Objects"]
    C --> D["Validation Gate"]
    D --> E["InstanceManager"]
    E --> F["Dispatch Channel"]
    F --> G["Protocol & Layer"]
    G --> H["Network Listeners"]

Configuration Pillars

ConfigurationManager

ConfigurationManager is the central entry point for configuration values and option binding. It handles loading from sources, binding to strongly-typed classes, and caching resolved instances.

Options Classes

Nalix uses focused, granular option types instead of a monolithic “Settings” object. This keeps runtime concerns (like timing wheels vs. socket limits) isolated.

OptionPurpose
NetworkSocketOptionsBuffer sizes, ports, and IP properties
DispatchOptionsPer-connection queue bounds, drop policy, and block timeout
ConnectionQuotaOptionsPer-IP concurrent connection and rate limits
ConnectionGuardOptionsGlobal connection ceiling, error thresholds, packet rate, and progressive bans
TimingWheelOptionsO(1) timeout scheduling for idle connections

Runtime Registry

InstanceManager (DI)

InstanceManager is the runtime registry for shared services. It is not complex dependency injection; it is a fast, thread-safe service locator designed for networking hot paths.

  • Logger: Centralized diagnostic output.
  • Packet Registry: The “Catalog” that maps opcodes to types.
  • Custom Helpers: Shared database bridges or game-state managers.

The Transport Shell

After configuration and shared services are ready, the dispatch and transport layers are initialized.

  • Dispatch: Where the application becomes “real”. It holds middleware and handlers.
  • Listener: The binary shell. It owns socket acceptance, receive workers, and the FramePipeline (AEAD).
  • Protocol: The bridge that receives “clean” messages from the listener and routes them to dispatch.

A Safe Startup Pattern

For most teams, this is the safest default wiring:

  1. Bind and Validate options.
  2. Register Logger and Packet Registry.
  3. Build Dispatch (Middleware + Handlers).
  4. Build Protocol and Listener.
  5. Activate Dispatch, then start the Listener.