Configuration

Consumer configuration defines broker connections, physical queue policy, and application shutdown. Handler code declares accepted message contracts; configuration selects which registrations run and which resources they use.

Select the file and mode together#

LILY_CONFIG_PATH=./lily.toml LILY_CONFIG_MODE=development cargo run

Use LILY_CONFIG_PATH and LILY_CONFIG_MODE together. Modes are development, test, and production. If neither is provided, compatibility defaults select lily.toml in the working directory and development mode, without searching parent directories. Providing only one bootstrap variable is invalid.

A missing file is a fail-closed startup error in production. Allowing a missing file in development or test does not remove Consumer's RabbitMQ connection and topology requirements. Use the complete first-application configuration as a working starting point.

Understand loading precedence#

TOML → LILY__SECTION__FIELD environment overlay
     → exact secret/file references → typed validation → immutable snapshot

LILY_CONFIG_PATH=./lily.toml LILY_CONFIG_MODE=production LILY__RABBITMQ__CONSUMER__PASSWORD="$BROKER_PASSWORD" cargo run

Double underscores separate sections in canonical environment overrides. The example changes only the consumer password while retaining other file values. Configuration names and types are validated; unknown typed fields do not add behavior. Store application-specific values under [custom].

Successful loading publishes an immutable snapshot. Changing the file or environment later does not hot-reload a running Consumer. Plan a new application startup to apply changes; secret management follows the same snapshot boundary.

Separate connections from topology#

[lifecycle]
shutdown_timeout_secs = 30

You can add this section to the existing lily.toml; 30 seconds is the default. It is the total application root budget, not a separate allowance added to every phase. Keep connection and topology settings out of handler macros, which select queue/version/content contracts.

Select configuration programmatically#

Consumer's builder has no general .config_path(). For programmatic options, enable the facade's config feature and seed ConfigService while building a caller-owned container. The function below does not run Consumer; it returns the builder and container together for the parent owner to manage.

lilyrs = { version = "0.1.0", features = ["consumer", "config"] }

use std::sync::Arc;
use lilyrs::{
    config::ConfigService,
    consumer::{ApplicationContainer, Consumer, ConsumerBuilder},
};

async fn configured_consumer()
    -> Result<(ConsumerBuilder, Arc<ApplicationContainer>), Box<dyn std::error::Error>>
{
    let container = Arc::new(ApplicationContainer::builder()
        .seed_singleton(ConfigService::production("./lily.toml"))
        .build().await?);
    let builder = Consumer::builder().container(Arc::clone(&container));
    Ok((builder, container))
}

Container construction may initialize Singletons; it is more than a configuration carrier. Reconcile caller-owned container shutdown with the managed lifecycle result. Resolve ConfigService and call load().await? to obtain a snapshot; loading again returns the same immutable configuration.

Diagnostics and reference#

Prefer the snapshot's redacted_values() view for diagnostics; typed configuration may contain resolved secrets. Field defaults and limits are listed in configuration reference, while broker choices are covered by topology and transport security.