reinhardt_conf/

settings.rs

//! # Settings Module
//!
//! Django-inspired settings system for Reinhardt projects.
//! This module provides configuration management for Reinhardt applications.

pub mod advanced;
pub mod builder;
pub mod cache;
/// Trait for composed settings structs generated by the `#[settings(...)]` macro.
pub mod composed;
pub mod contacts;
pub mod core_settings;
pub mod cors;
pub mod email;
pub mod env;
pub mod env_loader;
pub mod env_parser;
pub mod fragment;
pub mod i18n;
pub mod interpolation;
pub mod logging;
pub mod media;
pub(crate) mod merge;
/// OpenAPI documentation endpoint configuration.
pub mod openapi;
/// Field-level policy types for settings fragments.
pub mod policy;
pub mod prelude;
pub mod profile;
pub mod secret_types;
pub mod security;
pub mod session;
pub mod sources;
pub mod static_files;
pub mod template_settings;
pub mod typed_deserializer;
pub mod validation;

// Dynamic settings (async feature required)
#[cfg(feature = "async")]
pub mod dynamic;

#[cfg(feature = "async")]
pub mod backends;

/// Secret management with provider-based storage and rotation support.
#[cfg(feature = "async")]
pub mod secrets;

#[cfg(feature = "encryption")]
pub mod encryption;

#[cfg(feature = "async")]
pub mod audit;

#[cfg(feature = "hot-reload")]
pub mod hot_reload;

/// Additional application-level configuration types.
pub mod config;
/// Database connection configuration types and helpers.
pub mod database_config;
/// Settings documentation and introspection utilities.
pub mod docs;
/// Test utilities for settings configuration.
pub mod testing;

use core_settings::CoreSettings;
use fragment::HasSettings;
use reinhardt_utils::staticfiles::storage::StaticFilesConfig;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::path::PathBuf;

/// Contact information for administrators and managers
///
/// Used for error notifications, broken link notifications, etc.
///
/// # Examples
///
/// ```
/// use reinhardt_conf::settings::Contact;
///
/// let admin = Contact::new("John Doe", "john@example.com");
/// assert_eq!(admin.name, "John Doe");
/// assert_eq!(admin.email, "john@example.com");
/// ```
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
pub struct Contact {
	/// Person's name
	pub name: String,
	/// Email address
	pub email: String,
}

impl Contact {
	/// Create a new contact
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::Contact;
	///
	/// let contact = Contact::new("Alice Smith", "alice@example.com");
	/// assert_eq!(contact.name, "Alice Smith");
	/// assert_eq!(contact.email, "alice@example.com");
	/// ```
	pub fn new(name: impl Into<String>, email: impl Into<String>) -> Self {
		Self {
			name: name.into(),
			email: email.into(),
		}
	}
}

// Re-export from advanced module
#[allow(deprecated)]
pub use advanced::{
	AdvancedSettings, CacheSettings, CorsSettings, DatabaseSettings as AdvancedDatabaseSettings,
	EmailSettings, LoggingSettings, MediaSettings, SessionSettings, SettingsError, StaticSettings,
};

