Module config 

parse TOML config and generate requests from it

Sōzu’s configuration

This module is responsible for parsing the config.toml provided by the flag --config when starting Sōzu.

Here is the workflow for generating a working config:

    config.toml   ->   FileConfig    ->  ConfigBuilder   ->  Config

config.toml is parsed to FileConfig, a structure that itself contains a lot of substructures whose names start with File- and end with -Config, like FileHttpFrontendConfig for instance.

The instance of FileConfig is then passed to a ConfigBuilder that populates a final Config with listeners and clusters.

To illustrate:

use sozu_command_lib::config::{FileConfig, ConfigBuilder};

let file_config = FileConfig::load_from_path("../config.toml")
    .expect("Could not load config.toml");

let config = ConfigBuilder::new(file_config, "../assets/config.toml")
    .into_config()
    .expect("Could not build config");

Note that the path to config.toml is used twice: the first time, to parse the file, the second time, to keep the path in the config for later use.

However, there is a simpler way that combines all this:

use sozu_command_lib::config::Config;

let config = Config::load_from_path("../assets/config.toml")
    .expect("Could not build config from the path");

How values are chosen

Values are chosen in this order of priority:

1. values defined in a section of the TOML file, for instance, timeouts for a specific listener
2. values defined globally in the TOML file, like timeouts or buffer size
3. if a variable has not been set in the TOML file, it will be set to a default defined here

Structs

BackendConfig

Config

Sōzu configuration, populated with clusters and listeners.

ConfigBuilder

A builder that converts FileConfig to Config

FileClusterConfig

FileClusterFrontendConfig

FileConfig

Parsed from the TOML config provided by the user.

FileHealthCheckConfig

FileHstsConfig

HSTS (HTTP Strict Transport Security, RFC 6797) policy as serialised under [https.listeners.default.hsts] (listener default) or [clusters.<id>.frontends.hsts] (per-frontend override).

HeaderEditConfig

A single header mutation as serialised under [[clusters.<id>.frontends.headers]]. Maps to the proto Header message at request-build time.

HttpClusterConfig

HttpFrontendConfig

ListenerBuilder

An HTTP, HTTPS or TCP listener as parsed from the Listeners section in the toml

MetricsConfig

TcpClusterConfig

TcpFrontendConfig

Enums

ClusterConfig

ConfigError

FileClusterProtocolConfig

IncompatibilityKind

ListenerProtocol

MetricDetailLevel

Cardinality knob for metrics labels in the StatsD network drain.

MissingKind

PathRuleType

Constants

DEFAULT_ACCEPT_QUEUE_TIMEOUT

timeout to accept connection events in the accept queue (60 seconds)

DEFAULT_ALPN_PROTOCOLS

Default ALPN protocols advertised by HTTPS listeners. Both HTTP/2 and HTTP/1.1 are enabled, allowing clients to negotiate either.

DEFAULT_AUTOMATIC_STATE_SAVE

wether to save the state automatically (false)

DEFAULT_BACK_TIMEOUT

maximum time of inactivity for a backend socket (30 seconds)

DEFAULT_BUFFER_SIZE

size of the buffers, in bytes (16 KB)

DEFAULT_CIPHER_LIST

Authoritative list of default cipher suites for all rustls-based TLS providers.

DEFAULT_COMMAND_BUFFER_SIZE

size of the buffer for the channels, in bytes. Must be bigger than the size of the data received. (1 MB)

DEFAULT_CONNECT_TIMEOUT

maximum time to connect to a backend server (3 seconds)

DEFAULT_DISABLE_CLUSTER_METRICS

wether to avoid register cluster metrics in the local drain

DEFAULT_EVICT_ON_QUEUE_FULL

whether to evict least-recently-active sessions when the accept queue is saturated (false). Defaults to false because during a DDoS the existing connections are more likely to be legitimate clients than the queued ones; evicting them would serve the attacker. Enable when overload is dominated by normal traffic spikes rather than attacks.

DEFAULT_FRONT_TIMEOUT

maximum time of inactivity for a frontend socket (60 seconds)

DEFAULT_GROUPS_LIST

DEFAULT_HSTS_MAX_AGE

Default Strict-Transport-Security: max-age value (1 year, 31_536_000 seconds) substituted at config-load when an [hsts] block sets enabled = true but omits max_age. Matches the HSTS preload list minimum (https://hstspreload.org/) and the Caddy / Nginx community recommendation. Operators can override with any u32; max_age = 0 is the RFC 6797 §11.4 kill switch and is allowed silently.

DEFAULT_LOG_TARGET

for both logs and access logs

DEFAULT_MAX_BUFFERS

maximum number of buffers (1 000)

DEFAULT_MAX_COMMAND_BUFFER_SIZE

maximum size of the buffer for the channels, in bytes. (2 MB)

DEFAULT_MAX_CONNECTIONS

maximum number of simultaneous connections (10 000)

DEFAULT_MAX_CONNECTIONS_PER_IP

Default per-(cluster, source-IP) connection limit. 0 means unlimited. Counts are kept per (cluster_id, source_ip) so two clusters never share a counter even from the same IP. Per-cluster overrides on the Cluster message take precedence.

DEFAULT_MIN_BUFFERS

minimum number of buffers (1)

DEFAULT_REQUEST_TIMEOUT

maximum time to receive a request since the connection started (10 seconds)

DEFAULT_RETRY_AFTER

Default Retry-After header value (seconds) on HTTP 429 responses emitted when a per-(cluster, source-IP) connection limit is hit. 0 omits the header — Retry-After: 0 invites an immediate retry that defeats the limit. TCP rejections do not emit this value (no HTTP envelope), but the field is accepted for symmetry.

DEFAULT_SEND_TLS_13_TICKETS

Number of TLS 1.3 tickets to send to a client when establishing a connection. The tickets allow the client to resume a session. This protects the client agains session tracking. Increases the number of getrandom syscalls, with little influence on performance. Defaults to 4.

DEFAULT_SIGNATURE_ALGORITHMS

DEFAULT_STICKY_NAME

a name applied to sticky sessions (“SOZUBALANCEID”)

DEFAULT_WORKER_AUTOMATIC_RESTART

wether a worker is automatically restarted when it crashes (true)

DEFAULT_WORKER_COUNT

number of workers, i.e. Sōzu processes that scale horizontally (2)

DEFAULT_WORKER_TIMEOUT

maximum time to wait for a worker to respond, until it is deemed NotAnswering (10 seconds)

DEFAULT_ZOMBIE_CHECK_INTERVAL

Interval between checking for zombie sessions, (30 minutes)

H2_MIN_BUFFER_SIZE

minimum buffer size required when any HTTPS listener advertises H2 ALPN.

MAX_LOOP_ITERATIONS

Functions

default_sticky_name

load_answers

Load every per-status template referenced by answers.

resolve_answer_source

Resolve a single answers map entry into the literal template body the proto layer expects.

validate_health_check_config

Validate a HealthCheckConfig for the rules every layer relies on: strict positive thresholds and a URI that cannot smuggle a second HTTP message on the wire (RFC 9110 §5.1 — request-target). Used by the CLI request builder and the worker SetHealthCheck handler so off-channel inputs (TOML reload, third-party clients) are constrained the same way as sozu cluster health-check set.