Configuration Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/config.rs
• README.md
• src/state.rs
• src/main.rs
• src/templates.rs
• AGENTS.md
• src/auth/session.rs

Configuration Management in Hodor provides a layered and validated system for controlling proxy behavior, authentication settings, and UI appearance. The system ensures that the application has all necessary parameters to function as a secure gatekeeper before the HTTP server starts.

Hodor utilizes the figment library to merge configuration data from multiple sources. It prioritizes environment variables to support Docker sidecar deployments, while allowing local overrides via a TOML file.
Sources: src/config.rs:71-89, README.md:65-71, AGENTS.md:27-28

Layered Configuration Architecture

Hodor loads configuration in a specific hierarchy where each subsequent layer overrides the previous ones.

The diagram shows the precedence of configuration sources, ending in the runtime state used by the server.
Sources: src/config.rs:82-87, README.md:65-71

Configuration Sources

1. Defaults: Hardcoded values within the Config struct implementation provide a baseline for non-critical settings like listen ports and session_ttl.
2. hodor.toml: The application looks for this optional file in the working directory to load settings.
3. Environment Variables: Variables like PASSWORD and UPSTREAM override all other layers. This is the primary method for configuring Docker-based deployments.
   Sources: src/config.rs:82-87, README.md:67-71, AGENTS.md:27-28

Data Structures

The system uses two primary structures to manage settings: a static Config struct for loading and a dynamic AppState for runtime execution.

The Config Struct

The Config struct defines the schema for all possible settings. It uses serde for deserialization from TOML and environment variables.
Sources: src/config.rs:10-41

The AppState Struct

The AppState struct holds the processed runtime state. It converts raw configuration strings into typed objects such as Uri, Duration, and IpNet. It also initializes the shared LoginGuard and the hyper HTTP client.
Sources: src/state.rs:18-42

The relationship between the raw configuration and the functional runtime state.
Sources: src/config.rs:10-41, src/state.rs:18-42

Configuration Options

Key	Env Var	Required	Default	Description
password	PASSWORD	Yes	-	Shared password for gate access.
upstream	UPSTREAM	Yes	-	Backend URL to proxy traffic to.
secret	SECRET	No	Random	Key used to sign HMAC-SHA256 session cookies.
listen	LISTEN	No	:8080	Address the proxy listens on.
session_ttl	SESSION_TTL	No	86400	Session duration in seconds.
trust_proxy	TRUST_PROXY	No	false	Enables trusting X-Forwarded-For headers.
bypass_paths	BYPASS_PATHS	No	[]	CSV of paths that skip authentication.
Sources: README.md:73-100, src/config.rs:10-41

Validation and Initialization

Before the server starts, Hodor performs rigorous validation on the merged configuration.

Validation Rules

• Required Fields: The application panics if PASSWORD or UPSTREAM are missing or empty.
• Network Safety: If TRUSTED_PROXY_CIDRS is provided, TRUST_PROXY must be explicitly set to true.
• Formatting: COOKIE_DOMAIN must follow valid DNS naming conventions, and BYPASS_PATHS must start with a forward slash.
• Timeouts: SESSION_TTL and upstream timeouts must be greater than zero.
  Sources: src/config.rs:95-126, src/config.rs:200-209

State Construction

The build_app_state function handles the transition from Config to AppState. During this process, it:

1. Parses the UPSTREAM string into a Uri.
2. Loads and validates HTML templates from the filesystem or built-in defaults.
3. Initializes the SECRET for cookie signing (generates a random one if not provided).
4. Constructs the LoginGuard for brute-force protection.
   Sources: src/state.rs:44-96, src/templates.rs:15-31, src/auth/session.rs:104-114

The sequence of operations during application startup.
Sources: src/main.rs:29-35, src/config.rs:71-91, src/state.rs:44-96

Template and CSS Configuration

Hodor allows customizing the login and error UIs through configuration variables without requiring a recompilation.

• Custom Templates: Paths provided in TEMPLATE or ERROR_TEMPLATE override the built-in HTML.
• Custom CSS: The CUSTOM_CSS variable accepts raw CSS strings injected into the page <style> tags.
• Base Style Control: DISABLE_DEFAULT_CSS removes the internal dark-theme styling, allowing complete UI redesigns via CUSTOM_CSS.
  Sources: src/templates.rs:15-31, src/config.rs:19-27, README.md:189-216

Summary

Configuration Management in Hodor is a critical startup phase that ensures the proxy operates within safe and expected boundaries. By combining layered loading with strict validation, the system prevents misconfigurations that could lead to security vulnerabilities or runtime failures.
Sources: src/main.rs:29-59, AGENTS.md:27-28