/// Main settings structure for a Reinhardt project
///
/// **Deprecated since 0.1.0-rc.16**: Use [`CoreSettings`] fragment with
/// `ProjectSettings` instead. This struct is retained as a migration bridge
/// and implements `HasCoreSettings` so existing code can be gradually
/// moved to the composable settings system.
#[deprecated(
	since = "0.1.0-rc.16",
	note = "use CoreSettings fragment with ProjectSettings instead"
)]
#[non_exhaustive]
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Settings {
	/// Core settings (flattened for backward-compatible TOML deserialization).
	#[serde(flatten)]
	pub core: CoreSettings,

	/// Template engine configurations.
	///
	/// **Note:** Currently not consumed by the framework. Reserved for future
	/// template engine integration. Setting this value has no effect on framework
	/// behavior.
	pub templates: Vec<TemplateConfig>,

	/// Static files URL prefix.
	pub static_url: String,

	/// Static files root directory.
	pub static_root: Option<PathBuf>,

	/// Additional static files directories (STATICFILES_DIRS).
	pub staticfiles_dirs: Vec<PathBuf>,

	/// Media files URL prefix.
	pub media_url: String,

	/// Media files root directory.
	pub media_root: Option<PathBuf>,

	/// Language code for internationalization.
	///
	/// **Note:** Currently not consumed by the framework. Reserved for future
	/// i18n implementation. Setting this value has no effect on framework behavior.
	pub language_code: String,

	/// Time zone for datetime handling.
	///
	/// **Note:** Currently not consumed by the framework. Reserved for future
	/// timezone support implementation. Setting this value has no effect on
	/// framework behavior.
	pub time_zone: String,

	/// Enable internationalization.
	///
	/// **Note:** Currently not consumed by the framework. Reserved for future
	/// i18n implementation. Setting this value has no effect on framework behavior.
	pub use_i18n: bool,

	/// Use timezone-aware datetimes.
	///
	/// **Note:** Currently not consumed by the framework. Reserved for future
	/// timezone support implementation. Setting this value has no effect on
	/// framework behavior.
	pub use_tz: bool,

	/// Default auto field type for models.
	///
	/// **Note:** Currently not consumed by the framework. Reserved for future
	/// auto field configuration. Setting this value has no effect on framework
	/// behavior.
	pub default_auto_field: String,

	/// List of administrators who receive error notifications.
	/// Django equivalent: ADMINS = [('name', 'email'), ...]
	pub admins: Vec<Contact>,

	/// List of managers who receive broken link notifications, etc.
	/// Django equivalent: MANAGERS = [('name', 'email'), ...]
	pub managers: Vec<Contact>,
}

#[allow(deprecated)] // Internal: Settings is deprecated but we still need to implement methods
impl Settings {
	/// Create a new Settings instance with default values
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::Settings;
	/// use std::path::PathBuf;
	///
	/// #[allow(deprecated)]
	/// let settings = Settings::new(
	///     PathBuf::from("/app"),
	///     "my-secret-key-12345".to_string()
	/// );
	///
	/// assert_eq!(settings.core.base_dir, PathBuf::from("/app"));
	/// assert_eq!(settings.core.secret_key, "my-secret-key-12345");
	/// assert!(settings.core.debug);
	/// assert_eq!(settings.time_zone, "UTC");
	/// assert!(settings.core.installed_apps.is_empty());
	/// ```
	pub fn new(base_dir: PathBuf, secret_key: String) -> Self {
		Self {
			core: CoreSettings {
				base_dir,
				secret_key,
				debug: true,
				..Default::default()
			},
			templates: vec![TemplateConfig::default()],
			static_url: "/static/".to_string(),
			static_root: None,
			staticfiles_dirs: vec![],
			media_url: "/media/".to_string(),
			media_root: None,
			language_code: "en-us".to_string(),
			time_zone: "UTC".to_string(),
			use_i18n: true,
			use_tz: true,
			default_auto_field: "reinhardt.db.models.BigAutoField".to_string(),
			admins: vec![],
			managers: vec![],
		}
	}

