Sentinel Configuration

Configuration loading, parsing, validation, and hot-reload support for Sentinel reverse proxy.

Features

• Multiple Formats: KDL (primary), JSON, and TOML configuration support
• Schema Validation: Comprehensive validation with informative error messages
• Hot Reload: Watch configuration files for changes and reload without restart
• Multi-File Support: Split configuration across multiple files
• Secure Defaults: Security-first default values throughout
• Namespace Support: Hierarchical organization for multi-tenant deployments

Quick Start

Minimal Configuration (KDL)

schema-version "1.0"

server {
    worker-threads 0  // Auto-detect CPU cores
}

listeners {
    listener "http" {
        address "0.0.0.0:8080"
        protocol "http"
    }
}

upstreams {
    upstream "backend" {
        target "127.0.0.1:3000"
    }
}

routes {
    route "api" {
        matches {
            path-prefix "/api"
        }
        upstream "backend"
    }
}

Loading Configuration

use sentinel_config::Config;

// From file (format detected by extension)
let config = Config::from_file("sentinel.kdl")?;

// From KDL string
let config = Config::from_kdl(kdl_content)?;

// Default embedded configuration
let config = Config::default_embedded()?;

// Validate configuration
config.validate()?;

Configuration Sections

Documentation

Detailed documentation is available in the docs/ directory:

• KDL Configuration Format - Syntax guide and examples
• Schema Reference - Complete configuration schema
• Validation & Defaults - Validation rules and default values
• Examples - Common configuration patterns

Schema Version

The configuration uses semantic versioning for compatibility:

schema-version "1.0"

Older versions may not load. Newer versions load with a warning.

Service Types

Routes can serve different types of content:

Built-in Handlers

For service-type "builtin":

Filter Types

Built-in filters for request/response processing:

Hot Reload

Enable automatic configuration reload:

server {
    auto-reload true
}

Or manually trigger reload:

config.reload("sentinel.kdl")?;

Multi-File Configuration

Split configuration across multiple files:

config/
├── main.kdl           # Server, listeners
├── routes/
│   ├── api.kdl        # API routes
│   └── web.kdl        # Web routes
├── upstreams/
│   └── backends.kdl   # Backend pools
└── agents/
    └── waf.kdl        # WAF agent

Load with:

use sentinel_config::MultiFileLoader;

let loader = MultiFileLoader::new("config/");
let config = loader.load()?;

Default Configuration

When no configuration file is provided, Sentinel uses an embedded default:

• HTTP listener on 0.0.0.0:8080
• Admin listener on 0.0.0.0:9090
• Built-in status, health, and metrics endpoints
• Sensible resource limits

Validation

Configuration is validated for:

• Schema version compatibility
• Required fields presence
• Reference integrity (routes → upstreams, filters → agents)
• Value constraints (timeouts > 0, valid addresses, etc.)
• Security checks (TLS settings, limits)

// Validation happens automatically on load, or explicitly:
config.validate()?;

Error Messages

Parse errors include context for debugging:

KDL configuration parse error:

  Expected closing brace

  --> at line 15, column 1
   14 | upstream "backend" {
   15 |     target "127.0.0.1:3000"
      | ^ expected '}'
   16 | }

  Help: Check for unclosed blocks or missing braces