footing 0.1.2

Feature-gated foundations for Rust backend services
Documentation
use std::time::Duration;

use super::{
    ConfigDocument, ConfigFieldDoc, ConfigIssue, ConfigIssues, ConfigSectionDoc,
    ConfigValidationError, MAX_CONFIG_ISSUES, human_duration,
};
use crate::result::{ClassifyError, ErrorKind};

struct AppConfig {
    host: String,
    port: u16,
}

impl AppConfig {
    fn validate(&self) -> Result<(), super::ConfigValidationError> {
        let mut issues = ConfigIssues::new();
        issues.require_non_empty("server.host", &self.host);
        issues.require(self.port > 0, "server.port", "must be greater than zero");
        issues.into_result()
    }

    fn build(&self) -> Result<String, super::ConfigValidationError> {
        self.validate()?;
        Ok(format!("{}:{}", self.host, self.port))
    }
}

#[test]
fn config_issues_merge_nested_validation_errors() {
    let mut collector = ConfigIssues::new();
    collector.require_non_empty("server.host", "");
    collector.extend_result(
        AppConfig {
            host: String::new(),
            port: 0,
        }
        .validate(),
    );

    let error = collector
        .into_result()
        .expect_err("collector should contain validation issues");
    let paths = error
        .issues()
        .iter()
        .map(|issue| issue.path())
        .collect::<Vec<_>>();

    assert!(paths.contains(&"server.host"));
    assert!(paths.contains(&"server.port"));
    assert_eq!(error.error_kind(), ErrorKind::Validation);
    assert_eq!(error.error_code(), "configuration_invalid");
}

#[test]
fn config_issue_uses_stable_fallbacks_for_empty_operator_text() {
    let issue = ConfigIssue::new(" ", "");

    assert_eq!(issue.path(), "configuration");
    assert_eq!(issue.message(), "is invalid");
}

#[test]
fn config_issues_report_when_the_bounded_collection_is_truncated() {
    let mut issues = ConfigIssues::new();
    for index in 0..=MAX_CONFIG_ISSUES {
        issues.push(format!("field.{index}"), "is invalid");
    }

    assert_eq!(issues.len(), MAX_CONFIG_ISSUES);
    assert!(issues.is_truncated());

    let message = issues.into_result().unwrap_err().to_string();
    assert!(message.contains("additional issues omitted"));
}

#[test]
fn config_validation_error_normalizes_an_empty_issue_collection() {
    let error = ConfigValidationError::new(ConfigIssues::new());

    assert_eq!(error.issues().len(), 1);
    assert_eq!(error.issues()[0].path(), "configuration");
    assert_eq!(error.issues()[0].message(), "is invalid");
}

#[test]
fn human_duration_accepts_compact_duration_strings() {
    assert_eq!(
        human_duration::parse("1h30m").expect("duration should parse"),
        Duration::from_secs(90 * 60)
    );
    assert_eq!(
        human_duration::parse("500ms").expect("duration should parse"),
        Duration::from_millis(500)
    );
    assert_eq!(
        human_duration::parse("1µs").expect("duration should parse"),
        Duration::from_micros(1)
    );
    assert_eq!(
        human_duration::parse("2w 3d 4h").expect("duration should parse"),
        Duration::from_secs((14 + 3) * 24 * 60 * 60 + 4 * 60 * 60)
    );
}

#[test]
fn human_duration_rejects_ambiguous_values() {
    assert!(human_duration::parse("").is_err());
    assert!(human_duration::parse("5").is_err());
    assert!(human_duration::parse("1mo").is_err());
    assert_eq!(
        human_duration::parse("1msec"),
        Err(human_duration::ParseDurationError::InvalidUnit)
    );
    assert!(human_duration::parse("m").is_err());
}

#[test]
fn human_duration_errors_have_stable_classification() {
    let error = human_duration::parse("1mo").expect_err("unit should be invalid");
    let descriptor = error.error_descriptor();

    assert_eq!(descriptor.kind(), ErrorKind::Validation);
    assert_eq!(descriptor.code().as_str(), "duration_invalid_unit");
}

#[test]
fn human_duration_formats_using_largest_exact_unit() {
    assert_eq!(human_duration::format(Duration::from_secs(60 * 60)), "1h");
    assert_eq!(human_duration::format(Duration::from_millis(500)), "500ms");
    assert_eq!(human_duration::format(Duration::from_nanos(1)), "1ns");
}

