feat!: [#958] improve metadata in config files

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 applications 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.

Author: josecelano

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.rspackages/configuration/src/v2/core.rs renamed to 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/database.rs …ges/configuration/src/v2_0_0/database.rspackages/configuration/src/v2/database.rs renamed to packages/configuration/src/v2_0_0/database.rs packages/configuration/src/v2/database.rs renamed to packages/configuration/src/v2_0_0/database.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"

…configuration/src/v2/health_check_api.rs …iguration/src/v2_0_0/health_check_api.rspackages/configuration/src/v2/health_check_api.rs renamed to packages/configuration/src/v2_0_0/health_check_api.rs packages/configuration/src/v2/health_check_api.rs renamed to packages/configuration/src/v2_0_0/health_check_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() {