Configuration and secrets · WebSocket

Explicitly define central lily.toml settings, environment overrides, and the precedence of builder choices.

A WebSocket application uses an immutable configuration snapshot through ConfigService. Taking the address from the builder and taking the entire server policy from the builder are different choices.

Start from configuration#

[websocket]
enabled = true
host = "127.0.0.1"
port = 8081
endpoint_path = "/ws"
allowed_origins = ["http://localhost:3000"]
supported_protocols = ["lily.v2"]
require_subprotocol = true
message_timeout_secs = 30
message_cleanup_timeout_secs = 10
connection_middleware_timeout_secs = 10
connection_lifecycle_timeout_secs = 30
inbound_queue_capacity = 16
inbound_queue_max_bytes = 1048576
outbound_queue_capacity = 256
outbound_queue_max_bytes = 1048576

[lifecycle]
shutdown_timeout_secs = 30

use lilyrs::websocket::WsAppBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = WsAppBuilder::default().build().await?;
    app.start().await?;
    Ok(())
}

Include the application's controller modules in compilation as well. The public configuration entry point is default(). config_backed() is a private helper. Since central enabled defaults to false, configuration-based build requires explicit enablement.

Builder precedence#

Choice	Effect
`default()`	Uses the central address and server policy
`new("127.0.0.1:8081")`	Selects the address and treats the listener as enabled; other policies come from configuration
`.config(ServerConfig { ... })`	Selects the entire ServerConfig object; does not merge central fields individually
`.rustls_config(tls)`	Selects the listener's TLS policy
`.tls_disabled()`	Removes the builder's TLS choice
`.secret_resolver(resolver)`	Supplies a secret source for the app-created ConfigService
`.container(container)`	Uses a previously prepared external container
`.add_background_service::<T>()`	Registers a worker under the application's startup and shutdown ownership

Do not combine .container(...) with .secret_resolver(...); the external container owns its own ConfigService. Writing WebSocket certificate fields in a configuration file does not automatically configure TLS; WSS is selected through the builder.

Worker registration is explicit on the builder; configuration alone does not create it. Background services explains the shared shutdown budget and per-job DI scopes.

Environment and secrets#

The order is TOML → LILY__... environment overrides → permitted exact secret/file references → validation → snapshot. For example, LILY__WEBSOCKET__PORT=8082 changes the port on the configuration path; it does not change an explicit new(...) address.

For a custom configuration path, provide LILY_CONFIG_PATH and LILY_CONFIG_MODE together. Mode can be development, test, or production. Allowing defaults when the default file is missing in development does not mean a missing production file is accepted. A secret reference works only in a supported field with a real resolver; do not assume interpolation or automatic secret resolution for every field.

Live changes and limits#

A configuration snapshot does not automatically recreate a running listener. Secret rotation and certificate renewal belong to the application's operational plan. Configure timeout and queue values according to the distinct budgets explained in deadlines, backpressure, and the reference.