Struct SettingsManagerBuilder 

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

Main settings manager and builder. Builder for creating a SettingsManager with a fluent API.

This is the recommended way to create a SettingsManager. It allows you to configure all options and register sub-settings in a single chain of calls.

Example

use rcman::{SettingsManager, SubSettingsConfig};

let manager = SettingsManager::builder("my-app", "1.0.0")
    .with_config_dir("~/.config/my-app")
    .with_credentials()
    .with_sub_settings(SubSettingsConfig::new("remotes"))
    .with_sub_settings(SubSettingsConfig::singlefile("backends"))
    .build()
    .unwrap();

Implementations

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

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

Create a new builder with required app name and version.

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

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

Set the configuration directory path.

If not set, uses the system config directory.

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

Set the settings filename (default: “settings.json”).

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 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::{SettingsManager, CredentialConfig};

let manager = SettingsManager::builder("my-app", "1.0.0")
    .with_credential_config(CredentialConfig::WithFallback {
        fallback_path: "/tmp/secrets.enc.json".into(),
        encryption_key: [0u8; 32], // Use a derived key
    })
    .build()
    .unwrap();

pub fn with_env_credentials(self) -> Self

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

The environment variable name is automatically derived from the app name (e.g., “my-app” -> “MY_APP_SECRET”).

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

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

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

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

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

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)

Example

use rcman::SettingsManager;

let manager = SettingsManager::builder("my-app", "1.0.0")
    .with_env_prefix("MYAPP")
    .build()
    .unwrap();

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

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.

pub fn with_hot_reload(self) -> Self

Enable hot-reload with default watcher configuration.

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

Enable hot-reload with a custom watcher configuration.

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.

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

Specify the schema type for the settings.

This transforms the builder to use a typed schema instead of dynamic.

Example

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

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

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

let manager = SettingsManager::builder("my-app", "1.0.0")
    .with_schema::<AppSettings>()
    .build()
    .unwrap();

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

Specify the storage backend type.

This transforms the builder to use the specified storage backend.

Example

use rcman::{SettingsManager, JsonStorage};

let manager = SettingsManager::builder("my-app", "1.0.0")
    .with_storage::<JsonStorage>()
    .build()
    .unwrap();

pub fn with_profiles(self) -> Self

Enable profiles for main settings.

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

Example

use rcman::SettingsManager;

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

// Switch the entire app to work profile
manager.switch_profile("work")?;

pub fn with_sub_settings(self, config: SubSettingsConfig) -> Self

Register a sub-settings type for per-entity configuration.

Sub-settings allow you to manage separate config files for each entity (e.g., one file per remote, per profile, etc.).

Example

use rcman::{SettingsManager, SubSettingsConfig};

let manager = SettingsManager::builder("my-app", "1.0.0")
    .with_sub_settings(SubSettingsConfig::new("remotes"))
    .with_sub_settings(SubSettingsConfig::singlefile("backends"))
    .build()
    .unwrap();

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

where S: Default + 'static,

Build the SettingsManager.

This creates the config directory if it doesn’t exist, initializes the manager, and registers all sub-settings.

Errors

Returns an error if the config directory cannot be created.