Crate rcman 

rcman - Rust Config Manager

A generic, framework-agnostic Rust library for managing application settings with backup/restore, sub-settings, and automatic secret storage.

Features

• Settings Management: Load, save, and reset settings with schema metadata
• Secret Settings: Mark settings with .secret() to auto-store in OS keychain (requires keychain or encrypted-file feature)
• Sub-Settings: Per-entity configuration files (e.g., one file per “remote”)
• Backup & Restore: Create and restore encrypted backups with AES-256
• Schema Validation: Regex patterns, numeric ranges, and option constraints
• Performance: In-memory caching for fast access

Quick Start

use rcman::{SettingsManager, SubSettingsConfig};

let manager = SettingsManager::builder("my-app", "1.0.0")
    .config_dir("~/.config/my-app")
    .with_credentials()  // Enable automatic secret storage
    .with_sub_settings(SubSettingsConfig::new("remotes"))
    .build()
    .unwrap();

Defining Settings Schema

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

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

impl SettingsSchema for MySettings {
    fn get_metadata() -> HashMap<String, SettingMetadata> {
        settings! {
            "ui.theme" => SettingMetadata::select("Theme", "dark", vec![
                opt("light", "Light"),
                opt("dark", "Dark"),
            ]).category("appearance"),

            "ui.font_size" => SettingMetadata::number("Font Size", 14.0)
                .min(8.0).max(32.0).step(1.0),

            "logging.output" => SettingMetadata::file("Log File", "/var/log/app.log")
                .description("Path to the log output file"),

            "api.key" => SettingMetadata::password("API Key", "")
                .secret(),  // Auto-stored in OS keychain!
        }
    }
}

Default Value Behavior

When you save a setting that equals its default value, rcman removes it from storage to keep files minimal. This applies to both regular settings and secrets:

• Regular settings: Removed from JSON file
• Secret settings: Removed from keychain

This means:

• Settings files only contain user customizations
• Changing defaults in code auto-applies to users who haven’t customized
• Using reset_setting() removes the key from storage

Sub-Settings (Per-Entity Config)

use rcman::{SettingsManager, SubSettingsConfig};
use serde_json::json;

// Register sub-settings via builder
let manager = SettingsManager::builder("my-app", "1.0.0")
    .with_sub_settings(SubSettingsConfig::new("remotes"))  // Multi-file mode
    .with_sub_settings(SubSettingsConfig::new("backends").single_file())  // Single-file mode
    .build()?;

// Access sub-settings
let remotes = manager.sub_settings("remotes")?;
remotes.set("gdrive", &json!({"type": "drive"}))?;

Backup & Restore

use rcman::{SettingsManager, SettingsConfig, BackupOptions, RestoreOptions};

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

// Create encrypted backup using builder pattern
let path = manager.backup()
    .create(BackupOptions::new()
        .output_dir("backups/")
        .password("secret")
        .note("Weekly backup"))?;

// Analyze a backup before restoring (inspect contents, check if encrypted)
let analysis = manager.backup().analyze(&path)?;
println!("Encrypted: {}", analysis.requires_password);
println!("Valid: {}", analysis.is_valid);
println!("App version: {}", analysis.manifest.backup.app_version);

// Restore from backup
manager.backup()
    .restore(RestoreOptions::from_path(&path)
        .password("secret")
        .overwrite(true))?;

Credentials

Note: CredentialManager is only available when the keychain or encrypted-file feature is enabled.

#[cfg(feature = "keychain")]
{
    use rcman::CredentialManager;

    let creds = CredentialManager::new("my-app");
    creds.store("api-key", "secret-value").unwrap();
    let key = creds.get("api-key").unwrap();
}

Re-exports

pub use config::opt;

pub use config::SettingMetadata;

pub use config::SettingOption;

pub use config::SettingType;

pub use config::SettingsConfig;

pub use config::SettingsConfigBuilder;

pub use config::SettingsSchema;

pub use backup::BackupAnalysis;

pub use backup::BackupContents;

pub use backup::BackupManager;

pub use backup::BackupManifest;

pub use backup::BackupOptions;

pub use backup::ExportCategory;

pub use backup::ExportCategoryType;

pub use backup::ExportType;

pub use backup::ExternalConfig;

pub use backup::ExternalConfigProvider;

pub use backup::RestoreOptions;

pub use backup::RestoreResult;

pub use backup::SubSettingsManifestEntry;

pub use credentials::CredentialManager;

pub use credentials::SecretStorage;

Modules

backup

Backup and restore module for rcman

config

Core configuration types and traits

credentials

Credential management module

Macros

settings

Macro for building settings metadata HashMap more cleanly

Structs

DocsConfig

Configuration for docs generation

EventManager

Manages event listeners for settings changes

JsonStorage

JSON storage backend (default)

SettingsManager

Main settings manager for loading, saving, and managing application settings.

SettingsManagerBuilder

Builder for creating a SettingsManager with a fluent API.

SubSettings

Handler for a single sub-settings type

SubSettingsConfig

Configuration for a sub-settings type

Enums

Error

Main error type for rcman library

Traits

StorageBackend

Trait for storage backend implementations

Functions

generate_docs

Generate markdown documentation from a settings schema

generate_docs_from_metadata

Generate docs from raw metadata (useful when schema isn’t available)

Type Aliases

JsonSettingsManager

Convenient type alias for the common JSON-based SettingsManager.

Result

Result type alias for rcman operations

Derive Macros

DeriveSettingsSchema

Derive macro for auto-generating SettingsSchema implementations.