Struct SettingsConfigBuilder 

pub struct SettingsConfigBuilder<S: StorageBackend = JsonStorage, Schema: SettingsSchema = ()> { /* private fields */ }

Core configuration types and traits for settings management. Builder for creating SettingsConfig with a fluent API.

This is the recommended way to create a settings manager.

Type Parameters

• Schema: Settings schema type (defaults to () for dynamic usage)

Examples

Type-Safe (With Schema):

use rcman::{SettingsConfig, SettingsSchema, SettingMetadata, settings};
use serde::{Serialize, Deserialize};
use std::collections::HashMap;

#[derive(Default, Serialize, Deserialize)]
struct MySettings { theme: String }

impl SettingsSchema for MySettings {
    fn get_metadata() -> HashMap<String, SettingMetadata> {
        settings! { "ui.theme" => SettingMetadata::text("dark").meta_str("label", "Theme") }
    }
}

let config = SettingsConfig::builder("my-app", "1.0.0")
    .with_schema::<MySettings>()
    .with_config_dir("~/.config/my-app")
    .build();

Dynamic (Without Schema):

use rcman::SettingsConfig;

let config = SettingsConfig::builder("my-app", "1.0.0")
    .with_config_dir("~/.config/my-app")
    .build();

Implementations

impl SettingsConfigBuilder

pub fn new(app_name: impl Into<String>, app_version: impl Into<String>) -> Self

Create a new builder with required app name and version

impl<S: StorageBackend, Schema: SettingsSchema> SettingsConfigBuilder<S, Schema>

pub fn with_pretty_json(self, pretty: bool) -> Self

Use compact JSON (no pretty printing)

Note: This method is only available when using JsonStorage.

Example

use rcman::SettingsConfig;

let config = SettingsConfig::builder("my-app", "1.0.0")
    .build();

pub fn with_config_dir(self, path: impl Into<PathBuf>) -> Self

Set the configuration directory

Supports ~ expansion for home directory.

pub fn settings_file(self, filename: impl Into<String>) -> Self

Set the settings filename (default: “settings.{ext}”)

pub fn with_credentials(self) -> Self

Enable credential management for secret settings with default behavior.

When enabled, settings marked as secret: true in metadata will be stored in the primary OS keychain instead of the settings file.

pub fn with_credential_config(self, config: CredentialConfig) -> Self

Extensively configure how credential secrets should be stored, enabling advanced scenarios like custom proxy backends or keychain fallbacks.

Example

use rcman::{SettingsConfig, CredentialConfig, SecretPasswordSource};

let config = SettingsConfig::builder("my-app", "1.0.0")
    .with_credential_config(CredentialConfig::WithFallback {
        fallback_path: "/tmp/secrets.enc.json".into(),
        password: SecretPasswordSource::Environment("APP_KEY".into()),
    })
    .build();

pub fn with_encrypted_fallback( self, path: impl Into<PathBuf>, password_source: SecretPasswordSource, ) -> Self

Enable credential management with an encrypted file fallback triggered by a password source.

This is the recommended way to support CI/Docker environments securely.

pub fn with_env_credentials(self) -> Self

pub fn with_custom_env_credentials(self, var_name: impl Into<String>) -> Self

Enable credentials with a custom environment variable password source (Keychain + Encrypted File fallback).

The fallback file will be stored at the default path in the config directory.

pub fn with_file_credentials(self, path: impl Into<PathBuf>) -> Self

Enable credentials with file password source (Keychain + Encrypted File fallback).

The fallback file will be stored at the default path in the config directory.

pub fn with_password_credentials(self, password: impl Into<String>) -> Self

Enable credentials with provided password string (Keychain + Encrypted File fallback).

The fallback file will be stored at the default path in the config directory.

pub fn with_external_config(self, config: ExternalConfig) -> Self

Register an external configuration file for backup

External configs are files managed outside of rcman (like rclone.conf) that can be included in backups.

Example

use rcman::SettingsConfig;
use rcman::backup::ExternalConfig;

let config = SettingsConfig::builder("my-app", "1.0.0")
    .with_external_config(ExternalConfig::new("rclone", "/path/to/rclone.conf")
        .display_name("Rclone Configuration"))
    .build();

pub fn with_env_prefix(self, prefix: impl Into<String>) -> Self

Enable environment variable overrides

When set, settings can be overridden by environment variables. The format is: {PREFIX}_{CATEGORY}_{KEY} (all uppercase, dots become underscores)

