env_reader/reader.rs
1//! Reading a whole configuration, collecting every problem on the way.
2
3use std::collections::BTreeMap;
4use std::str::FromStr;
5
6use crate::error::{Error, Errors};
7use crate::secret::Secret;
8use crate::value::{parse_bool, parse_bool_lenient, parse_csv, present};
9
10/// What an unparseable integer is reported as.
11const A_WHOLE_NUMBER: &str = "a whole number";
12
13/// Reads a configuration from variables, accumulating problems rather than
14/// stopping at the first.
15///
16/// A reader is built once, asked for every value the program needs, and
17/// then [`finish`](Reader::finish)ed. Each getter returns a usable value
18/// even when it failed — a required string that was missing comes back
19/// empty — so a caller can read the whole configuration in one straight run
20/// of statements without `?` after every line. `finish` is what decides
21/// whether any of it was valid.
22///
23/// That shape is the point: a program with four missing variables reports
24/// all four, once, instead of over four restarts.
25///
26/// # Examples
27///
28/// ```
29/// use env_reader::Reader;
30///
31/// #[derive(Debug)]
32/// struct Config {
33/// service_name: String,
34/// port: u16,
35/// upstreams: Vec<String>,
36/// }
37///
38/// let mut reader = Reader::from_pairs([
39/// ("SERVICE_NAME", "orders"),
40/// ("PORT", "8443"),
41/// ("UPSTREAMS", "a.internal, b.internal"),
42/// ]);
43///
44/// let config = Config {
45/// service_name: reader.required_string("SERVICE_NAME"),
46/// port: reader.integer_or("PORT", 8080),
47/// upstreams: reader.list("UPSTREAMS"),
48/// };
49/// reader.finish()?;
50///
51/// assert_eq!(config.port, 8443);
52/// assert_eq!(config.upstreams, ["a.internal", "b.internal"]);
53/// # Ok::<(), env_reader::Errors>(())
54/// ```
55#[derive(Debug, Clone)]
56pub struct Reader {
57 /// The variables this reader sees.
58 source: BTreeMap<String, String>,
59 /// Problems found so far, in the order they were found.
60 errors: Vec<Error>,
61}
62
63impl Reader {
64 /// A reader over the process environment.
65 ///
66 /// The only constructor that touches the environment, so every other
67 /// path is testable without mutating global state — which
68 /// [`std::env::set_var`] is `unsafe` for good reason.
69 #[must_use]
70 pub fn from_env() -> Self {
71 Self::from_pairs(std::env::vars())
72 }
73
74 /// A reader over an explicit set of variables, for tests and for
75 /// configuration that arrives from somewhere other than the
76 /// environment.
77 ///
78 /// # Examples
79 ///
80 /// ```
81 /// use env_reader::Reader;
82 ///
83 /// let mut reader = Reader::from_pairs([("PORT", "9000")]);
84 /// assert_eq!(reader.integer_or::<u16>("PORT", 8080), 9000);
85 /// ```
86 pub fn from_pairs<K, V, I>(pairs: I) -> Self
87 where
88 I: IntoIterator<Item = (K, V)>,
89 K: Into<String>,
90 V: Into<String>,
91 {
92 Self {
93 source: pairs
94 .into_iter()
95 .map(|(key, value)| (key.into(), value.into()))
96 .collect(),
97 errors: Vec::new(),
98 }
99 }
100
101 // -- reading ----------------------------------------------------------
102
103 /// The raw value of a variable, trimmed, or `None` when absent or
104 /// blank.
105 ///
106 /// # Examples
107 ///
108 /// ```
109 /// use env_reader::Reader;
110 ///
111 /// let reader = Reader::from_pairs([("A", " x "), ("B", " ")]);
112 /// assert_eq!(reader.raw("A"), Some("x"));
113 /// assert_eq!(reader.raw("B"), None);
114 /// assert_eq!(reader.raw("C"), None);
115 /// ```
116 #[must_use]
117 pub fn raw(&self, name: &str) -> Option<&str> {
118 present(self.source.get(name).map(String::as_str))
119 }
120
121 /// Whether a variable is set to something non-blank.
122 ///
123 /// # Examples
124 ///
125 /// ```
126 /// use env_reader::Reader;
127 ///
128 /// let reader = Reader::from_pairs([("A", "x"), ("B", " ")]);
129 /// assert!(reader.is_set("A"));
130 /// assert!(!reader.is_set("B"), "blank is absent");
131 /// assert!(!reader.is_set("C"));
132 /// ```
133 #[must_use]
134 pub fn is_set(&self, name: &str) -> bool {
135 self.raw(name).is_some()
136 }
137
138 /// A variable that must be set.
139 ///
140 /// Records [`Error::Missing`] and returns an empty string when it is
141 /// not, so reading can continue and every other problem is found too.
142 ///
143 /// # Examples
144 ///
145 /// ```
146 /// use env_reader::Reader;
147 ///
148 /// let mut reader = Reader::from_pairs([("SERVICE_NAME", "orders")]);
149 /// assert_eq!(reader.required_string("SERVICE_NAME"), "orders");
150 /// assert_eq!(reader.required_string("REGION"), "");
151 /// assert_eq!(reader.finish().unwrap_err().len(), 1);
152 /// ```
153 pub fn required_string(&mut self, name: &str) -> String {
154 if let Some(value) = self.raw(name) {
155 value.to_string()
156 } else {
157 self.errors.push(Error::missing(name));
158 String::new()
159 }
160 }
161
162 /// A variable that need not be set.
163 ///
164 /// # Examples
165 ///
166 /// ```
167 /// use env_reader::Reader;
168 ///
169 /// let reader = Reader::from_pairs([("REGION", "eu-west-2")]);
170 /// assert_eq!(reader.optional_string("REGION").as_deref(), Some("eu-west-2"));
171 /// assert_eq!(reader.optional_string("ZONE"), None);
172 /// ```
173 #[must_use]
174 pub fn optional_string(&self, name: &str) -> Option<String> {
175 self.raw(name).map(str::to_string)
176 }
177
178 /// An optional variable with a fallback.
179 ///
180 /// # Examples
181 ///
182 /// ```
183 /// use env_reader::Reader;
184 ///
185 /// let reader = Reader::from_pairs([("HOST", "0.0.0.0")]);
186 /// assert_eq!(reader.string_or("HOST", "127.0.0.1"), "0.0.0.0");
187 /// assert_eq!(reader.string_or("BIND", "127.0.0.1"), "127.0.0.1");
188 /// ```
189 #[must_use]
190 pub fn string_or(&self, name: &str, default: &str) -> String {
191 self.raw(name).unwrap_or(default).to_string()
192 }
193
194 // -- secrets ----------------------------------------------------------
195
196 /// A secret that must be set.
197 ///
198 /// # Examples
199 ///
200 /// ```
201 /// use env_reader::Reader;
202 ///
203 /// let mut reader = Reader::from_pairs([("DB_PASSWORD", "hunter2")]);
204 /// let password = reader.required_secret("DB_PASSWORD");
205 /// assert_eq!(format!("{password:?}"), "<redacted>");
206 /// ```
207 pub fn required_secret(&mut self, name: &str) -> Secret {
208 Secret::new(self.required_string(name))
209 }
210
211 /// A secret that need not be set.
212 ///
213 /// # Examples
214 ///
215 /// ```
216 /// use env_reader::Reader;
217 ///
218 /// let reader = Reader::from_pairs([("API_KEY", " ")]);
219 /// assert!(reader.optional_secret("API_KEY").is_none());
220 /// ```
221 #[must_use]
222 pub fn optional_secret(&self, name: &str) -> Option<Secret> {
223 self.raw(name).map(Secret::new)
224 }
225
226 // -- integers ---------------------------------------------------------
227
228 /// An integer that must be set.
229 ///
230 /// # Examples
231 ///
232 /// ```
233 /// use env_reader::Reader;
234 ///
235 /// let mut reader = Reader::from_pairs([("PORT", "8443")]);
236 /// assert_eq!(reader.required_integer::<u16>("PORT"), 8443);
237 /// ```
238 pub fn required_integer<T>(&mut self, name: &str) -> T
239 where
240 T: FromStr + Default,
241 {
242 self.required_parse(name, A_WHOLE_NUMBER).unwrap_or_default()
243 }
244
245 /// An integer that need not be set.
246 ///
247 /// A blank value is absent, not a parse failure.
248 ///
249 /// # Examples
250 ///
251 /// ```
252 /// use env_reader::Reader;
253 ///
254 /// let mut reader = Reader::from_pairs([("A", "30"), ("B", " ")]);
255 /// assert_eq!(reader.optional_integer::<u64>("A"), Some(30));
256 /// assert_eq!(reader.optional_integer::<u64>("B"), None);
257 /// assert!(reader.finish().is_ok());
258 /// ```
259 pub fn optional_integer<T>(&mut self, name: &str) -> Option<T>
260 where
261 T: FromStr,
262 {
263 self.optional_parse(name, A_WHOLE_NUMBER)
264 }
265
266 /// An integer with a fallback.
267 ///
268 /// An unparseable value is a recorded error, **not** a silent fallback
269 /// to the default: a program quietly running on a default nobody chose
270 /// is harder to diagnose than one that will not start.
271 ///
272 /// # Examples
273 ///
274 /// ```
275 /// use env_reader::Reader;
276 ///
277 /// let mut reader = Reader::from_pairs([("PORT", "8443"), ("OTHER", "two")]);
278 /// assert_eq!(reader.integer_or::<u16>("PORT", 8080), 8443);
279 /// assert_eq!(reader.integer_or::<u16>("MISSING", 8080), 8080);
280 /// assert_eq!(reader.integer_or::<u16>("OTHER", 8080), 8080);
281 /// // The absent one is fine; the unparseable one is not.
282 /// assert_eq!(reader.finish().unwrap_err().len(), 1);
283 /// ```
284 pub fn integer_or<T>(&mut self, name: &str, default: T) -> T
285 where
286 T: FromStr,
287 {
288 self.parse_or(name, A_WHOLE_NUMBER, default)
289 }
290
291 /// An optional integer that, when present, must be greater than zero.
292 ///
293 /// For the "absent means unlimited" shape, where a configured zero is a
294 /// mistake rather than a request for an infinite wait.
295 ///
296 /// # Examples
297 ///
298 /// ```
299 /// use env_reader::Reader;
300 ///
301 /// let mut reader = Reader::from_pairs([("A", "30"), ("B", "0")]);
302 /// assert_eq!(reader.optional_positive_integer::<u32>("A"), Some(30));
303 /// assert_eq!(reader.optional_positive_integer::<u32>("B"), None);
304 /// assert_eq!(reader.optional_positive_integer::<u32>("C"), None);
305 /// // Only B is a problem; C was simply absent.
306 /// assert_eq!(reader.finish().unwrap_err().len(), 1);
307 /// ```
308 pub fn optional_positive_integer<T>(&mut self, name: &str) -> Option<T>
309 where
310 T: FromStr + PartialOrd + Default,
311 {
312 let raw = self.raw(name)?.to_string();
313 let parsed: T = self.parse(name, &raw, A_WHOLE_NUMBER)?;
314
315 if parsed > T::default() {
316 Some(parsed)
317 } else {
318 self.errors.push(Error::invalid(
319 name,
320 "a positive integer when provided",
321 raw,
322 ));
323 None
324 }
325 }
326
327 // -- anything with a `FromStr` ----------------------------------------
328
329 /// Any [`FromStr`] value that must be set.
330 ///
331 /// `expected` is the noun phrase the error message uses: `a socket
332 /// address`, `an RFC 3339 timestamp`, `a log level`. It is the whole
333 /// difference between a message somebody can act on and one they
334 /// cannot, so it is required rather than derived from the type name.
335 ///
336 /// Returns `None` on either failure, having recorded it.
337 ///
338 /// # Examples
339 ///
340 /// ```
341 /// use std::net::IpAddr;
342 /// use env_reader::Reader;
343 ///
344 /// let mut reader = Reader::from_pairs([("BIND", "10.0.0.1"), ("PEER", "not-an-ip")]);
345 ///
346 /// assert_eq!(
347 /// reader.required_parse::<IpAddr>("BIND", "an IP address"),
348 /// Some("10.0.0.1".parse().unwrap())
349 /// );
350 /// assert_eq!(reader.required_parse::<IpAddr>("PEER", "an IP address"), None);
351 ///
352 /// let errors = reader.finish().unwrap_err();
353 /// assert!(errors.to_string().contains("PEER must be an IP address"));
354 /// ```
355 pub fn required_parse<T>(&mut self, name: &str, expected: &str) -> Option<T>
356 where
357 T: FromStr,
358 {
359 match self.raw(name) {
360 None => {
361 self.errors.push(Error::missing(name));
362 None
363 }
364 Some(value) => {
365 let value = value.to_string();
366 self.parse(name, &value, expected)
367 }
368 }
369 }
370
371 /// Any [`FromStr`] value that need not be set.
372 ///
373 /// Absent is `None` with no error; present-but-unparseable is `None`
374 /// with one.
375 ///
376 /// # Examples
377 ///
378 /// ```
379 /// use std::path::PathBuf;
380 /// use env_reader::Reader;
381 ///
382 /// let mut reader = Reader::from_pairs([("CA_BUNDLE", "/etc/ca.pem")]);
383 /// assert_eq!(
384 /// reader.optional_parse::<PathBuf>("CA_BUNDLE", "a path"),
385 /// Some(PathBuf::from("/etc/ca.pem"))
386 /// );
387 /// assert_eq!(reader.optional_parse::<PathBuf>("OTHER", "a path"), None);
388 /// assert!(reader.finish().is_ok());
389 /// ```
390 pub fn optional_parse<T>(&mut self, name: &str, expected: &str) -> Option<T>
391 where
392 T: FromStr,
393 {
394 let value = self.raw(name)?.to_string();
395 self.parse(name, &value, expected)
396 }
397
398 /// Any [`FromStr`] value with a fallback.
399 ///
400 /// As with [`Reader::integer_or`], an unparseable value is a recorded
401 /// error rather than a silent fallback.
402 ///
403 /// # Examples
404 ///
405 /// ```
406 /// use std::net::IpAddr;
407 /// use env_reader::Reader;
408 ///
409 /// let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
410 /// let bind: IpAddr = reader.parse_or("BIND", "an IP address", "127.0.0.1".parse().unwrap());
411 ///
412 /// assert_eq!(bind.to_string(), "127.0.0.1");
413 /// assert!(reader.finish().is_ok());
414 /// ```
415 pub fn parse_or<T>(&mut self, name: &str, expected: &str, default: T) -> T
416 where
417 T: FromStr,
418 {
419 match self.raw(name) {
420 None => default,
421 Some(value) => {
422 let value = value.to_string();
423 self.parse(name, &value, expected).unwrap_or(default)
424 }
425 }
426 }
427
428 // -- booleans ---------------------------------------------------------
429
430 /// A boolean with a fallback, read strictly by [`crate::parse_bool`].
431 ///
432 /// A value that is neither a true spelling nor a false one is a
433 /// recorded error, not a silent fallback.
434 ///
435 /// # Examples
436 ///
437 /// ```
438 /// use env_reader::Reader;
439 ///
440 /// let mut reader = Reader::from_pairs([("TRACING", "off"), ("CACHE", "maybe")]);
441 /// assert!(!reader.bool_or("TRACING", true));
442 /// assert!(reader.bool_or("METRICS", true), "absent takes the default");
443 /// assert!(reader.bool_or("CACHE", true), "unparseable takes it too, but records");
444 ///
445 /// let errors = reader.finish().unwrap_err();
446 /// assert_eq!(errors.len(), 1);
447 /// assert!(errors.to_string().contains("CACHE"));
448 /// ```
449 pub fn bool_or(&mut self, name: &str, default: bool) -> bool {
450 let Some(raw) = self.raw(name) else {
451 return default;
452 };
453 let raw = raw.to_string();
454
455 if let Some(parsed) = parse_bool(Some(&raw)) {
456 parsed
457 } else {
458 self.errors.push(Error::invalid(
459 name,
460 "true, 1, yes, on, false, 0, no or off",
461 raw,
462 ));
463 default
464 }
465 }
466
467 /// A boolean with a fallback, read leniently by
468 /// [`crate::parse_bool_lenient`]: anything not false-ish is true.
469 ///
470 /// Never records an error, because there is no value it cannot read.
471 /// See [`crate::parse_bool_lenient`] for when that is what you want and
472 /// when it is not.
473 ///
474 /// # Examples
475 ///
476 /// ```
477 /// use env_reader::Reader;
478 ///
479 /// let reader = Reader::from_pairs([("LEGACY_FLAG", "disabled")]);
480 /// assert!(reader.lenient_bool_or("LEGACY_FLAG", false), "not a false spelling");
481 /// ```
482 #[must_use]
483 pub fn lenient_bool_or(&self, name: &str, default: bool) -> bool {
484 parse_bool_lenient(self.raw(name)).unwrap_or(default)
485 }
486
487 // -- lists ------------------------------------------------------------
488
489 /// A comma-separated list, possibly empty.
490 ///
491 /// # Examples
492 ///
493 /// ```
494 /// use env_reader::Reader;
495 ///
496 /// let reader = Reader::from_pairs([("UPSTREAMS", "a, b")]);
497 /// assert_eq!(reader.list("UPSTREAMS"), ["a", "b"]);
498 /// assert!(reader.list("ABSENT").is_empty());
499 /// ```
500 #[must_use]
501 pub fn list(&self, name: &str) -> Vec<String> {
502 parse_csv(self.raw(name))
503 }
504
505 /// A comma-separated list that must be set and must have an element.
506 ///
507 /// # Examples
508 ///
509 /// ```
510 /// use env_reader::Reader;
511 ///
512 /// let mut reader = Reader::from_pairs([("BAD", " , ")]);
513 /// assert!(reader.required_list("ABSENT").is_empty());
514 /// assert!(reader.required_list("BAD").is_empty());
515 /// // One missing, one set to nothing but separators.
516 /// assert_eq!(reader.finish().unwrap_err().len(), 2);
517 /// ```
518 pub fn required_list(&mut self, name: &str) -> Vec<String> {
519 let Some(value) = self.raw(name) else {
520 self.errors.push(Error::missing(name));
521 return Vec::new();
522 };
523 let value = value.to_string();
524 let parsed = parse_csv(Some(&value));
525
526 if parsed.is_empty() {
527 self.errors.push(Error::invalid(
528 name,
529 "a comma-separated list with at least one value",
530 value,
531 ));
532 }
533 parsed
534 }
535
536 /// A comma-separated list, falling back to a default list when the
537 /// variable is absent.
538 ///
539 /// A variable set to only separators is a recorded error rather than an
540 /// empty list, because it means someone meant to configure something.
541 ///
542 /// # Examples
543 ///
544 /// ```
545 /// use env_reader::Reader;
546 ///
547 /// let mut reader = Reader::from_pairs([("BAD", " , ")]);
548 /// assert_eq!(reader.list_or("METHODS", "GET,HEAD"), ["GET", "HEAD"]);
549 /// assert!(reader.list_or("BAD", "x").is_empty());
550 /// assert_eq!(reader.finish().unwrap_err().len(), 1);
551 /// ```
552 pub fn list_or(&mut self, name: &str, default: &str) -> Vec<String> {
553 match self.raw(name) {
554 None => parse_csv(Some(default)),
555 Some(value) => {
556 let value = value.to_string();
557 let parsed = parse_csv(Some(&value));
558 if parsed.is_empty() {
559 self.errors.push(Error::invalid(
560 name,
561 "a comma-separated list with at least one value",
562 value,
563 ));
564 }
565 parsed
566 }
567 }
568 }
569
570 // -- fixed sets -------------------------------------------------------
571
572 /// A value that must be set and must be one of a fixed set.
573 ///
574 /// # Examples
575 ///
576 /// ```
577 /// use env_reader::Reader;
578 ///
579 /// const LEVELS: &[&str] = &["trace", "debug", "info", "warn", "error"];
580 ///
581 /// let mut reader = Reader::from_pairs([("LOG_LEVEL", "verbose")]);
582 /// assert_eq!(reader.required_one_of("LOG_LEVEL", LEVELS), None);
583 ///
584 /// let errors = reader.finish().unwrap_err();
585 /// assert!(errors.to_string().contains("one of trace, debug, info, warn, error"));
586 /// ```
587 pub fn required_one_of(&mut self, name: &str, accepted: &[&str]) -> Option<String> {
588 if self.raw(name).is_none() {
589 self.errors.push(Error::missing(name));
590 return None;
591 }
592 self.optional_one_of(name, accepted)
593 }
594
595 /// A value that, when set, must be one of a fixed set.
596 ///
597 /// # Examples
598 ///
599 /// ```
600 /// use env_reader::Reader;
601 ///
602 /// const LEVELS: &[&str] = &["trace", "debug", "info", "warn", "error"];
603 ///
604 /// let mut reader = Reader::from_pairs([("LOG_LEVEL", "debug")]);
605 /// assert_eq!(reader.optional_one_of("LOG_LEVEL", LEVELS).as_deref(), Some("debug"));
606 /// assert_eq!(reader.optional_one_of("OTHER", LEVELS), None);
607 /// assert!(reader.finish().is_ok());
608 /// ```
609 pub fn optional_one_of(&mut self, name: &str, accepted: &[&str]) -> Option<String> {
610 let value = self.raw(name)?.to_string();
611
612 if accepted.contains(&value.as_str()) {
613 Some(value)
614 } else {
615 self.errors.push(Error::invalid(
616 name,
617 format!("one of {}", accepted.join(", ")),
618 value,
619 ));
620 None
621 }
622 }
623
624 // -- UUIDs ------------------------------------------------------------
625
626 /// A required UUID.
627 ///
628 /// Returns [`uuid::Uuid::nil`] and records a problem when the variable
629 /// is absent or unparseable, so reading continues like every other
630 /// getter here.
631 ///
632 /// # Examples
633 ///
634 /// ```
635 /// use env_reader::Reader;
636 ///
637 /// let mut reader = Reader::from_pairs([
638 /// ("BATCH_ID", "00000000-0000-0000-0000-000000000001"),
639 /// ]);
640 /// assert_eq!(
641 /// reader.required_uuid("BATCH_ID").to_string(),
642 /// "00000000-0000-0000-0000-000000000001"
643 /// );
644 /// ```
645 #[cfg(feature = "uuid")]
646 pub fn required_uuid(&mut self, name: &str) -> uuid::Uuid {
647 self.required_parse(name, "a UUID")
648 .unwrap_or_else(uuid::Uuid::nil)
649 }
650
651 /// An optional UUID.
652 #[cfg(feature = "uuid")]
653 pub fn optional_uuid(&mut self, name: &str) -> Option<uuid::Uuid> {
654 self.optional_parse(name, "a UUID")
655 }
656
657 // -- problems the caller finds ----------------------------------------
658
659 /// Record that one variable held a value this crate cannot check.
660 ///
661 /// [`optional_one_of`](Reader::optional_one_of) covers a fixed set of
662 /// accepted strings, and [`optional_parse`](Reader::optional_parse)
663 /// covers anything with a [`FromStr`]. This is for what neither can: a
664 /// value that has to be resolved against something outside this crate,
665 /// where only the caller knows what "valid" means. The problem joins
666 /// the others, so a program that rejects a value here still reports
667 /// every *other* problem in the same breath.
668 ///
669 /// # Examples
670 ///
671 /// ```
672 /// use env_reader::Reader;
673 ///
674 /// let mut reader = Reader::from_pairs([("TENANT", "unknown-tenant")]);
675 ///
676 /// if let Some(value) = reader.optional_string("TENANT") {
677 /// if !["alpha", "beta"].contains(&value.as_str()) {
678 /// reader.invalid("TENANT", "a tenant this build knows about", value);
679 /// }
680 /// }
681 ///
682 /// let errors = reader.finish().unwrap_err();
683 /// assert!(errors.to_string().contains("a tenant this build knows about"));
684 /// ```
685 pub fn invalid(
686 &mut self,
687 name: impl Into<String>,
688 expected: impl Into<String>,
689 got: impl Into<String>,
690 ) {
691 self.errors.push(Error::invalid(name, expected, got));
692 }
693
694 /// Record a conflict between variables that are individually fine.
695 ///
696 /// # Examples
697 ///
698 /// ```
699 /// use env_reader::Reader;
700 ///
701 /// let mut reader = Reader::from_pairs([("QUEUE_NAME", "q"), ("TOPIC_NAME", "t")]);
702 /// if reader.is_set("QUEUE_NAME") && reader.is_set("TOPIC_NAME") {
703 /// reader.conflict("Cannot specify both QUEUE_NAME and TOPIC_NAME.");
704 /// }
705 /// assert!(reader.finish().is_err());
706 /// ```
707 pub fn conflict(&mut self, message: impl Into<String>) {
708 self.errors.push(Error::conflict(message));
709 }
710
711 // -- finishing --------------------------------------------------------
712
713 /// Whether anything has gone wrong so far.
714 ///
715 /// Lets a caller skip a cross-field check that would only produce noise
716 /// on top of an already-broken configuration.
717 ///
718 /// # Examples
719 ///
720 /// ```
721 /// use env_reader::Reader;
722 ///
723 /// let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
724 /// assert!(!reader.has_errors());
725 /// let _ = reader.required_string("SERVICE_NAME");
726 /// assert!(reader.has_errors());
727 /// ```
728 #[must_use]
729 pub fn has_errors(&self) -> bool {
730 !self.errors.is_empty()
731 }
732
733 /// How many problems have been found so far.
734 #[must_use]
735 pub fn error_count(&self) -> usize {
736 self.errors.len()
737 }
738
739 /// Finish reading.
740 ///
741 /// # Errors
742 ///
743 /// Returns every problem found, in the order it was found, when there
744 /// was at least one.
745 ///
746 /// # Examples
747 ///
748 /// ```
749 /// use env_reader::Reader;
750 ///
751 /// let mut reader = Reader::from_pairs([("SERVICE_NAME", "orders")]);
752 /// let _ = reader.required_string("SERVICE_NAME");
753 /// assert!(reader.finish().is_ok());
754 /// ```
755 pub fn finish(self) -> Result<(), Errors> {
756 if self.errors.is_empty() {
757 Ok(())
758 } else {
759 Err(Errors::new(self.errors))
760 }
761 }
762
763 /// Finish reading, returning `value` when nothing went wrong.
764 ///
765 /// The shape that lets a `Config` be built and validated in one
766 /// expression, so a caller cannot forget the `finish`.
767 ///
768 /// # Errors
769 ///
770 /// Returns every problem found, as [`Reader::finish`].
771 ///
772 /// # Examples
773 ///
774 /// ```
775 /// use env_reader::{Errors, Reader};
776 ///
777 /// #[derive(Debug)]
778 /// struct Config {
779 /// port: u16,
780 /// }
781 ///
782 /// fn load() -> Result<Config, Errors> {
783 /// let mut reader = Reader::from_pairs([("PORT", "8443")]);
784 /// let config = Config {
785 /// port: reader.integer_or("PORT", 8080),
786 /// };
787 /// reader.finish_with(config)
788 /// }
789 ///
790 /// assert_eq!(load()?.port, 8443);
791 /// # Ok::<(), Errors>(())
792 /// ```
793 pub fn finish_with<T>(self, value: T) -> Result<T, Errors> {
794 self.finish().map(|()| value)
795 }
796
797 /// Parse a value, recording a problem and returning `None` when it does
798 /// not parse.
799 fn parse<T: FromStr>(&mut self, name: &str, value: &str, expected: &str) -> Option<T> {
800 if let Ok(parsed) = value.parse::<T>() {
801 Some(parsed)
802 } else {
803 self.errors.push(Error::invalid(name, expected, value));
804 None
805 }
806 }
807}
808
809#[cfg(test)]
810mod tests {
811 use super::*;
812
813 #[test]
814 fn every_problem_is_reported_at_once() {
815 // The reason this crate is shaped the way it is.
816 let mut reader = Reader::from_pairs([("PORT", "two")]);
817 let _ = reader.required_string("SERVICE_NAME");
818 let _ = reader.required_string("REGION");
819 let _: u16 = reader.integer_or("PORT", 8080);
820
821 let errors = reader.finish().unwrap_err();
822 assert_eq!(errors.len(), 3);
823 assert_eq!(errors.to_string().lines().count(), 3);
824 }
825
826 #[test]
827 fn problems_come_back_in_the_order_they_were_found() {
828 let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
829 let _ = reader.required_string("FIRST");
830 let _ = reader.required_string("SECOND");
831
832 let errors = reader.finish().unwrap_err();
833 let names: Vec<_> = errors.iter().filter_map(Error::name).collect();
834 assert_eq!(names, ["FIRST", "SECOND"]);
835 }
836
837 #[test]
838 fn a_blank_integer_is_absent_rather_than_a_parse_failure() {
839 // The trap: `int("")` in the language this pattern usually comes
840 // from raises, so a blank variable becomes a crash rather than a
841 // default.
842 let mut reader = Reader::from_pairs([("A", " ")]);
843 assert_eq!(reader.optional_integer::<u32>("A"), None);
844 assert_eq!(reader.integer_or::<u32>("A", 7), 7);
845 assert!(reader.finish().is_ok());
846 }
847
848 #[test]
849 fn an_unparseable_value_does_not_silently_take_the_default() {
850 // A program quietly running on a default nobody chose is harder to
851 // diagnose than one that will not start.
852 let mut reader = Reader::from_pairs([("PORT", "eighty")]);
853 assert_eq!(reader.integer_or::<u16>("PORT", 8080), 8080);
854 assert!(reader.has_errors());
855 }
856
857 #[test]
858 fn a_failed_getter_still_returns_something_usable() {
859 // What lets a caller read a whole configuration without `?` after
860 // every line.
861 let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
862 assert_eq!(reader.required_string("A"), "");
863 assert_eq!(reader.required_integer::<u16>("B"), 0);
864 assert!(reader.required_list("C").is_empty());
865 assert_eq!(reader.error_count(), 3);
866 }
867
868 #[test]
869 fn any_from_str_type_can_be_read() {
870 use std::net::{IpAddr, SocketAddr};
871 use std::path::PathBuf;
872
873 let mut reader = Reader::from_pairs([
874 ("BIND", "10.0.0.1"),
875 ("PEER", "10.0.0.2:9000"),
876 ("BUNDLE", "/etc/ca.pem"),
877 ]);
878
879 assert_eq!(
880 reader.required_parse::<IpAddr>("BIND", "an IP address"),
881 Some("10.0.0.1".parse().unwrap())
882 );
883 assert_eq!(
884 reader.required_parse::<SocketAddr>("PEER", "a socket address"),
885 Some("10.0.0.2:9000".parse().unwrap())
886 );
887 assert_eq!(
888 reader.optional_parse::<PathBuf>("BUNDLE", "a path"),
889 Some(PathBuf::from("/etc/ca.pem"))
890 );
891 assert!(reader.finish().is_ok());
892 }
893
894 #[test]
895 fn the_expected_phrase_reaches_the_message() {
896 // The whole difference between a message somebody can act on and
897 // one they cannot.
898 use std::net::IpAddr;
899
900 let mut reader = Reader::from_pairs([("BIND", "localhost")]);
901 assert_eq!(reader.required_parse::<IpAddr>("BIND", "an IP address"), None);
902
903 let errors = reader.finish().unwrap_err();
904 assert_eq!(
905 errors.to_string(),
906 r#"invalid configuration: BIND must be an IP address, got "localhost""#
907 );
908 }
909
910 #[test]
911 fn a_strict_boolean_records_what_it_cannot_read() {
912 let mut reader = Reader::from_pairs([("A", "on"), ("B", "disabled")]);
913 assert!(reader.bool_or("A", false));
914 assert!(reader.bool_or("B", true), "the default, having recorded");
915 assert!(reader.bool_or("C", true), "absent takes the default silently");
916
917 let errors = reader.finish().unwrap_err();
918 assert_eq!(errors.len(), 1);
919 assert_eq!(errors.iter().next().and_then(Error::name), Some("B"));
920 }
921
922 #[test]
923 fn a_lenient_boolean_records_nothing() {
924 let mut reader = Reader::from_pairs([("B", "disabled")]);
925 assert!(reader.lenient_bool_or("B", false));
926 assert!(!reader.lenient_bool_or("C", false));
927 let _ = reader.bool_or("ABSENT", true);
928 assert!(reader.finish().is_ok());
929 }
930
931 #[test]
932 fn a_positive_integer_rejects_zero_but_not_absence() {
933 let mut reader = Reader::from_pairs([("A", "0")]);
934 assert_eq!(reader.optional_positive_integer::<u32>("A"), None);
935 assert_eq!(reader.optional_positive_integer::<u32>("ABSENT"), None);
936 assert_eq!(reader.error_count(), 1, "only the configured zero");
937 }
938
939 #[test]
940 fn a_fixed_set_lists_what_it_accepted() {
941 const LEVELS: &[&str] = &["info", "warn"];
942
943 let mut reader = Reader::from_pairs([("L", "verbose")]);
944 assert_eq!(reader.optional_one_of("L", LEVELS), None);
945 assert_eq!(reader.required_one_of("M", LEVELS), None);
946
947 let text = reader.finish().unwrap_err().to_string();
948 assert!(text.contains("one of info, warn"), "{text}");
949 assert!(text.contains("missing required configuration: M"), "{text}");
950 }
951
952 #[test]
953 fn a_required_fixed_set_reports_missing_once_not_twice() {
954 // The trap in delegating to the optional form: an absent variable
955 // must not be both "missing" and "not one of".
956 const LEVELS: &[&str] = &["info"];
957
958 let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
959 assert_eq!(reader.required_one_of("L", LEVELS), None);
960 assert_eq!(reader.error_count(), 1);
961 }
962
963 #[test]
964 fn a_list_of_only_separators_is_a_problem_not_an_empty_list() {
965 // It means someone meant to configure something.
966 let mut reader = Reader::from_pairs([("A", " , ")]);
967 assert!(reader.list_or("A", "x").is_empty());
968 assert!(reader.list("A").is_empty(), "the plain reader has no opinion");
969 assert_eq!(reader.error_count(), 1);
970 }
971
972 #[test]
973 fn finish_with_carries_a_value_through() {
974 let mut reader = Reader::from_pairs([("PORT", "8443")]);
975 let port = reader.integer_or::<u16>("PORT", 8080);
976 assert_eq!(reader.finish_with(port).unwrap(), 8443);
977
978 let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
979 let _ = reader.required_string("A");
980 assert!(reader.finish_with(1).is_err());
981 }
982
983 #[test]
984 fn blank_is_absent_everywhere_it_matters() {
985 let mut reader = Reader::from_pairs([
986 ("S", " "),
987 ("I", "\t"),
988 ("B", " "),
989 ("L", ""),
990 ("K", " "),
991 ]);
992
993 assert_eq!(reader.optional_string("S"), None);
994 assert_eq!(reader.optional_integer::<u32>("I"), None);
995 assert!(!reader.lenient_bool_or("B", false));
996 assert!(reader.list("L").is_empty());
997 assert!(reader.optional_secret("K").is_none());
998 assert!(!reader.is_set("S"));
999 assert!(reader.finish().is_ok(), "none of that is a problem");
1000 }
1001
1002 #[test]
1003 fn a_reader_can_come_from_the_process_environment() {
1004 // Constructing it is the whole assertion: this is the one path that
1005 // touches global state, and it must not panic on whatever is there.
1006 let reader = Reader::from_env();
1007 assert!(!reader.has_errors());
1008 }
1009
1010 #[cfg(feature = "uuid")]
1011 #[test]
1012 fn a_uuid_is_read_and_a_bad_one_is_recorded() {
1013 let mut reader = Reader::from_pairs([
1014 ("GOOD", "00000000-0000-0000-0000-000000000001"),
1015 ("BAD", "not-a-uuid"),
1016 ]);
1017
1018 assert_eq!(
1019 reader.required_uuid("GOOD").to_string(),
1020 "00000000-0000-0000-0000-000000000001"
1021 );
1022 assert!(reader.required_uuid("BAD").is_nil());
1023 assert!(reader.optional_uuid("ABSENT").is_none());
1024
1025 let text = reader.finish().unwrap_err().to_string();
1026 assert!(text.contains("BAD must be a UUID"), "{text}");
1027 }
1028}