dynamic_config/source.rs
1//! What to load, and from where.
2
3/// Separator that introduces one level of nesting in a variable name.
4///
5/// A single underscore cannot mean both "word break" and "nesting", so nesting
6/// gets the doubled form: `APP_DB_POOL__MAX_SIZE` is `pool.max_size`, while
7/// `APP_DB_MAX_SIZE` is the single field `max_size`.
8pub const DEFAULT_NEST: &str = "__";
9
10/// A configuration file format.
11///
12/// Every variant exists regardless of which features are enabled; parsing one
13/// whose feature is off is a runtime [`ErrorKind::Backend`](crate::ErrorKind).
14/// Code written through `#[dynamic_config]` cannot reach that error — the macro
15/// turns it into a compile error naming the missing feature.
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
17pub enum Format {
18 /// JSON, via the `json` feature.
19 Json,
20 /// TOML, via the `toml` feature.
21 Toml,
22 /// YAML, via the `yaml` feature.
23 Yaml,
24}
25
26impl Format {
27 /// The format a path's extension names.
28 ///
29 /// A `.age` suffix is looked *through*: `secrets.json.age` is JSON that
30 /// happens to be encrypted, so the format is the one under the suffix.
31 ///
32 /// # Errors
33 ///
34 /// If the name resolves to no supported format.
35 pub fn from_path(path: &std::path::Path) -> Result<Self, crate::Error> {
36 let named = path.to_str().unwrap_or_default();
37 let inner = inner_name(named).map_or(named, |(inner, _)| inner);
38
39 std::path::Path::new(inner)
40 .extension()
41 .and_then(|extension| extension.to_str())
42 .and_then(Self::from_extension)
43 .ok_or_else(|| crate::Error::unsupported(path))
44 }
45
46 /// The cargo feature that enables this format.
47 #[must_use]
48 pub fn feature(self) -> &'static str {
49 match self {
50 Self::Json => "json",
51 Self::Toml => "toml",
52 Self::Yaml => "yaml",
53 }
54 }
55
56 /// Infers a format from a file extension, case-insensitively.
57 ///
58 /// Returns `None` for an unknown or absent extension. The macro performs
59 /// the same inference at compile time.
60 #[must_use]
61 pub fn from_extension(extension: &str) -> Option<Self> {
62 match extension.to_ascii_lowercase().as_str() {
63 "json" => Some(Self::Json),
64 "toml" => Some(Self::Toml),
65 "yaml" | "yml" => Some(Self::Yaml),
66 _ => None,
67 }
68 }
69
70 /// Infers a format from a store key's extension: `app/config.json` is
71 /// JSON.
72 ///
73 /// What every remote store crate does with the key it was given, written
74 /// once. Returns `None` when the key has no extension or an unknown one —
75 /// the store's `with_format` exists for exactly that case.
76 #[must_use]
77 pub fn from_key(key: &str) -> Option<Self> {
78 std::path::Path::new(key)
79 .extension()
80 .and_then(|extension| extension.to_str())
81 .and_then(Self::from_extension)
82 }
83}
84
85/// No `Debug` or `PartialEq`: a `&dyn Provider` is neither, and equality of
86/// sources was never something a caller could rely on. `Source` renders itself
87/// by hand instead — see its `Debug` impl.
88#[derive(Clone, Copy)]
89enum Kind<'a> {
90 File(&'a str),
91 /// A file whose bytes are ciphertext. `format` describes the plaintext.
92 Encrypted(&'a str),
93 Inline(&'a str),
94 /// Somebody else's figment provider, merged in place.
95 #[cfg(feature = "figment")]
96 Provider(&'a (dyn figment::Provider + Send + Sync)),
97}
98
99/// One layer of configuration.
100///
101/// Constructors are `const`, so a `&'static [Source<'static>]` can live in a
102/// `static` — which is how the macro emits it. The lifetime is there for
103/// everything else: configuration assembled at runtime, fetched over the
104/// network, or read from a pipe borrows just as happily.
105#[derive(Clone, Copy)]
106pub struct Source<'a> {
107 kind: Kind<'a>,
108 format: Format,
109}
110
111impl<'a> Source<'a> {
112 /// A file on disk. A file that does not exist is skipped, not an error —
113 /// listing an optional `secrets.toml` is the whole point of layering.
114 #[must_use]
115 pub const fn file(path: &'a str, format: Format) -> Self {
116 Self {
117 kind: Kind::File(path),
118 format,
119 }
120 }
121
122 /// Configuration already in memory: a compiled-in default, a fixture, or
123 /// something just read off a socket.
124 ///
125 /// figment parses from a string, so anything implementing [`Read`] arrives
126 /// here through [`std::io::read_to_string`] rather than through a variant
127 /// of its own — a reader source would only hide that one line.
128 ///
129 /// ```
130 /// # #[cfg(feature = "json")] {
131 /// use dynamic_config::{load, Format, LoadSpec, Source};
132 /// use serde::Deserialize;
133 ///
134 /// #[derive(Deserialize)]
135 /// struct Db { host: String }
136 ///
137 /// let mut pipe = std::io::Cursor::new(r#"{"db": {"host": "localhost"}}"#);
138 /// let text = std::io::read_to_string(&mut pipe).unwrap();
139 ///
140 /// let sources = [Source::inline(&text, Format::Json)];
141 /// let db: Db = load(&LoadSpec::new("db", &sources)).unwrap();
142 ///
143 /// assert_eq!(db.host, "localhost");
144 /// # }
145 /// ```
146 ///
147 /// [`Read`]: std::io::Read
148 #[must_use]
149 pub const fn inline(text: &'a str, format: Format) -> Self {
150 Self {
151 kind: Kind::Inline(text),
152 format,
153 }
154 }
155
156 /// Configuration from a figment provider of your own.
157 ///
158 /// The three built-in kinds — a file, an encrypted file, inline text — are
159 /// the ones this crate can describe. A provider is anything figment can
160 /// read: `Serialized::defaults(T)`, an `Env` with a filter this crate does
161 /// not model, a provider you wrote, one from another crate.
162 ///
163 /// ```
164 /// # #[cfg(all(feature = "figment", feature = "json"))] {
165 /// use dynamic_config::{load, LoadSpec, Source};
166 /// use figment::providers::{Format as _, Json};
167 /// # use serde::Deserialize;
168 /// # #[derive(Deserialize)] struct Db { host: String }
169 ///
170 /// // `.nested()` because this crate reads a top-level key as a section.
171 /// let provider = Json::string(r#"{"db": {"host": "localhost"}}"#).nested();
172 /// let sources = [Source::provider(&provider)];
173 ///
174 /// let db: Db = load(&LoadSpec::new("db", &sources)).unwrap();
175 /// assert_eq!(db.host, "localhost");
176 /// # }
177 /// ```
178 ///
179 /// # Two things it is on you to get right
180 ///
181 /// **Sections.** Every other source here goes through this crate's own
182 /// mapping of top-level keys to sections. A provider does not: what it
183 /// yields is merged as figment sees it, so it has to produce the section as
184 /// a profile — `.nested()` on a figment `Data` provider does exactly that.
185 ///
186 /// **Provenance.** `source_of` and every error report the provider's own
187 /// metadata name. A provider that describes itself badly produces a
188 /// diagnostic that describes it badly.
189 ///
190 /// The `Send + Sync` bound is not decoration: a `LoadSpec` is moved to
191 /// another thread by `load_async` and by the file watcher, so a provider
192 /// that cannot cross one would take those with it. Every provider figment
193 /// ships already satisfies it.
194 #[cfg(feature = "figment")]
195 #[cfg_attr(docsrs, doc(cfg(feature = "figment")))]
196 #[must_use]
197 pub const fn provider(provider: &'a (dyn figment::Provider + Send + Sync)) -> Self {
198 Self {
199 kind: Kind::Provider(provider),
200 // A provider parses nothing: it hands over values that are already
201 // figment's. `format()` says so by answering `None`.
202 format: Format::Json,
203 }
204 }
205
206 /// This source's format, for the kinds that parse text.
207 ///
208 /// `None` for a [`provider`](Self::provider), which hands over values that
209 /// are already figment's and never sees a byte of text.
210 #[must_use]
211 pub const fn format(&self) -> Option<Format> {
212 match self.kind {
213 #[cfg(feature = "figment")]
214 Kind::Provider(_) => None,
215 _ => Some(self.format),
216 }
217 }
218
219 /// Configuration in a file that is encrypted on disk.
220 ///
221 /// `format` is what the *plaintext* is, so `secrets.json.age` is
222 /// [`Format::Json`]. Reading it needs a decryptor installed with
223 /// [`set_decryptor`](crate::set_decryptor).
224 ///
225 /// In every other respect it is a file: same precedence, same profile
226 /// variants, watched the same way, skipped if it is not there.
227 #[must_use]
228 pub const fn encrypted(path: &'a str, format: Format) -> Self {
229 Self {
230 kind: Kind::Encrypted(path),
231 format,
232 }
233 }
234
235 /// The file path, if this source is a file — encrypted or not.
236 ///
237 /// Encrypted files are included because everything that asks this question
238 /// — profile variants, the directories to watch — wants the same answer for
239 /// both.
240 #[must_use]
241 pub const fn path(&self) -> Option<&'a str> {
242 match self.kind {
243 Kind::File(path) | Kind::Encrypted(path) => Some(path),
244 _ => None,
245 }
246 }
247
248 /// Whether this source has to be decrypted before it can be parsed.
249 #[must_use]
250 pub const fn is_encrypted(&self) -> bool {
251 matches!(self.kind, Kind::Encrypted(_))
252 }
253
254 /// The embedded text, if this source is inline.
255 pub(crate) fn inline_text(&self) -> Option<&'a str> {
256 match self.kind {
257 Kind::Inline(text) => Some(text),
258 _ => None,
259 }
260 }
261
262 /// The foreign provider, if this source is one.
263 #[cfg(feature = "figment")]
264 pub(crate) fn foreign(&self) -> Option<&'a (dyn figment::Provider + Send + Sync)> {
265 match self.kind {
266 Kind::Provider(provider) => Some(provider),
267 _ => None,
268 }
269 }
270}
271
272impl std::fmt::Debug for Source<'_> {
273 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
274 match self.kind {
275 Kind::File(path) => f.debug_tuple("File").field(&path).finish(),
276 Kind::Encrypted(path) => f.debug_tuple("Encrypted").field(&path).finish(),
277 // Never the text: an inline source is as likely to hold secrets as
278 // a file is, and this is the type that would print them.
279 Kind::Inline(text) => f
280 .debug_struct("Inline")
281 .field("bytes", &text.len())
282 .field("format", &self.format)
283 .finish(),
284 #[cfg(feature = "figment")]
285 Kind::Provider(provider) => f
286 .debug_tuple("Provider")
287 .field(&provider.metadata().name)
288 .finish(),
289 }
290 }
291}
292
293/// The suffix that marks a config file as encrypted.
294///
295/// Lives here rather than with the decryption itself because the *naming* rules
296/// — which files are encrypted, what a profile variant of one is called — are
297/// needed whether or not this build can decrypt anything.
298pub(crate) const ENCRYPTED_SUFFIX: &str = "age";
299
300/// Splits `secrets.json.age` into `("secrets.json", "json")`.
301///
302/// `None` when the name does not end in the suffix, or has no extension under
303/// it to name a format.
304pub(crate) fn inner_name(path: &str) -> Option<(&str, &str)> {
305 let stripped = path.strip_suffix(ENCRYPTED_SUFFIX)?.strip_suffix('.')?;
306 let extension = std::path::Path::new(stripped)
307 .extension()
308 .and_then(|extension| extension.to_str())?;
309
310 Some((stripped, extension))
311}
312
313/// Everything the loader needs: which layers, which section, which env prefix.
314///
315/// Prefer [`new`](Self::new) and the `with_*` methods over a struct literal, so
316/// that a later release can add a knob without breaking every call site.
317#[derive(Clone, Copy)]
318pub struct LoadSpec<'a> {
319 /// The configuration section this maps to, e.g. `"db"`.
320 pub key: &'a str,
321 /// Layers, merged left to right. Later sources win.
322 pub sources: &'a [Source<'a>],
323 /// Environment variable prefix, e.g. `"APP_"`. Combined with `key`.
324 /// `None` ignores the environment entirely.
325 pub env_prefix: Option<&'a str>,
326 /// Where to look for configuration files by name, if anywhere.
327 ///
328 /// Discovered files are merged *before* [`sources`](Self::sources), so an
329 /// explicitly listed file still has the last word.
330 pub search: Option<crate::Search<'a>>,
331 /// Environment variable naming the active profile, e.g. `"APP_ENV"`.
332 ///
333 /// When it is set to `production`, every file gains a sibling layer:
334 /// `config.toml` is followed by `config.production.toml`, discovered or
335 /// listed alike. A variant that does not exist is skipped like any other
336 /// missing file.
337 pub profile_env: Option<&'a str>,
338 /// Values below the files: consulted only when nothing else supplies a key.
339 pub defaults: Option<&'a crate::Layer>,
340 /// A document fetched from a remote store: above the files, below the
341 /// environment.
342 pub remote: Option<&'a crate::Remote>,
343 /// `.env` files, read as the environment layer rather than as documents.
344 ///
345 /// Merged in order, just *below* the real environment: a variable somebody
346 /// exported for this run should beat a file in the repository.
347 pub env_files: &'a [&'a str],
348 /// Old key paths that still resolve, filling a gap rather than overriding.
349 pub aliases: Option<&'a crate::Aliases>,
350 /// Fields bound to environment variables by name: just above the prefixed
351 /// environment layer, because a binding is the more specific statement.
352 pub env_bindings: Option<&'a crate::EnvBindings>,
353 /// Values from the command line: above the environment, below overrides.
354 pub flags: Option<&'a crate::Layer>,
355 /// Values above everything, including the environment.
356 pub overrides: Option<&'a crate::Layer>,
357 /// Separator that introduces nesting in an environment variable name.
358 ///
359 /// Defaults to `"__"`, so `APP_DB_POOL__MAX_SIZE` is `pool.max_size`. A
360 /// single separator cannot mean both "word break" and "nesting", so
361 /// whatever this is set to, it has to be something a field name will not
362 /// contain.
363 pub nest: &'a str,
364 /// Whether `FOO=` counts as set-to-empty.
365 ///
366 /// Defaults to `false`, which treats it as unset. An unset value rendered
367 /// into a deployment template leaves exactly `FOO=`, and letting that blank
368 /// out a perfectly good configured value is a bad afternoon. Turn it on
369 /// when empty really is a value you need to be able to send.
370 pub allow_empty_env: bool,
371}
372
373impl std::fmt::Debug for LoadSpec<'_> {
374 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
375 f.debug_struct("LoadSpec")
376 .field("key", &self.key)
377 .field("sources", &self.sources)
378 .field("search", &self.search)
379 .field("profile_env", &self.profile_env)
380 .field("env_prefix", &self.env_prefix)
381 .field("defaults", &self.defaults.is_some())
382 .field("remote", &self.remote.is_some())
383 .field("flags", &self.flags.is_some())
384 .field("overrides", &self.overrides.is_some())
385 .field("nest", &self.nest)
386 .field("allow_empty_env", &self.allow_empty_env)
387 .finish()
388 }
389}
390
391impl<'a> LoadSpec<'a> {
392 /// A spec that reads `sources` and selects `key`, ignoring the environment.
393 #[must_use]
394 pub const fn new(key: &'a str, sources: &'a [Source<'a>]) -> Self {
395 Self {
396 key,
397 sources,
398 search: None,
399 profile_env: None,
400 env_prefix: None,
401 defaults: None,
402 remote: None,
403 env_files: &[],
404 aliases: None,
405 env_bindings: None,
406 flags: None,
407 overrides: None,
408 nest: DEFAULT_NEST,
409 allow_empty_env: false,
410 }
411 }
412
413 /// Looks for `{name}.{ext}` in each of `paths`, in order.
414 ///
415 /// Every directory that has a match contributes one file, so the search
416 /// order *is* the layering order. Discovered files sit below the explicit
417 /// [`sources`](Self::sources).
418 #[must_use]
419 pub const fn with_search(mut self, name: &'a str, paths: &'a [&'a str]) -> Self {
420 self.search = Some(crate::Search::new(name, paths));
421 self
422 }
423
424 /// Layers a per-profile sibling over every file.
425 ///
426 /// `variable` names the environment variable holding the profile, so the
427 /// profile itself is resolved at load time rather than baked in.
428 #[must_use]
429 pub const fn with_profile_env(mut self, variable: &'a str) -> Self {
430 self.profile_env = Some(variable);
431 self
432 }
433
434 /// Values consulted only when no file and no variable supplies a key.
435 #[must_use]
436 pub const fn with_defaults(mut self, layer: &'a crate::Layer) -> Self {
437 self.defaults = Some(layer);
438 self
439 }
440
441 /// `.env` files, merged just below the real environment.
442 ///
443 /// Needs the `dotenv` feature; without it, a non-empty list is an error at
444 /// load time naming the feature rather than a list silently ignored.
445 #[must_use]
446 pub const fn with_env_files(mut self, files: &'a [&'a str]) -> Self {
447 self.env_files = files;
448 self
449 }
450
451 /// Old key paths that still resolve.
452 #[must_use]
453 pub const fn with_aliases(mut self, aliases: &'a crate::Aliases) -> Self {
454 self.aliases = Some(aliases);
455 self
456 }
457
458 /// Fields bound to environment variables by name.
459 #[must_use]
460 pub const fn with_env_bindings(mut self, bindings: &'a crate::EnvBindings) -> Self {
461 self.env_bindings = Some(bindings);
462 self
463 }
464
465 /// A remote store's document, layered over the files.
466 #[must_use]
467 pub const fn with_remote(mut self, remote: &'a crate::Remote) -> Self {
468 self.remote = Some(remote);
469 self
470 }
471
472 /// Values from the command line, layered over the environment.
473 #[must_use]
474 pub const fn with_flags(mut self, layer: &'a crate::Layer) -> Self {
475 self.flags = Some(layer);
476 self
477 }
478
479 /// Values that win over the files, the environment and the flags alike.
480 #[must_use]
481 pub const fn with_overrides(mut self, layer: &'a crate::Layer) -> Self {
482 self.overrides = Some(layer);
483 self
484 }
485
486 /// Layers environment variables named `{prefix}{KEY}_*` over the files.
487 #[must_use]
488 pub const fn with_env(mut self, prefix: &'a str) -> Self {
489 self.env_prefix = Some(prefix);
490 self
491 }
492
493 /// Uses `separator` instead of `__` to introduce nesting.
494 #[must_use]
495 pub const fn with_nest(mut self, separator: &'a str) -> Self {
496 self.nest = separator;
497 self
498 }
499
500 /// Treats `FOO=` as set-to-empty rather than unset.
501 #[must_use]
502 pub const fn with_empty_env(mut self, allow: bool) -> Self {
503 self.allow_empty_env = allow;
504 self
505 }
506
507 /// The active profile, if one is named and set to something.
508 pub(crate) fn profile(&self) -> Option<String> {
509 self.profile_env
510 .and_then(|variable| std::env::var(variable).ok())
511 .map(|profile| profile.trim().to_owned())
512 .filter(|profile| !profile.is_empty())
513 }
514
515 /// The full environment prefix for this section: `"APP_"` + `"db"` → `"APP_DB_"`.
516 pub(crate) fn full_env_prefix(&self) -> Option<String> {
517 self.env_prefix
518 .map(|prefix| format!("{prefix}{}_", self.key.to_ascii_uppercase()))
519 }
520}
521
522#[cfg(test)]
523mod tests {
524 use super::*;
525
526 #[test]
527 fn extensions_map_to_formats_case_insensitively() {
528 assert_eq!(Format::from_extension("JSON"), Some(Format::Json));
529 assert_eq!(Format::from_extension("yml"), Some(Format::Yaml));
530 assert_eq!(Format::from_extension("yaml"), Some(Format::Yaml));
531 assert_eq!(Format::from_extension("ini"), None);
532 }
533
534 #[test]
535 fn the_env_prefix_combines_the_caller_prefix_with_the_key() {
536 let spec = LoadSpec::new("db", &[]).with_env("APP_");
537
538 assert_eq!(spec.full_env_prefix().as_deref(), Some("APP_DB_"));
539 }
540
541 #[test]
542 fn no_env_prefix_means_no_environment() {
543 assert_eq!(LoadSpec::new("db", &[]).full_env_prefix(), None);
544 }
545
546 #[test]
547 fn an_empty_environment_variable_is_unset_by_default() {
548 assert!(!LoadSpec::new("db", &[]).allow_empty_env);
549 assert!(
550 LoadSpec::new("db", &[])
551 .with_empty_env(true)
552 .allow_empty_env
553 );
554 }
555
556 #[test]
557 fn only_file_sources_expose_a_path() {
558 assert_eq!(Source::file("a.json", Format::Json).path(), Some("a.json"));
559 assert_eq!(Source::inline("{}", Format::Json).path(), None);
560 }
561
562 #[test]
563 fn a_source_can_borrow_from_a_runtime_string() {
564 let text = String::from("{}");
565 let source = Source::inline(&text, Format::Json);
566
567 assert_eq!(source.path(), None);
568 }
569}