Example

use rcman::SettingsConfig;

let config = SettingsConfig::builder("my-app", "1.0.0")
    .with_env_prefix("MYAPP")
    .build();

// Now MYAPP_UI_THEME=dark will override the "ui.theme" setting

pub fn env_overrides_secrets(self, allow: bool) -> Self

Allow environment variables to override secret settings

By default, secrets stored in the OS keychain are NOT affected by env vars. Enable this for Docker/CI environments where secrets are passed via env.

Example

use rcman::SettingsConfig;

let config = SettingsConfig::builder("my-app", "1.0.0")
    .with_env_prefix("MYAPP")
    .env_overrides_secrets(true)  // MYAPP_API_KEY will override keychain
    .build();

pub fn with_env_source(self, source: Arc<dyn EnvSource>) -> Self

Set a custom environment variable source

Useful for testing or injecting env vars procedurally.

pub fn with_migrator<F>(self, migrator: F) -> Self

where F: Fn(Value) -> Value + Send + Sync + 'static,

Set a migration function for schema changes (lazy migration)

The migrator function is called automatically when loading settings. If the function modifies the value, the migrated version is saved back.

Use this to upgrade old data formats to new ones transparently.

Example

use rcman::SettingsConfig;
use serde_json::json;

let config = SettingsConfig::builder("my-app", "1.0.0")
    .with_migrator(|mut value| {
        // Migrate v1 to v2: rename "color" to "theme"
        if let Some(obj) = value.as_object_mut() {
            if let Some(ui) = obj.get_mut("ui").and_then(|v| v.as_object_mut()) {
                if let Some(color) = ui.remove("color") {
                    ui.insert("theme".to_string(), color);
                }
            }
        }
        value
    })
    .build();

pub fn with_hot_reload(self) -> Self

Enable hot-reload with default configuration.

pub fn with_hot_reload_config(self, config: HotReloadConfig) -> Self

Enable hot-reload with a custom configuration.

pub fn with_profiles(self) -> Self

Enable profiles for main settings

When enabled, the main settings file is stored per-profile, allowing completely different configurations (e.g., “work” vs “personal”).

Example

use rcman::SettingsManager;

let manager = SettingsManager::builder("my-app", "1.0.0")
    .with_profiles()  // Enable profiles for main settings
    .build()?;

// Now you can switch profiles
manager.switch_profile("work")?;

pub fn with_schema<NewSchema: SettingsSchema>( self, ) -> SettingsConfigBuilder<S, NewSchema>

Specify the schema type for compile-time type safety.

This binds your settings struct to the manager, enabling:

• Type-safe get_all() method returning your struct
• Compile-time validation of setting keys
• Better IDE autocomplete and refactoring support

Example

use rcman::{SettingsConfig, SettingsSchema, SettingMetadata, settings};
use serde::{Serialize, Deserialize};
use std::collections::HashMap;

#[derive(Default, Serialize, Deserialize)]
struct AppSettings {
    theme: String,
    font_size: f64,
}

impl SettingsSchema for AppSettings {
    fn get_metadata() -> HashMap<String, SettingMetadata> {
        settings! {
            "ui.theme" => SettingMetadata::text("dark").meta_str("label", "Theme"),
            "ui.font_size" => SettingMetadata::number(14.0).meta_str("label", "Font Size")
        }
    }
}

let config = SettingsConfig::builder("my-app", "1.0.0")
    .with_schema::<AppSettings>()  // Bind the schema
    .build();

pub fn with_storage<NewS: StorageBackend + Default>( self, ) -> SettingsConfigBuilder<NewS, Schema>

Specify the storage backend type.

This transforms the builder to use the specified storage backend. The settings filename will automatically be updated to match the format.

Example

use rcman::{SettingsConfig, JsonStorage};

let config = SettingsConfig::builder("my-app", "1.0.0")
    .with_storage::<JsonStorage>()
    .build();

pub fn build(self) -> SettingsConfig<S, Schema>

where S: Default,

Build the SettingsConfig

If config_dir is not set, uses the system config directory for the app.

Trait Implementations

impl<S: Clone + StorageBackend, Schema: Clone + SettingsSchema> Clone for SettingsConfigBuilder<S, Schema>

fn clone(&self) -> SettingsConfigBuilder<S, Schema>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S: StorageBackend, Schema: SettingsSchema> Debug for SettingsConfigBuilder<S, Schema>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.