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 PathBuf;
use Conf;
use ;
let loaded = new.?;
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:
- Compiled defaults
- TOML document
- Environment variables
- 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.
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_markdownrenders a configuration reference from theconfschema. Applications commit the output and test that it is current.example::AnnotatedExamplereads an annotated example file, commented settings included, so a test can check that the example documents every option and that every documented value parses.