cfgmatic-source

Unified configuration source abstraction for the cfgmatic framework.

Overview

cfgmatic-source provides a trait-based abstraction for loading configuration from various sources. It follows hexagonal architecture principles with clear separation between domain, application, and infrastructure layers.

Built-in infrastructure covers file, env, memory, composite, and cascade loading. URL-backed sources remain possible through custom Source implementations, but are not shipped by this crate.

Features

• FileSource - Load configuration from files (TOML, JSON, YAML)
• EnvSource - Load from environment variables with prefix support
• MemorySource - In-memory source for testing
• CompositeSource - Combine multiple sources with priorities
• CascadeLoader - Git-like layered configuration (system -> global -> local -> worktree)
• Async Support - Optional async API via async feature flag
• Format Detection - Automatic format detection from file extensions

Installation

Add to your Cargo.toml:

[dependencies]
cfgmatic-source = "3"

Feature Flags

Quick Start

File Source

use cfgmatic_source::prelude::*;

// Single file
let source = FileSource::new("config.toml");
let content = source.load_raw()?;

// Multiple files (merged)
let source = FileSource::builder()
    .path("config.default.toml")
    .path("config.local.toml")
    .required(false)
    .build()?;

let parsed = source.load()?;

Environment Source

use cfgmatic_source::prelude::*;

// With prefix
let source = EnvSource::with_prefix("MYAPP");
// Reads MYAPP_DATABASE_URL, MYAPP_SERVER_PORT, etc.

let content = source.load_raw()?;

Composite Source

use cfgmatic_source::prelude::*;

let composite = CompositeSource::builder()
    .add_with_priority(FileSource::new("config.toml"), SourcePriority::LOWEST)
    .add_with_priority(MemorySource::from_json(serde_json::json!({
        "server": { "port": 3000 }
    })), SourcePriority::HIGH)
    .build();

let raw = composite.load_raw()?;

Cascading Configuration

Use CascadeLoader when configuration must be layered in a deterministic order, for example like .gitconfig with system -> global -> local -> worktree.

use cfgmatic_source::prelude::*;

let loader = CascadeLoader::builder()
    .add_optional_file(CascadeScope::System, "/etc/myapp/config.toml")
    .add_optional_file(CascadeScope::Global, "/home/alice/.config/myapp/config.toml")
    .add_optional_file(CascadeScope::Local, ".myapp/config.toml")
    .add_optional_file(CascadeScope::Worktree, ".myapp/config.worktree.toml")
    .default_format(Format::Toml)
    .build();

let result = loader.load()?;
println!("Loaded {} layers", result.loaded_layers.len());

This models Git-like precedence, but it does not parse Git's INI syntax or includeIf rules. It is a layering mechanism for TOML/JSON/YAML sources.

Using with Loader

use cfgmatic_source::prelude::*;
use serde::Deserialize;

#[derive(Deserialize)]
struct Config {
    server: ServerConfig,
    database: DatabaseConfig,
}

#[derive(Deserialize)]
struct ServerConfig {
    host: String,
    port: u16,
}

#[derive(Deserialize)]
struct DatabaseConfig {
    url: String,
}

let source = FileSource::new("config.toml");
let loader = Loader::new();

let config: Config = loader.load_as(&source)?;

Architecture

+-------------------------------------------------+
|                    lib.rs                        |
|              (Facade + Re-exports)               |
+-------------------------------------------------+
                       |
+-------------------------------------------------+
|                 Config Layer                     |
|         LoadOptions, SourceConfig               |
+-------------------------------------------------+
                       |
+-------------------------------------------------+
|              Application Layer                   |
|           Loader, SourceCoordinator             |
+-------------------------------------------------+
                       |
+-------------------------------------------------+
|             Infrastructure Layer                 |
|   FileSource, EnvSource, MemorySource, etc.     |
+-------------------------------------------------+
                       |
+-------------------------------------------------+
|                 Domain Layer                     |
|    Source trait, Format, RawContent, Errors     |
+-------------------------------------------------+

API Reference

See the API documentation for full details.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.