	/// Add an installed app
	///
	/// **Deprecated since 0.2.0**: Use `installed_apps!` macro with `ApplicationBuilder` instead.
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::Settings;
	///
	/// #[allow(deprecated)]
	/// let mut settings = Settings::default();
	/// #[allow(deprecated)]
	/// {
	///     let initial_count = settings.core.installed_apps.len();
	///     settings.add_app("myapp");
	///
	///     assert_eq!(settings.core.installed_apps.len(), initial_count + 1);
	///     assert!(settings.core.installed_apps.contains(&"myapp".to_string()));
	/// }
	/// ```
	#[deprecated(
		since = "0.1.0-rc.16",
		note = "Use `installed_apps!` macro with `ApplicationBuilder` instead"
	)]
	pub fn add_app(&mut self, app: impl Into<String>) {
		self.core.installed_apps.push(app.into());
	}

	/// Create settings with a compile-time validated app list
	///
	/// This method accepts a function that returns `Vec<String>` generated by the
	/// `installed_apps!` macro, providing compile-time validation of app names.
	///
	/// **Deprecated since 0.2.0**: Use `installed_apps!` macro with `ApplicationBuilder` instead.
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::Settings;
	///
	/// #[allow(deprecated)]
	/// let settings = Settings::default()
	///     .with_validated_apps(|| vec![
	///         "reinhardt.contrib.admin".to_string(),
	///         "myapp".to_string(),
	///     ]);
	///
	/// #[allow(deprecated)]
	/// {
	///     assert_eq!(settings.core.installed_apps.len(), 2);
	///     assert!(settings.core.installed_apps.contains(&"myapp".to_string()));
	/// }
	/// ```
	#[deprecated(
		since = "0.1.0-rc.16",
		note = "Use `installed_apps!` macro with `ApplicationBuilder` instead"
	)]
	pub fn with_validated_apps<F>(mut self, app_provider: F) -> Self
	where
		F: FnOnce() -> Vec<String>,
	{
		self.core.installed_apps = app_provider();
		self
	}

	/// Add an administrator
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::{Settings, Contact};
	///
	/// #[allow(deprecated)]
	/// let mut settings = Settings::default();
	/// settings.add_admin("John Doe", "john@example.com");
	///
	/// assert_eq!(settings.admins.len(), 1);
	/// assert_eq!(settings.admins[0].name, "John Doe");
	/// assert_eq!(settings.admins[0].email, "john@example.com");
	/// ```
	pub fn add_admin(&mut self, name: impl Into<String>, email: impl Into<String>) {
		self.admins.push(Contact::new(name, email));
	}

	/// Add a manager
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::{Settings, Contact};
	///
	/// #[allow(deprecated)]
	/// let mut settings = Settings::default();
	/// settings.add_manager("Jane Smith", "jane@example.com");
	///
	/// assert_eq!(settings.managers.len(), 1);
	/// assert_eq!(settings.managers[0].name, "Jane Smith");
	/// assert_eq!(settings.managers[0].email, "jane@example.com");
	/// ```
	pub fn add_manager(&mut self, name: impl Into<String>, email: impl Into<String>) {
		self.managers.push(Contact::new(name, email));
	}

	/// Set managers to be the same as administrators
	///
	/// This is a common pattern in Django projects where MANAGERS = ADMINS
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::Settings;
	///
	/// #[allow(deprecated)]
	/// let mut settings = Settings::default();
	/// settings.add_admin("John Doe", "john@example.com");
	/// settings.add_admin("Jane Smith", "jane@example.com");
	/// settings.managers_from_admins();
	///
	/// assert_eq!(settings.managers.len(), 2);
	/// assert_eq!(settings.managers, settings.admins);
	/// ```
	pub fn managers_from_admins(&mut self) {
		self.managers = self.admins.clone();
	}

	/// Set administrators with a fluent API
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::{Settings, Contact};
	///
	/// #[allow(deprecated)]
	/// let settings = Settings::default()
	///     .with_admins(vec![
	///         Contact::new("John Doe", "john@example.com"),
	///         Contact::new("Jane Smith", "jane@example.com"),
	///     ]);
	///
	/// assert_eq!(settings.admins.len(), 2);
	/// ```
	pub fn with_admins(mut self, admins: Vec<Contact>) -> Self {
		self.admins = admins;
		self
	}

	/// Set managers with a fluent API
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::{Settings, Contact};
	///
	/// #[allow(deprecated)]
	/// let settings = Settings::default()
	///     .with_managers(vec![
	///         Contact::new("Alice Brown", "alice@example.com"),
	///     ]);
	///
	/// assert_eq!(settings.managers.len(), 1);
	/// ```
	pub fn with_managers(mut self, managers: Vec<Contact>) -> Self {
		self.managers = managers;
		self
	}

	/// Convert Settings to `StaticFilesConfig`
	///
	/// This method extracts static files related configuration from Settings
	/// and creates a `StaticFilesConfig` instance suitable for use with `CollectStaticCommand`.
	///
	/// # Returns
	///
	/// Returns `Ok(StaticFilesConfig)` if static_root is configured,
	/// or `Err` if static_root is None.
	///
	/// # Examples
	///
	/// ```no_run
	/// use reinhardt_conf::settings::Settings;
	/// use std::path::PathBuf;
	///
	/// #[allow(deprecated)]
	/// let settings = Settings::new(
	///     PathBuf::from("/app"),
	///     "secret".to_string()
	/// );
	///
	/// let config = settings.get_static_config().unwrap();
	/// assert_eq!(config.static_url, "/static/");
	/// ```
	pub fn get_static_config(&self) -> Result<StaticFilesConfig, String> {
		let static_root = self
			.static_root
			.clone()
			.ok_or_else(|| "STATIC_ROOT is not configured".to_string())?;

		Ok(StaticFilesConfig {
			static_root,
			static_url: self.static_url.clone(),
			staticfiles_dirs: self.staticfiles_dirs.clone(),
			media_url: Some(self.media_url.clone()),
		})
	}
}

