Konfigurationsschema

Anwendungsschemas sind normale confique-Konfigurationstypen. Das Root-Schema muss ConfigSchema implementieren, damit rust-config-tree rekursive Includes aus der zwischengeschalteten confique-Schicht entdecken kann.

#![allow(unused)]
fn main() {
use std::path::PathBuf;

use confique::Config;
use schemars::JsonSchema;
use rust_config_tree::ConfigSchema;

#[derive(Debug, Config, JsonSchema)]
struct AppConfig {
    #[config(default = [])]
    include: Vec<PathBuf>,

    #[config(nested)]
    #[schemars(extend("x-tree-split" = true))]
    database: DatabaseConfig,
}

#[derive(Debug, Config, JsonSchema)]
struct DatabaseConfig {
    #[config(env = "APP_DATABASE_URL")]
    url: String,

    #[config(default = 16)]
    #[config(env = "APP_DATABASE_POOL_SIZE")]
    pool_size: u32,
}

impl ConfigSchema for AppConfig {
    fn include_paths(layer: &<Self as Config>::Layer) -> Vec<PathBuf> {
        layer.include.clone().unwrap_or_default()
    }
}
}

Include-Feld

Das Include-Feld kann beliebig heissen. rust-config-tree kennt es nur ueber ConfigSchema::include_paths.

Das Feld sollte normalerweise einen leeren Default haben:

#![allow(unused)]
fn main() {
#[config(default = [])]
include: Vec<PathBuf>,
}

Der Loader erhaelt fuer jede Datei eine teilweise geladene Schicht. Dadurch kann er Kind-Konfigurationsdateien entdecken, bevor das finale Schema zusammengefuehrt und validiert wird.

Verschachtelte Abschnitte

Verwende #[config(nested)] fuer strukturierte Abschnitte. Verschachtelte Abschnitte werden immer fuer das Laden zur Laufzeit genutzt. Fuege #[schemars(extend("x-tree-split" = true))] hinzu, wenn ein nested Feld zusaetzlich als eigenes *.yaml-Template und <section>.schema.json-Schema erzeugt werden soll:

#![allow(unused)]
fn main() {
#[derive(Debug, Config, JsonSchema)]
struct AppConfig {
    #[config(nested)]
    #[schemars(extend("x-tree-split" = true))]
    server: ServerConfig,
}
}

Die natuerliche YAML-Form ist:

server:
  bind: 127.0.0.1
  port: 8080

Nur-Umgebung-Felder

Markiere ein Blattfeld mit #[schemars(extend("x-env-only" = true))], wenn sein Wert nur aus einer Umgebungsvariable kommen soll und nicht in generierten Konfigurationsdateien erscheinen darf. Generierte YAML-Vorlagen und JSON-Schemas lassen env-only-Felder weg, und dadurch leere Elternobjekte werden entfernt.

#![allow(unused)]
fn main() {
#[config(env = "APP_SECRET")]
#[schemars(extend("x-env-only" = true))]
secret: String,
}

Feldwertvalidierung

Erzeugte *.schema.json-Dateien sind nur fuer IDE-Vervollstaendigung und grundlegende Editor-Pruefungen gedacht. Sie entscheiden nicht, ob ein konkreter Feldwert fuer die Anwendung gueltig ist.

Feldwertvalidierung muss im Code mit #[config(validate = Self::validate)] implementiert werden. Der Validator laeuft, wenn die finale Konfiguration ueber load_config geladen oder ueber config-validate geprueft wird.

Abschnittspfade fuer Vorlagen ueberschreiben

Wenn eine Vorlagenquelle keine Includes hat, kann die Crate Kind-Vorlagendateien aus mit x-tree-split markierten verschachtelten Schemaabschnitten ableiten. Der Standardpfad auf oberster Ebene ist <section>.yaml.

Ueberschreibe diesen Pfad mit template_path_for_section:

#![allow(unused)]
fn main() {
impl ConfigSchema for AppConfig {
    fn include_paths(layer: &<Self as Config>::Layer) -> Vec<PathBuf> {
        layer.include.clone().unwrap_or_default()
    }

    fn template_path_for_section(section_path: &[&str]) -> Option<PathBuf> {
        match section_path {
            ["database"] => Some(PathBuf::from("examples/database.yaml")),
            _ => None,
        }
    }
}
}