Crate cfgmatic_source 

cfgmatic-source

Configuration sources (file, env, remote) for cfgmatic framework.

This crate provides a unified interface for loading configuration from various sources: files, environment variables, and remote URLs.

Architecture

graph TB
    subgraph "Public API"
        LIB[lib.rs Facade]
        PRELUDE[prelude]
        FUNC[Convenience Functions]
    end

    subgraph "Config Layer"
        OPT[LoaderOptions]
        CTX[LoadContext]
    end

    subgraph "Application Layer"
        LOADER[Loader]
        DETECTOR[FormatDetector]
    end

    subgraph "Infrastructure Layer"
        FS[FileSource]
        ES[EnvSource]
        MS[MemorySource]
        CS[CompositeSource]
        REG[SourceRegistry]
    end

    subgraph "Domain Layer"
        SRC[Source Trait]
        KIND[SourceKind]
        META[SourceMetadata]
        FMT[Format]
        RAW[RawContent]
        PARSED[ParsedContent]
        ERR[SourceError]
    end

    LIB --> PRELUDE
    LIB --> FUNC
    LIB --> OPT
    LIB --> LOADER
    LIB --> SRC

    FUNC --> LOADER
    LOADER --> REG
    REG --> FS
    REG --> ES
    REG --> MS
    REG --> CS

    FS --> SRC
    ES --> SRC
    MS --> SRC
    CS --> SRC

    SRC --> RAW
    RAW --> FMT
    FMT --> PARSED
    DETECTOR --> FMT

    OPT --> CTX
    CTX --> LOADER

Layer Dependencies

The architecture follows the Onion (Layered) pattern with dependencies pointing inward:

+------------------------------------------+
|              lib.rs (Facade)              |
+------------------------------------------+
                    |
+------------------------------------------+
|             Config Layer                  |
|  Options, Context, Builders               |
+------------------------------------------+
                    |
+------------------------------------------+
|          Infrastructure Layer             |
|  FileSource, EnvSource, MemorySource,     |
|  CompositeSource, Registry                |
+------------------------------------------+
                    |
+------------------------------------------+
|           Application Layer               |
|  Loader, FormatDetector                   |
+------------------------------------------+
                    |
+------------------------------------------+
|             Domain Layer                  |
|  Source, SourceKind, Format,              |
|  RawContent, ParsedContent, Error         |
+------------------------------------------+

Feature Flags

Feature	Description	Default
file	File-based sources	Yes
env	Environment variable sources	No
remote	Remote HTTP/HTTPS sources	No
toml	TOML format support	Yes
json	JSON format support	Yes
yaml	YAML format support	No
async	Async source loading	No
watch	File watching support	No

Quick Start

Load from a file

use cfgmatic_source::prelude::*;

let content = FileSource::new("config.toml")
    .load()?
    .parse_as::<MyConfig>()?;

Load from environment

use cfgmatic_source::prelude::*;

let content = EnvSource::new("APP")
    .load()?
    .parse_as::<MyConfig>()?;

Combine multiple sources

use cfgmatic_source::prelude::*;

let source = CompositeSource::new()
    .with_source(FileSource::new("config.toml"), SourcePriority::High)
    .with_source(EnvSource::new("APP"), SourcePriority::Low);

let content = source.load()?.parse_as::<MyConfig>()?;

Use convenience functions

use cfgmatic_source::{load, load_from_file, load_from_env};

// Auto-detect source and load
let config: MyConfig = load()?;

// Load from specific file
let config: MyConfig = load_from_file("config.toml")?;

// Load from environment
let config: MyConfig = load_from_env("APP")?;

Re-exports

pub use domain::Format;

pub use domain::ParsedContent;

pub use domain::RawContent;

pub use domain::Result;

pub use domain::Source;

pub use domain::SourceError;

pub use domain::SourceKind;

pub use domain::SourceMetadata;

pub use infrastructure::CompositeSource;

pub use infrastructure::CompositeSourceBuilder;

pub use infrastructure::MemorySource;

pub use infrastructure::MemorySourceBuilder;

pub use infrastructure::SourcePriority;

pub use infrastructure::FileSource;

pub use infrastructure::FileSourceBuilder;

pub use config::LoadOptions;

pub use config::LoadOptionsBuilder;

pub use config::MergeStrategy;

pub use config::SourceConfig;

pub use config::SourceConfigBuilder;

pub use application::LoadResult;

pub use application::Loader;

pub use application::LoaderBuilder;

pub use application::SourceCoordinator;

pub use application::SourceCoordinatorBuilder;

pub use constants::DEFAULT_APP_NAME;

pub use constants::DEFAULT_CONFIG_BASE_NAME;

pub use constants::DEFAULT_DEBOUNCE_MS;

pub use constants::DEFAULT_ENV_PREFIX;

pub use constants::DEFAULT_EXTENSIONS;

pub use constants::DEFAULT_REMOTE_TIMEOUT_SECS;

pub use constants::ENV_KEY_SEPARATOR;

pub use constants::JSON_POINTER_ROOT;

pub use constants::MAX_REMOTE_RETRIES;

pub use constants::MAX_SEARCH_DEPTH;

Modules

application

Application layer - services. Application layer - services for loading configuration.

config

Config layer - options and context. Config layer - options and configuration types.

constants

Constants for cfgmatic-source.

domain

Domain layer - core business entities and rules.

infrastructure

Infrastructure layer - source implementations.

prelude

Common imports for cfgmatic-source.

Functions

load

Load configuration from auto-detected source.

load_from_file

Load configuration from a specific file.

load_from_memory

Load configuration from memory (useful for testing).