#[allow(deprecated)] // Internal: Settings is deprecated but we still need to implement Default
impl Default for Settings {
	fn default() -> Self {
		Self::new(
			PathBuf::from("."),
			"insecure-change-this-in-production".to_string(),
		)
	}
}

#[allow(deprecated)] // Internal: Settings is deprecated but we still need the HasCoreSettings bridge
impl HasSettings<CoreSettings> for Settings {
	fn get_settings(&self) -> &CoreSettings {
		&self.core
	}
}

// Re-export DatabaseConfig from database_config module
pub use database_config::DatabaseConfig;

// Re-export policy types
pub use policy::{FieldPolicy, FieldRequirement};

// Re-export ComposedSettings trait
pub use composed::ComposedSettings;

// Re-export the merge strategy selector for SettingsBuilder. See issue #4260.
pub use builder::MergeStrategy;

/// Template engine configuration
#[non_exhaustive]
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct TemplateConfig {
	/// Template backend/engine
	pub backend: String,

	/// Directories to search for templates
	pub dirs: Vec<PathBuf>,

	/// Search for templates in app directories
	pub app_dirs: bool,

	/// Template engine options
	pub options: HashMap<String, serde_json::Value>,
}

impl TemplateConfig {
	/// Create a new template configuration
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::TemplateConfig;
	///
	/// let config = TemplateConfig::new("reinhardt.template.backends.jinja2.Jinja2");
	///
	/// assert_eq!(config.backend, "reinhardt.template.backends.jinja2.Jinja2");
	/// assert!(config.app_dirs);
	/// assert_eq!(config.dirs.len(), 0);
	/// ```
	pub fn new(backend: impl Into<String>) -> Self {
		Self {
			backend: backend.into(),
			dirs: vec![],
			app_dirs: true,
			options: HashMap::new(),
		}
	}
	/// Add a template directory
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::TemplateConfig;
	/// use std::path::PathBuf;
	///
	/// let config = TemplateConfig::new("reinhardt.template.backends.jinja2.Jinja2")
	///     .add_dir("/app/templates");
	///
	/// assert_eq!(config.dirs.len(), 1);
	/// assert_eq!(config.dirs[0], PathBuf::from("/app/templates"));
	/// ```
	pub fn add_dir(mut self, dir: impl Into<PathBuf>) -> Self {
		self.dirs.push(dir.into());
		self
	}
}

impl Default for TemplateConfig {
	fn default() -> Self {
		let mut options = HashMap::new();
		options.insert(
			"context_processors".to_string(),
			serde_json::json!([
				"reinhardt.template.context_processors.request",
				"reinhardt.contrib.auth.context_processors.auth",
				"reinhardt.contrib.messages.context_processors.messages",
			]),
		);

		Self {
			backend: "reinhardt.template.backends.jinja2.Jinja2".to_string(),
			dirs: vec![],
			app_dirs: true,
			options,
		}
	}
}

/// Middleware configuration
#[non_exhaustive]
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct MiddlewareConfig {
	/// Full path to the middleware class
	pub path: String,

	/// Middleware options
	pub options: HashMap<String, serde_json::Value>,
}

impl MiddlewareConfig {
	/// Create a new middleware configuration
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::MiddlewareConfig;
	///
	/// let middleware = MiddlewareConfig::new("myapp.middleware.CustomMiddleware");
	///
	/// assert_eq!(middleware.path, "myapp.middleware.CustomMiddleware");
	/// assert_eq!(middleware.options.len(), 0);
	/// ```
	pub fn new(path: impl Into<String>) -> Self {
		Self {
			path: path.into(),
			options: HashMap::new(),
		}
	}
	/// Add an option to the middleware
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::MiddlewareConfig;
	///
	/// let middleware = MiddlewareConfig::new("myapp.middleware.CustomMiddleware")
	///     .with_option("timeout", serde_json::json!(30));
	///
	/// assert_eq!(middleware.options.get("timeout"), Some(&serde_json::json!(30)));
	/// ```
	pub fn with_option(mut self, key: impl Into<String>, value: serde_json::Value) -> Self {
		self.options.insert(key.into(), value);
		self
	}
}

