Add AsyncSource trait

This patch adds the AsyncSource trait, the interface for providing async
source functionality for this crate.

Signed-off-by: Matthias Beyer <mail@beyermatthias.de>
Reviewed-by: Matthias Beyer <mail@beyermatthias.de>

3 files changed, 43 insertions, 0 deletions

diff --git a/Cargo.toml b/Cargo.toml
index 35b1ab3..5d0db61 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -23,6 +23,7 @@ ini = ["rust-ini"]
 json5 = ["json5_rs"]
 
 [dependencies]
+async-trait = "0.1.50"
 lazy_static = "1.0"
 serde = "1.0.8"
 nom = "6"
diff --git a/src/lib.rs b/src/lib.rs
index 60d7012..00526c4 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -69,6 +69,7 @@ pub use crate::config::Config;
 pub use crate::env::Environment;
 pub use crate::error::ConfigError;
 pub use crate::file::{File, FileFormat, FileSourceFile, FileSourceString};
+pub use crate::source::AsyncSource;
 pub use crate::source::Source;
 pub use crate::value::Value;
 pub use crate::value::ValueKind;
diff --git a/src/source.rs b/src/source.rs
index 647d948..8711e77 100644
--- a/src/source.rs
+++ b/src/source.rs
@@ -2,6 +2,8 @@ use std::collections::HashMap;
 use std::fmt::Debug;
 use std::str::FromStr;
 
+use async_trait::async_trait;
+
 use crate::error::*;
 use crate::path;
 use crate::value::{Value, ValueKind};
@@ -34,6 +36,45 @@ fn set_value(cache: &mut Value, key: &String, value: &Value) {
     }
 }
 
+/// Describes a generic _source_ of configuration properties capable of using an async runtime.
+///
+/// At the moment this library does not implement it, although it allows using its implementations
+/// within builders.  Due to the scattered landscape of asynchronous runtimes, it is impossible to
+/// cater to all needs with one implementation.  Also, this trait might be most useful with remote
+/// configuration sources, reachable via the network, probably using HTTP protocol.  Numerous HTTP
+/// libraries exist, making it even harder to find one implementation that rules them all.
+///
+/// For those reasons, it is left to other crates to implement runtime-specific or proprietary
+/// details.
+///
+/// It is advised to use `async_trait` crate while implementing this trait.
+///
+/// See examples for sample implementation.
+#[async_trait]
+pub trait AsyncSource: Debug + Sync {
+    // Sync is supertrait due to https://docs.rs/async-trait/0.1.50/async_trait/index.html#dyn-traits
+
+    /// Collects all configuration properties available from this source and return
+    /// a HashMap as an async operations.
+    async fn collect(&self) -> Result<HashMap<String, Value>>;
+
+    /// Collects all configuration properties to a provided cache.
+    async fn collect_to(&self, cache: &mut Value) -> Result<()> {
+        self.collect()
+            .await?
+            .iter()
+            .for_each(|(key, val)| set_value(cache, key, val));
+
+        Ok(())
+    }
+}
+
+impl Clone for Box<dyn AsyncSource + Send + Sync> {
+    fn clone(&self) -> Self {
+        self.to_owned()
+    }
+}
+
 impl Clone for Box<dyn Source + Send + Sync> {
     fn clone(&self) -> Box<dyn Source + Send + Sync> {
         self.clone_into_box()