Merge #991: Config overhaul: use an explicit section for metadata

287e484 feat!: [#958] improve metadata in config files (Jose Celano)

Pull request description:

  The metadata section in the configuration file is changed:

  TOML:

  ```toml
  [metadata]
  app = "torrust-tracker"
  purpose = "configuration"
  schema_version = "2.0.0"
  ```

  JSON:

  ```json
  {
    "metadata": {
      "app": "torrust-tracker",
      "purpose": "configuration",
      "version": "2.0.0"
    }
  }
  ```

  - `app`: the application this config file is used for.
  - `purpose`: the purpose of the file containing these metadata.
  - `schema_version`: the schema version for the file being parsed.

ACKs for top commit:
  josecelano:
    ACK 287e484

Tree-SHA512: 86ee59ddb7a76fee24289d1ea801e7d7e492f5c265d2b6569b0aecc368f3d97d3c7463cf0ebf9fafe16827e8008409c57a994608add2afee97514adf91203746

packages/configuration/src/lib.rs

@@ -4,7 +4,7 @@
 //! Torrust Tracker, which is a `BitTorrent` tracker server.
 //!
 //! The current version for configuration is [`v2`].
-pub mod v2;
+pub mod v2_0_0;
 pub mod validator;
 
 use std::collections::HashMap;
@@ -35,67 +35,100 @@ const ENV_VAR_CONFIG_TOML: &str = "TORRUST_TRACKER_CONFIG_TOML";
 /// The `tracker.toml` file location.
 pub const ENV_VAR_CONFIG_TOML_PATH: &str = "TORRUST_TRACKER_CONFIG_TOML_PATH";
 
-pub type Configuration = v2::Configuration;
-pub type Core = v2::core::Core;
-pub type HealthCheckApi = v2::health_check_api::HealthCheckApi;
-pub type HttpApi = v2::tracker_api::HttpApi;
-pub type HttpTracker = v2::http_tracker::HttpTracker;
-pub type UdpTracker = v2::udp_tracker::UdpTracker;
-pub type Database = v2::database::Database;
-pub type Driver = v2::database::Driver;
-pub type Threshold = v2::logging::Threshold;
+pub type Configuration = v2_0_0::Configuration;
+pub type Core = v2_0_0::core::Core;
+pub type HealthCheckApi = v2_0_0::health_check_api::HealthCheckApi;
+pub type HttpApi = v2_0_0::tracker_api::HttpApi;
+pub type HttpTracker = v2_0_0::http_tracker::HttpTracker;
+pub type UdpTracker = v2_0_0::udp_tracker::UdpTracker;
+pub type Database = v2_0_0::database::Database;
+pub type Driver = v2_0_0::database::Driver;
+pub type Threshold = v2_0_0::logging::Threshold;
 
 pub type AccessTokens = HashMap<String, String>;
 
-pub const LATEST_VERSION: &str = "2";
+pub const LATEST_VERSION: &str = "2.0.0";
 
 /// Info about the configuration specification.
 #[derive(Serialize, Deserialize, PartialEq, Eq, Debug, Display, Clone)]
+#[display(fmt = "Metadata(app: {app}, purpose: {purpose}, schema_version: {schema_version})")]
 pub struct Metadata {
-    #[serde(default = "Metadata::default_version")]
+    /// The application this configuration is valid for.
+    #[serde(default = "Metadata::default_app")]
+    app: App,
+
+    /// The purpose of this parsed file.
+    #[serde(default = "Metadata::default_purpose")]
+    purpose: Purpose,
+
+    /// The schema version for the configuration.
+    #[serde(default = "Metadata::default_schema_version")]
     #[serde(flatten)]
-    version: Version,
+    schema_version: Version,
 }
 
 impl Default for Metadata {
     fn default() -> Self {
         Self {
-            version: Self::default_version(),
+            app: Self::default_app(),
+            purpose: Self::default_purpose(),
+            schema_version: Self::default_schema_version(),
         }
     }
 }
 
 impl Metadata {
-    fn default_version() -> Version {
+    fn default_app() -> App {
+        App::TorrustTracker
+    }
+
+    fn default_purpose() -> Purpose {
+        Purpose::Configuration
+    }
+
+    fn default_schema_version() -> Version {
         Version::latest()
     }
 }
 
+#[derive(Serialize, Deserialize, PartialEq, Eq, Debug, Display, Clone)]
+#[serde(rename_all = "kebab-case")]
+pub enum App {
+    TorrustTracker,
+}
+
+#[derive(Serialize, Deserialize, PartialEq, Eq, Debug, Display, Clone)]
+#[serde(rename_all = "lowercase")]
+pub enum Purpose {
+    Configuration,
+}
+
 /// The configuration version.
 #[derive(Serialize, Deserialize, PartialEq, Eq, Debug, Display, Clone)]
+#[serde(rename_all = "lowercase")]
 pub struct Version {
     #[serde(default = "Version::default_semver")]
-    version: String,
+    schema_version: String,
 }
 
 impl Default for Version {
     fn default() -> Self {
         Self {
-            version: Self::default_semver(),
+            schema_version: Self::default_semver(),
         }
     }
 }
 
 impl Version {
     fn new(semver: &str) -> Self {
         Self {
-            version: semver.to_owned(),
+            schema_version: semver.to_owned(),
         }
     }
 
     fn latest() -> Self {
         Self {
-            version: LATEST_VERSION.to_string(),
+            schema_version: LATEST_VERSION.to_string(),
         }
     }
 

packages/configuration/src/v2/core.rs → packages/configuration/src/v2_0_0/core.rs

@@ -2,18 +2,18 @@ use derive_more::{Constructor, Display};
 use serde::{Deserialize, Serialize};
 
 use super::network::Network;
-use crate::v2::database::Database;
+use crate::v2_0_0::database::Database;
 use crate::validator::{SemanticValidationError, Validator};
 use crate::{AnnouncePolicy, TrackerPolicy};
 
 #[allow(clippy::struct_excessive_bools)]
 #[derive(Serialize, Deserialize, PartialEq, Eq, Debug, Clone)]
 pub struct Core {
-    // Announce policy configuration.
+    /// Announce policy configuration.
     #[serde(default = "Core::default_announce_policy")]
     pub announce_policy: AnnouncePolicy,
 
-    // Database configuration.
+    /// Database configuration.
     #[serde(default = "Core::default_database")]
     pub database: Database,
 
@@ -22,23 +22,23 @@ pub struct Core {
     #[serde(default = "Core::default_inactive_peer_cleanup_interval")]
     pub inactive_peer_cleanup_interval: u64,
 
-    // When `true` only approved torrents can be announced in the tracker.
+    /// When `true` only approved torrents can be announced in the tracker.
     #[serde(default = "Core::default_listed")]
     pub listed: bool,
 
-    // Network configuration.
+    /// Network configuration.
     #[serde(default = "Core::default_network")]
     pub net: Network,
 
-    // When `true` clients require a key to connect and use the tracker.
+    /// When `true` clients require a key to connect and use the tracker.
     #[serde(default = "Core::default_private")]
     pub private: bool,
 
-    // Configuration specific when the tracker is running in private mode.
+    /// Configuration specific when the tracker is running in private mode.
     #[serde(default = "Core::default_private_mode")]
     pub private_mode: Option<PrivateMode>,
 
-    // Tracker policy configuration.
+    /// Tracker policy configuration.
     #[serde(default = "Core::default_tracker_policy")]
     pub tracker_policy: TrackerPolicy,
 

packages/configuration/src/v2/mod.rs → packages/configuration/src/v2_0_0/mod.rs

@@ -255,7 +255,7 @@ use crate::validator::{SemanticValidationError, Validator};
 use crate::{Error, Info, Metadata, Version};
 
 /// This configuration version
-const VERSION_2: &str = "2";
+const VERSION_2_0_0: &str = "2.0.0";
 
 /// Prefix for env vars that overwrite configuration options.
 const CONFIG_OVERRIDE_PREFIX: &str = "TORRUST_TRACKER_CONFIG_OVERRIDE_";
@@ -267,7 +267,6 @@ const CONFIG_OVERRIDE_SEPARATOR: &str = "__";
 #[derive(Serialize, Deserialize, PartialEq, Eq, Debug, Default, Clone)]
 pub struct Configuration {
     /// Configuration metadata.
-    #[serde(flatten)]
     pub metadata: Metadata,
 
     /// Logging configuration
@@ -335,9 +334,9 @@ impl Configuration {
 
         let config: Configuration = figment.extract()?;
 
-        if config.metadata.version != Version::new(VERSION_2) {
+        if config.metadata.schema_version != Version::new(VERSION_2_0_0) {
             return Err(Error::UnsupportedVersion {
-                version: config.metadata.version,
+                version: config.metadata.schema_version,
             });
         }
 
@@ -406,12 +405,15 @@ mod tests {
 
     use std::net::{IpAddr, Ipv4Addr};
 
-    use crate::v2::Configuration;
+    use crate::v2_0_0::Configuration;
     use crate::Info;
 
     #[cfg(test)]
     fn default_config_toml() -> String {
-        let config = r#"version = "2"
+        let config = r#"[metadata]
+                                app = "torrust-tracker"
+                                purpose = "configuration"
+                                schema_version = "2.0.0"
 
                                 [logging]
                                 threshold = "info"

packages/configuration/src/v2/tracker_api.rs → packages/configuration/src/v2_0_0/tracker_api.rs

@@ -71,7 +71,7 @@ impl HttpApi {
 
 #[cfg(test)]
 mod tests {
-    use crate::v2::tracker_api::HttpApi;
+    use crate::v2_0_0::tracker_api::HttpApi;
 
     #[test]
     fn http_api_configuration_should_check_if_it_contains_a_token() {

share/default/config/tracker.container.mysql.toml

@@ -1,4 +1,7 @@
-version = "2"
+[metadata]
+app = "torrust-tracker"
+purpose = "configuration"
+schema_version = "2.0.0"
 
 [core.database]
 driver = "mysql"

share/default/config/tracker.container.sqlite3.toml

@@ -1,4 +1,7 @@
-version = "2"
+[metadata]
+app = "torrust-tracker"
+purpose = "configuration"
+schema_version = "2.0.0"
 
 [core.database]
 path = "/var/lib/torrust/tracker/database/sqlite3.db"

share/default/config/tracker.development.sqlite3.toml

@@ -1,4 +1,7 @@
-version = "2"
+[metadata]
+app = "torrust-tracker"
+purpose = "configuration"
+schema_version = "2.0.0"
 
 [[udp_trackers]]
 bind_address = "0.0.0.0:6969"

share/default/config/tracker.e2e.container.sqlite3.toml

@@ -1,4 +1,7 @@
-version = "2"
+[metadata]
+app = "torrust-tracker"
+purpose = "configuration"
+schema_version = "2.0.0"
 
 [core.database]
 path = "/var/lib/torrust/tracker/database/sqlite3.db"

share/default/config/tracker.udp.benchmarking.toml

@@ -1,4 +1,7 @@
-version = "2"
+[metadata]
+app = "torrust-tracker"
+purpose = "configuration"
+schema_version = "2.0.0"
 
 [logging]
 threshold = "error"

src/bootstrap/config.rs

@@ -24,7 +24,7 @@ pub const DEFAULT_PATH_CONFIG: &str = "./share/default/config/tracker.developmen
 #[must_use]
 pub fn initialize_configuration() -> Configuration {
     let info = Info::new(DEFAULT_PATH_CONFIG.to_string()).expect("info to load configuration is not valid");
-    Configuration::load(&info).expect("configuration should be loaded from provided info")
+    Configuration::load(&info).expect("error loading configuration from sources")
 }
 
 #[cfg(test)]

src/core/mod.rs

@@ -459,7 +459,7 @@ use derive_more::Constructor;
 use error::PeerKeyError;
 use tokio::sync::mpsc::error::SendError;
 use torrust_tracker_clock::clock::Time;
-use torrust_tracker_configuration::v2::database;
+use torrust_tracker_configuration::v2_0_0::database;
 use torrust_tracker_configuration::{AnnouncePolicy, Core, TORRENT_PEERS_LIMIT};
 use torrust_tracker_located_error::Located;
 use torrust_tracker_primitives::info_hash::InfoHash;
@@ -1841,7 +1841,7 @@ mod tests {
                         use std::time::Duration;
 
                         use torrust_tracker_clock::clock::Time;
-                        use torrust_tracker_configuration::v2::core::PrivateMode;
+                        use torrust_tracker_configuration::v2_0_0::core::PrivateMode;
 
                         use crate::core::auth::Key;
                         use crate::core::tests::the_tracker::private_tracker;
@@ -1893,7 +1893,7 @@ mod tests {
                         use std::time::Duration;
 
                         use torrust_tracker_clock::clock::Time;
-                        use torrust_tracker_configuration::v2::core::PrivateMode;
+                        use torrust_tracker_configuration::v2_0_0::core::PrivateMode;
 
                         use crate::core::auth::Key;
                         use crate::core::tests::the_tracker::private_tracker;