#[cfg(test)]
#[allow(deprecated)] // Tests exercise deprecated Settings for backward-compatibility verification
mod tests {
	use super::*;
	use crate::settings::core_settings::HasCoreSettings;
	use rstest::rstest;

	#[rstest]
	fn test_settings_default_unit() {
		// Arrange / Act
		let settings = Settings::default();

		// Assert
		assert!(settings.core.debug);
		assert_eq!(settings.language_code, "en-us");
		assert_eq!(settings.time_zone, "UTC");
	}

	#[rstest]
	fn test_template_config() {
		// Arrange / Act
		let config = TemplateConfig::default();

		// Assert
		assert!(config.app_dirs);
		assert_eq!(config.backend, "reinhardt.template.backends.jinja2.Jinja2");
	}

	#[rstest]
	fn test_middleware_config() {
		// Arrange / Act
		let middleware = MiddlewareConfig::new("reinhardt.middleware.TestMiddleware")
			.with_option("enabled", serde_json::json!(true));

		// Assert
		assert_eq!(middleware.path, "reinhardt.middleware.TestMiddleware");
		assert_eq!(
			middleware.options.get("enabled"),
			Some(&serde_json::json!(true))
		);
	}

	#[rstest]
	fn test_contact_creation() {
		// Arrange / Act
		let contact = Contact::new("Alice Smith", "alice@example.com");

		// Assert
		assert_eq!(contact.name, "Alice Smith");
		assert_eq!(contact.email, "alice@example.com");
	}

	#[rstest]
	fn test_settings_admins() {
		// Arrange
		let mut settings = Settings::default();
		assert_eq!(settings.admins.len(), 0);

		// Act
		settings.add_admin("John Doe", "john@example.com");

		// Assert
		assert_eq!(settings.admins.len(), 1);
		assert_eq!(settings.admins[0].name, "John Doe");
		assert_eq!(settings.admins[0].email, "john@example.com");
	}

	#[rstest]
	fn test_settings_managers() {
		// Arrange
		let mut settings = Settings::default();
		assert_eq!(settings.managers.len(), 0);

		// Act
		settings.add_manager("Jane Smith", "jane@example.com");

		// Assert
		assert_eq!(settings.managers.len(), 1);
		assert_eq!(settings.managers[0].name, "Jane Smith");
		assert_eq!(settings.managers[0].email, "jane@example.com");
	}

	#[rstest]
	fn test_managers_from_admins() {
		// Arrange
		let mut settings = Settings::default();
		settings.add_admin("John Doe", "john@example.com");
		settings.add_admin("Jane Smith", "jane@example.com");
		assert_eq!(settings.managers.len(), 0);

		// Act
		settings.managers_from_admins();

		// Assert
		assert_eq!(settings.managers.len(), 2);
		assert_eq!(settings.managers, settings.admins);
	}

	#[rstest]
	fn test_with_admins_fluent_api() {
		// Arrange / Act
		let settings = Settings::default().with_admins(vec![
			Contact::new("Alice", "alice@example.com"),
			Contact::new("Bob", "bob@example.com"),
		]);

		// Assert
		assert_eq!(settings.admins.len(), 2);
		assert_eq!(settings.admins[0].name, "Alice");
		assert_eq!(settings.admins[1].name, "Bob");
	}

	#[rstest]
	fn test_with_managers_fluent_api() {
		// Arrange / Act
		let settings =
			Settings::default().with_managers(vec![Contact::new("Charlie", "charlie@example.com")]);

		// Assert
		assert_eq!(settings.managers.len(), 1);
		assert_eq!(settings.managers[0].name, "Charlie");
	}

	#[rstest]
	fn test_has_core_settings_bridge() {
		// Arrange
		let settings = Settings::new(PathBuf::from("/app"), "test-secret".to_string());

		// Act
		let core = settings.core();

		// Assert
		assert_eq!(core.base_dir, PathBuf::from("/app"));
		assert_eq!(core.secret_key, "test-secret");
		assert!(core.debug);
	}
}