#[test]
fn human_duration_option_supports_null_and_strings() {
    #[derive(serde::Deserialize, serde::Serialize)]
    struct Config {
        #[serde(default, with = "human_duration::option")]
        value: Option<Duration>,
    }

    let parsed: Config = serde_json::from_str(r#"{ "value": "5m" }"#).unwrap();
    assert_eq!(parsed.value, Some(Duration::from_secs(300)));

    let parsed: Config = serde_json::from_str(r#"{ "value": null }"#).unwrap();
    assert_eq!(parsed.value, None);
    assert_eq!(
        serde_json::to_value(Config {
            value: Some(Duration::from_secs(30))
        })
        .unwrap(),
        serde_json::json!({ "value": "30s" })
    );
}

#[test]
fn settings_build_validates_before_mapping() {
    let config = AppConfig {
        host: "127.0.0.1".to_owned(),
        port: 8080,
    };
    assert_eq!(config.build().unwrap(), "127.0.0.1:8080");

    let config = AppConfig {
        host: String::new(),
        port: 0,
    };
    let error = config.build().unwrap_err();
    assert_eq!(error.issues().len(), 2);
    assert!(error.to_string().contains("server.host"));
}

#[test]
fn config_document_renders_markdown_and_toml_example() {
    let document = ConfigDocument::new("Example").with_section(
        ConfigSectionDoc::new("server")
            .with_description("HTTP listener settings.")
            .with_field(ConfigFieldDoc::required(
                "host",
                r#""127.0.0.1""#,
                "Bind host.",
            ))
            .with_field(
                ConfigFieldDoc::optional_default("port", "8080", "Bind port.").recommended(),
            )
            .with_field(ConfigFieldDoc::optional_default(
                "debug",
                "false",
                "Debug mode.",
            ))
            .with_field(
                ConfigFieldDoc::required("token", r#""change-me""#, "Admin token.")
                    .secret()
                    .with_restart_required()
                    .with_env_var("APP_TOKEN"),
            ),
    );

    document.validate().expect("document should be valid");
    assert!(document.sections()[0].field("port").is_some());

    let markdown = document.render_markdown();
    assert!(markdown.contains("## [server]"));
    assert!(markdown.contains("`host` required"));
    assert!(markdown.contains("default `8080`"));
    assert!(markdown.contains("`port`, recommended"));
    assert!(markdown.contains("`token` required, secret, restart required"));
    assert!(markdown.contains("env `APP_TOKEN`"));

    let toml = document.render_toml_example();
    assert!(toml.contains("[server]"));
    assert!(toml.contains("host = \"127.0.0.1\""));
    assert!(toml.contains("# port = 8080"));

    let required = document.render_required_toml_example();
    assert!(required.contains("host = \"127.0.0.1\""));
    assert!(required.contains("token = \"change-me\" # secret"));
    assert!(!required.contains("port = 8080"));

    let recommended = document.render_recommended_toml_example();
    assert!(recommended.contains("host = \"127.0.0.1\""));
    assert!(recommended.contains("port = 8080"));
    assert!(!recommended.contains("debug = false"));
}

#[test]
fn secret_config_field_debug_redacts_example_and_default_values() {
    let secret = "private-config-secret";
    let field = ConfigFieldDoc::optional_default("token", secret, "Admin token.").secret();
    let debug = format!("{field:?}");

    assert!(debug.contains("token"));
    assert!(debug.contains("[REDACTED]"));
    assert!(!debug.contains(secret));

    let non_secret = ConfigFieldDoc::optional_default("port", "8080", "Bind port.");
    assert!(format!("{non_secret:?}").contains("8080"));
}

#[test]
fn config_document_validation_rejects_invalid_toml_paths_and_duplicates() {
    let document = ConfigDocument::new("Bad")
        .with_section(
            ConfigSectionDoc::new("bad section").with_field(ConfigFieldDoc::required(
                "host",
                r#""127.0.0.1""#,
                "",
            )),
        )
        .with_section(
            ConfigSectionDoc::new("server")
                .with_field(ConfigFieldDoc::required("host", r#""127.0.0.1""#, ""))
                .with_field(ConfigFieldDoc::optional("host", "8080", "")),
        )
        .with_section(ConfigSectionDoc::new("server"));

    let error = document.validate().expect_err("document should be invalid");
    let message = error.to_string();

    assert!(message.contains("[bad section]"));
    assert!(message.contains("server.host"));
    assert!(message.contains("section name must be unique"));
    assert!(message.contains("field name must be unique within section"));
}