Module config

Expand description

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:

values defined in a section of the TOML file, for instance, timeouts for a specific listener
values defined globally in the TOML file, like timeouts or buffer size
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).
FileUdpClusterConfig: UDP-specific cluster knobs, parsed from a [clusters.<id>.udp] block.
FileUdpHealthConfig: UDP backend health-check configuration, parsed from [clusters.<id>.udp.health].
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_SNI_PREREAD_MAX_BYTES: maximum number of bytes buffered while prereading the TLS ClientHello looking for the SNI extension on a TCP listener (16 KB — matches the H2 frame ceiling used elsewhere in this file). Only relevant when at least one SNI-scoped TcpFrontendConfig targets the listener; clamped by the global buffer_size (see ConfigError::SniPrereadMaxBytesExceedsBufferSize). Must match the proto default on TcpListenerConfig.sni_preread_max_bytes.
DEFAULT_SNI_PREREAD_TIMEOUT: maximum time allowed to receive enough bytes of the TLS ClientHello to read the SNI extension on a TCP listener (5 seconds). Only relevant when at least one SNI-scoped TcpFrontendConfig targets the listener. Must match the proto default on TcpListenerConfig.sni_preread_timeout.
DEFAULT_STICKY_NAME: a name applied to sticky sessions (“SOZUBALANCEID”)
DEFAULT_UDP_BACK_TIMEOUT: upstream flow idle timeout for a UDP listener (30 seconds)
DEFAULT_UDP_FRONT_TIMEOUT: client/upstream flow idle timeout for a UDP listener (30 seconds)
DEFAULT_UDP_MAX_FLOWS: maximum number of concurrent UDP flows per listener. 0 selects the runtime auto policy (~70% of the soft RLIMIT_NOFILE).
DEFAULT_UDP_MAX_RX_DATAGRAM_SIZE: maximum received datagram size for a UDP listener, in bytes (1500 = a typical Ethernet MTU). Capped at the effective buffer_size at runtime.
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
MIN_SNI_PREREAD_MAX_BYTES: minimum allowed sni_preread_max_bytes on a TCP listener targeted by an SNI frontend (5 bytes — a full TLS record header: 1-byte ContentType + 2-byte ProtocolVersion + 2-byte length, RFC 8446 §5.1). 0 (and every value below this floor) makes the preread shell issue reads that can never accumulate enough bytes to parse even the outer record framing, spinning until the event-loop iteration guard (MAX_LOOP_ITERATIONS) trips instead of ever reaching a routing decision. See ConfigError::SniPrereadMaxBytesTooSmall.

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.
validate_sni_pattern: Validates and normalizes a TCP frontend’s SNI pattern (sozu-proxy/sozu#1279): either an exact hostname or a single leading *. wildcard label. Rejects an embedded * anywhere else (so *.*.example.com and foo.*.com are both invalid), a bare *, any empty label (leading/trailing/consecutive dots), and any non-ASCII character (ConfigError::NonAsciiSniPattern) — on-wire SNI is always an ASCII A-label (RFC 6066 §3 / IDNA), so a Unicode U-label would load fine but never match at runtime, a silent routing failure. Full IDNA/ punycode transformation at config-load is intentionally out of scope (no idna dependency in this crate); operators write the A-label form directly, consistent with what the HTTP router produces via idna::domain_to_ascii in lib/src/router/mod.rs. ASCII-lowercases the accepted pattern for case-insensitive comparison.

Module config

Module config Copy item path

§Sōzu’s configuration

§How values are chosen

Structs§

Enums§

Constants§

Functions§

Module config