rushls-common 0.1.0

Configuration, outbound HTTP, lifecycle hooks, rotating TLS, and listener helpers shared by Rushls services
Documentation

rushls-common

Infrastructure shared by Rushls and its sibling services. Every module is behind a feature of the same name, so a dependent compiles only what it uses. Nothing here chooses application policy or logs: reporting stays with each application's own events.

Feature Module Provides
config config Layered configuration loading over conf schemas
outbound outbound A pooled HTTP client for operator-configured services, with optional client TLS
hooks hooks Ordered, best-effort lifecycle event delivery (CloudEvents JSON)
tls tls TLS termination with certificates that rotate under a running listener
axum tls axum::serve::Listener for the TLS listener
metrics metrics Prometheus endpoint helpers: bearer tokens and label escaping
proxy-protocol proxy_protocol PROXY protocol v1 and v2 headers, read ahead of a TCP stream
accept accept Accept-loop error classification and backoff

outbound enables tls, and hooks enables outbound.

Configuration

Configuration loading independent of application policy. Application schemas use conf::Conf with Serde support. The loader owns file discovery, interpolation, source precedence, environment warnings, and source metadata.

Application integration

use std::path::PathBuf;
use conf::Conf;
use rushls_common::config::{Loader, SecretString};

#[derive(Conf)]
#[conf(serde, name = "example", env_prefix = "EXAMPLE_")]
pub struct Config {
    #[conf(long, env, serde(skip))]
    config: Option<PathBuf>,

    #[conf(long, env, default_value = "127.0.0.1:8080")]
    listen: std::net::SocketAddr,

    #[conf(env, secret)]
    token: Option<SecretString>,
}

let loaded = Loader::new("example", "EXAMPLE_").load::<Config>()?;

The application declares conf as a direct dependency because its derive macro uses the conf crate path. The loader prefix matches the schema prefix. A field marked env derives its environment name from the field name. Nested structs use #[conf(flatten, prefix)] to derive nested names. The example accepts EXAMPLE_LISTEN, --listen, and the TOML key listen.

Application validation runs after loading. The shared crate does not construct services, choose media policies, or start background tasks.

Source contract

Values resolve in this order, with later sources overriding earlier sources:

  1. Compiled defaults
  2. TOML document
  3. Environment variables
  4. CLI arguments.

File selection uses --config, then <PREFIX>CONFIG. An explicit path must exist. Without an explicit path, discovery selects the first file named <app>.toml in the working directory or platform configuration directories. The local platform directory precedes the roaming directory. Paths inside the document remain relative to the process working directory.

explicit_only().load_from(args, env) disables discovery and accepts source snapshots. Tests do not mutate the process environment or read the live shell. load() reads the live process arguments and environment.

Unknown CLI arguments and TOML fields fail startup. Unknown application-prefixed environment variables produce warnings and are ignored as configuration overrides. Environment names come from the derived schema, including declared aliases. Loaded::warnings contains sorted, deduplicated diagnostics with variable names but no values. Each application reports these diagnostics at startup. Variables outside the application prefix produce no warning.

All environment variables remain available for explicit TOML interpolation. Custom interpolation inputs can use names such as INGEST_HOST to avoid warnings about undeclared application-prefixed names.

Schemas can explicitly contain maps with operator-defined keys. Those maps retain their own validation of entry fields.

Interpolation

Interpolation applies to TOML string values, including strings inside arrays and tables. It never changes keys or table names.

Syntax Meaning
${NAME} Required environment variable
${NAME:-fallback} Literal fallback when the variable is unset or empty, as in a shell
$$ Literal dollar sign
$NAME Literal text

Names use ASCII letters, digits, and underscores, starting with a letter or underscore. A defined empty value remains empty, even with a fallback. Inserted values are literal strings. They cannot introduce TOML fields or trigger another interpolation pass. Fallback values are not recursively expanded. Interpolation runs before overrides, so unresolved file references still fail when another source overrides the field.

Credentials and diagnostics

Secret fields use #[conf(env, secret)] and SecretString for redacted Debug output and Serde type errors. Existing string fields can use serde(deserialize_with = "rushls_common::config::deserialize_secret") for error redaction. conf disallows inline CLI arguments on fields marked secret.

Credentials use one TextSource field each: a literal string (including "${VAR}" interpolation) or { file = "/path" }. The value's shape selects the source, so there is no separate _file field to conflict with. Environment values accept the same two spellings. TextSource::read returns the text. Mounted secret files lose trailing CR/LF characters only. Spaces remain part of the credential. Inline values remain unchanged.

Loaded::sources maps field identifiers to defaults, CLI arguments, environment names, or document names. It contains no configuration values. TOML syntax diagnostics omit source lines. Interpolation diagnostics omit the value being expanded. Help and version remain available with broken configuration. Applications own diagnostic output and exit handling.

Dependencies and tests

This crate depends on parsing and filesystem libraries. It has no dependency on HTTP, hooks, TLS, or the application.

cargo test -p rushls-common --all-features --locked

Shared schema vocabulary

Applications use the same value shapes, so the same spelling means the same thing in Rushls and Routmp:

Item Purpose
OptionalDuration A duration, or "off"/"none" where waiting indefinitely is legitimate
OptionalAddress A listener address, or "off"
OptionalBytes A byte limit, or "unlimited"
TomlTable<T> An open namespace keyed by operator-chosen names, such as [hook.<name>]
TomlValue<T> A structured value handed over as TOML text, overridable from the environment
read_credential A TextSource credential whose CLI flag names a file

Two modules keep documentation tied to the schema:

  • reference::reference_markdown renders a configuration reference from the conf schema. Applications commit the output and test that it is current.
  • example::AnnotatedExample reads an annotated example file, commented settings included, so a test can check that the example documents every option and that every documented value parses.