Skip to content

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.

nest_rs::config::ConfigSource
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 Vault source that hits the API once at startup and caches the result:

apps/api/src/vault.rs
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:

apps/api/src/main.rs
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.

The default source is the right answer for most apps:

  • Local dev reads from the .env cascade.
  • 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_namespace nor a module’s import publishes anything; the first config load registers the active Environment and stops there.
  • TestApp::builder() does publish the cascade. The e2e harness reads backend URLs through std::env before any ConfigService exists, so it calls load_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.local is skipped under <PREFIX>_ENV=test — and a for_root pin still outranks every cascade value. Reach for with_source (or .provide(cfg)) when a test must not see a committed .env at all: it decides where the values come from, which is the stronger guarantee.
  • In an app, assume the cascade is in std::env, because main put it there. That is the point: a .env value reaches code the DI graph never 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_name before the lookup.
  • The source has no idea which Config struct is being loaded. It’s a flat key-value store. If you need per-namespace routing (e.g. seaorm from Vault, http from env), wrap a couple of sources in a dispatching one.
  • Empty strings are unset. ConfigService drops 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, ConfigService reads the file the second one names, and a value for both is refused, naming the two.

A dispatching source for two backends:

apps/api/src/dispatch.rs
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)
}
}
}