Alternative sources
Plug Vault, a K8s ConfigMap, or AWS Parameter Store behind ConfigSource — the trait ConfigService reads through.
ConfigService reads its raw values through a small trait:
ConfigSource. The default EnvSource reads the process environment and,
for a variable absent there, falls back to the .env cascade parsed into an
in-crate map — reading never writes to the process environment. A variable
present but empty in the process environment counts as unset and still keeps
the .env value from being read. Swap it for anything that can answer
“what’s the value of <PREFIX>_SEAORM__URL?” and the same Config
struct loads from there — HashiCorp Vault, a K8s ConfigMap, AWS Parameter
Store, an in-process map for tests.
The trait
Section titled “The trait”pub trait ConfigSource: Send + Sync + 'static { fn get(&self, var: &str) -> Option<String>;}One required method. var is the fully-qualified name (e.g.
"<PREFIX>_SEAORM__URL") — namespacing happens in ConfigService, the
source just answers lookups. Empty strings count as unset, same rule as
EnvSource.
The trait is sync on purpose: a config’s overlay runs synchronously
at boot. A remote source pre-fetches its keys into an in-memory map
during a factory phase, then serves get from that map.
A custom source — by example
Section titled “A custom source — by example”A Vault source that hits the API once at startup and caches the result:
use std::collections::HashMap;use std::sync::Arc;use nest_rs::config::ConfigSource;use nest_rs::core::EnvPrefix;
pub struct VaultSource { snapshot: HashMap<String, String>,}
impl VaultSource { pub async fn fetch(client: &VaultClient, path: &str) -> anyhow::Result<Self> { let response = client.read(path).await?; let snapshot = response .data .into_iter() .map(|(k, v)| (format!("{}_{}", EnvPrefix::current(), k.to_ascii_uppercase()), v)) .collect(); Ok(Self { snapshot }) }}
impl ConfigSource for VaultSource { fn get(&self, var: &str) -> Option<String> { self.snapshot.get(var).cloned() }}get is the only required method. The trait also carries
get_from_deployment, which defaults to get, and in_deployment, which defaults to
whether get_from_deployment holds a value, and shadows both spellings of a key below
it — that is the tier allowed to
outrank a value pinned in code, and a
custom source counts as deployment-supplied unless it says otherwise. That
default is the safe direction: a Vault secret is never shadowed by a struct
literal. Override it only if your source also serves values that should lose
to a pin.
Wire it in by building the ConfigService directly and calling
Config::from_env yourself — bypassing the factory the boot would queue:
use nest_rs::config::{Config, ConfigService};
let vault = Arc::new( VaultSource::fetch(&vault_client, "secret/api").await?,);let env = ConfigService::with_source("seaorm", vault);let db_config = SeaOrmConfig::from_env(&env, SeaOrmConfig::default())?;
App::builder() .module::<ApiModule>() .provide(db_config) .build() .await?;A seeded config wins over the factory that would read it, so the rest of the app sees the Vault-loaded value without changing any
downstream code. The pattern matches Repo::scoped:
build the seam where the source lives, hand the result to the framework.
When EnvSource is fine
Section titled “When EnvSource is fine”The default source is the right answer for most apps:
- Local dev reads from the
.envcascade. - Production reads from real env vars set by the orchestrator.
- A secrets manager (Vault, AWS Secrets Manager, GCP Secret Manager) typically already injects env vars into the running container.
Reach for a custom ConfigSource only when:
- The secrets manager cannot inject env vars (a sidecar pattern that serves values over HTTP).
- A K8s ConfigMap mounts as a file tree rather than env vars.
- A test needs a programmatic source decoupled from
std::env.
What fails if you get it wrong — hermeticity and the cascade
Section titled “What fails if you get it wrong — hermeticity and the cascade”ConfigService::for_namespace(ns) is with_source(ns, Arc::new(EnvSource)) plus the
report of a variable no config reads. Reading through it mutates nothing. EnvSource
resolves the real process environment first, then falls back to the .env
cascade parsed into a map inside the crate — std::env::set_var is unsound
against a concurrent getenv on another thread, so no read path may write.
Read by hand outside a ConfigService, EnvSource::get witnesses nothing and the
report calls that variable unread; env_var witnesses.
One step publishes the cascade into the process environment:
#[nest_rs::main] runs it before your main, before the runtime exists. It
exists for the consumers that only know std::env::var and never see a
ConfigService — the console’s RUST_LOG and <PREFIX>_LOG_*,
OpenTelemetry::init and the OpenTelemetry SDK’s OTEL_*, your migrate/seed binaries. It writes set-if-absent
(the real env still wins), and it runs before the runtime precisely because a
process with one thread is what makes the write sound. A binary without
#[nest_rs::main] calls load_cascade itself, first thing.
What this means in practice:
- Resolving config is side-effect-free, whichever source you use. Neither
for_namespacenor a module’s import publishes anything; the first config load registers the activeEnvironmentand stops there. TestApp::builder()does publish the cascade. The e2e harness reads backend URLs throughstd::envbefore anyConfigServiceexists, so it callsload_project_env, which publishes the same cascade, the package’s own files over the root’s, once per process. The merge is bounded — set-if-absent, real env still wins, and.env.localis skipped under<PREFIX>_ENV=test— and afor_rootpin still outranks every cascade value. Reach forwith_source(or.provide(cfg)) when a test must not see a committed.envat all: it decides where the values come from, which is the stronger guarantee.- In an app, assume the cascade is in
std::env, becausemainput it there. That is the point: a.envvalue reaches code the DI graph never sees.
What the source sees
Section titled “What the source sees”var is always the fully-qualified <PREFIX>_<NS>__<KEY> string. A few
implications:
- The source receives the uppercased namespace + key — the casing
conversion happens in
var_namebefore the lookup. - The source has no idea which
Configstruct is being loaded. It’s a flat key-value store. If you need per-namespace routing (e.g.seaormfrom Vault,httpfrom env), wrap a couple of sources in a dispatching one. - Empty strings are unset.
ConfigServicedrops an empty value whatever the source returns, so a Vault entry with an empty value never blanks an in-code default. - Every key is looked up under two names,
<KEY>and<KEY>_FILE: the source answers each like any other variable,ConfigServicereads the file the second one names, and a value for both is refused, naming the two.
A dispatching source for two backends:
use nest_rs::config::{ConfigSource, EnvSource, var_name};
pub struct Dispatch { vault: VaultSource, env: EnvSource,}
impl ConfigSource for Dispatch { fn get(&self, var: &str) -> Option<String> { let from_vault = ["seaorm", "oauth"] .into_iter() .any(|namespace| var.starts_with(&var_name(namespace, ""))); if from_vault { self.vault.get(var) } else { self.env.get(var) } }}Going further
Section titled “Going further”- Configuration overview — the typed-struct contract.
- The .env cascade — load order, hermeticity, file naming.
- Overriding in tests —
with_varsfor unit tests,.provide()for e2e.