datadog_agent_config_testing/

smoke_test.rs

use datadog_agent_config::DatadogEnvProvider;
use saluki_config::{ConfigurationLoader, GenericConfiguration};
use serde::Serialize;
use serde_json::json;

use crate::config_registry::{SalukiAnnotation, ValueType, SUPPORTED_ANNOTATIONS};

/// Test value injected for `String` keys.
pub const TEST_STRING_VALUE: &str = "http://smoke-proxy.example.com:3128";
/// Test value injected for `Bool` keys.
pub const TEST_BOOL_VALUE: bool = true;
/// Test value injected for `StringList` keys.
pub const TEST_STRING_LIST_VALUE: &[&str] = &["smoke-host-1.example.com", "smoke-host-2.example.com"];

fn test_json_value(value_type: ValueType) -> serde_json::Value {
    match value_type {
        ValueType::String => json!(TEST_STRING_VALUE),
        ValueType::Bool => json!(TEST_BOOL_VALUE),
        ValueType::StringList => json!(TEST_STRING_LIST_VALUE),
        ValueType::Integer => json!(42i64),
        ValueType::Float => json!(1.5f64),
        ValueType::Duration => json!("42s"),
    }
}

fn effective_test_value(annotation: &SalukiAnnotation) -> serde_json::Value {
    let v = test_json_value(annotation.value_type());
    if let Some(default_raw) = annotation.schema.default {
        if let Ok(default_val) = serde_json::from_str::<serde_json::Value>(default_raw) {
            if v == default_val {
                return match annotation.value_type() {
                    ValueType::Bool => json!(!default_val.as_bool().unwrap_or(false)),
                    _ => v,
                };
            }
        }
    }
    v
}

fn json_value_to_env_string(value: &serde_json::Value, value_type: ValueType) -> String {
    match value_type {
        ValueType::Bool => value
            .as_bool()
            .map(|b| b.to_string())
            .unwrap_or_else(|| "true".to_string()),
        ValueType::Integer => value
            .as_i64()
            .map(|n| n.to_string())
            .unwrap_or_else(|| "42".to_string()),
        ValueType::Float => value
            .as_f64()
            .map(|f| f.to_string())
            .unwrap_or_else(|| "1.5".to_string()),
        ValueType::String => value.as_str().unwrap_or(TEST_STRING_VALUE).to_string(),
        ValueType::StringList => value
            .as_array()
            .map(|arr| arr.iter().filter_map(|v| v.as_str()).collect::<Vec<_>>().join(" "))
            .unwrap_or_else(|| TEST_STRING_LIST_VALUE.join(" ")),
        ValueType::Duration => value.as_str().unwrap_or("42s").to_string(),
    }
}

fn collect_unchanged_leaves(
    full: &serde_json::Value, default: &serde_json::Value, path: &str, unchanged: &mut Vec<String>,
) {
    match (full, default) {
        (serde_json::Value::Object(f), serde_json::Value::Object(d)) => {
            for (key, full_val) in f {
                let child_path = if path.is_empty() {
                    key.clone()
                } else {
                    format!("{}.{}", path, key)
                };
                let def_val = d.get(key).unwrap_or(&serde_json::Value::Null);
                collect_unchanged_leaves(full_val, def_val, &child_path, unchanged);
            }
        }
        (full_val, def_val) => {
            if full_val == def_val {
                unchanged.push(path.to_string());
            }
        }
    }
}

fn yaml_path_to_json(yaml_path: &str, value: serde_json::Value) -> serde_json::Value {
    let mut root = json!({});
    saluki_config::upsert(&mut root, yaml_path, value);
    root
}

fn merge_over_base(base: &serde_json::Value, overlay: serde_json::Value) -> serde_json::Value {
    let mut merged = base.clone();
    if let (Some(base_obj), Some(overlay_obj)) = (merged.as_object_mut(), overlay.as_object()) {
        for (k, v) in overlay_obj {
            base_obj.insert(k.clone(), v.clone());
        }
    }
    merged
}

fn dd_env_var_to_test_key(env_var: &str) -> &str {
    env_var.strip_prefix("DD_").unwrap_or(env_var)
}

async fn make_config_from_file(file_values: serde_json::Value) -> GenericConfiguration {
    make_config(file_values, &[], Vec::new()).await
}

/// Builds a configuration from `base_file_values` plus one environment variable.
///
/// `env_var` is the variable's real name, as the Datadog Agent spells it. It is fed to
/// [`DatadogEnvProvider`] under that name so the schema-driven reader can resolve it to the key's
/// canonical path, exactly as it does in production. The same value is additionally handed to the
/// test loader's prefix-scanning environment provider under the `DD_`-stripped name, which is the
/// only spelling that provider can consume.
async fn make_config_from_env(
    base_file_values: &serde_json::Value, env_var: &str, value: &str,
) -> GenericConfiguration {
    let scanned = [(dd_env_var_to_test_key(env_var).to_string(), value.to_string())];
    let modeled = vec![(env_var.to_string(), value.to_string())];
    make_config(base_file_values.clone(), &scanned, modeled).await
}

async fn make_config(
    file_values: serde_json::Value, scanned_env_vars: &[(String, String)], modeled_env_vars: Vec<(String, String)>,
) -> GenericConfiguration {
    let (cfg, _) =
        ConfigurationLoader::for_tests_with_provider_factory(Some(file_values), Some(scanned_env_vars), false, |_| {
            DatadogEnvProvider::from_env_vars(modeled_env_vars)
                .expect("test environment values should decode into their declared shapes")
        })
        .await;
    cfg
}

/// Runs smoke tests for all annotations registered to `struct_name` against a deserialized config struct `T`.
///
/// Verifies three properties:
///
/// **Supported keys**: loading the struct with the test value set via the annotation's `yaml_path`
/// and via each of its effective env vars must all produce identical structs, and each must differ
/// from the default (empty-config) struct.
///
/// **Unsupported keys**: loading the struct with that key set must produce a struct identical to the
/// default struct.
///
/// **Full field coverage**: loading the struct with all supported keys set simultaneously must
/// produce a struct where every serialized leaf field differs from the default.
///
/// Environment values are supplied per test case rather than read from the ambient process
/// environment, so an unrelated variable set by the surrounding shell cannot influence a result.
pub async fn run_config_smoke_tests<T, Factory>(
    struct_name: &'static str, non_config_fields: &[&str], base_config: serde_json::Value, config_factory: Factory,
) where
    T: PartialEq + Serialize,
    Factory: Fn(GenericConfiguration) -> T,
{
    let keys: Vec<&'static SalukiAnnotation> = SUPPORTED_ANNOTATIONS
        .iter()
        .copied()
        .filter(|a| a.used_by.contains(&struct_name))
        .collect();

    let default_struct = config_factory(make_config_from_file(base_config.clone()).await);
    let mut failures: Vec<String> = Vec::new();

    for annotation in &keys {
        let canonical_path = annotation.yaml_path();
        let injected_value = match annotation.test_json {
            Some(raw) => serde_json::from_str(raw).expect("test_json is not valid JSON"),
            None => effective_test_value(annotation),
        };
        let reference = config_factory(
            make_config_from_file(merge_over_base(
                &base_config,
                yaml_path_to_json(canonical_path, injected_value.clone()),
            ))
            .await,
        );

        if reference == default_struct {
            failures.push(format!(
                "yaml_path '{}': struct did not change from its default—\
                 is the test value the same as the default, or is the key not wired up?",
                canonical_path,
            ));
            continue;
        }

        for yaml_path in annotation.additional_yaml_paths {
            let from_path = config_factory(
                make_config_from_file(merge_over_base(
                    &base_config,
                    yaml_path_to_json(yaml_path, injected_value.clone()),
                ))
                .await,
            );
            if from_path != reference {
                failures.push(format!(
                    "yaml_path '{}' produced a different struct than canonical yaml_path '{}'",
                    yaml_path, canonical_path,
                ));
            }
        }

        for env_var in annotation.effective_env_vars() {
            let value = json_value_to_env_string(&injected_value, annotation.value_type());
            let from_env = config_factory(make_config_from_env(&base_config, env_var, &value).await);
            if from_env != reference {
                failures.push(format!(
                    "env var '{}' produced a different struct than yaml_path '{}'",
                    env_var, canonical_path,
                ));
            }
        }
    }

    for annotation in SUPPORTED_ANNOTATIONS
        .iter()
        .filter(|a| !a.used_by.contains(&struct_name))
    {
        for yaml_path in annotation.all_yaml_paths() {
            let with_foreign = config_factory(
                make_config_from_file(merge_over_base(
                    &base_config,
                    yaml_path_to_json(yaml_path, test_json_value(annotation.value_type())),
                ))
                .await,
            );
            if with_foreign != default_struct {
                failures.push(format!(
                    "yaml_path '{}' is not registered for '{}' but unexpectedly changed the struct",
                    yaml_path, struct_name,
                ));
            }
        }
    }

    let mut all_vals = base_config.clone();
    for annotation in keys {
        let val = match annotation.test_json {
            Some(raw) => serde_json::from_str(raw).expect("test_json is not valid JSON"),
            None => effective_test_value(annotation),
        };
        saluki_config::upsert(&mut all_vals, annotation.yaml_path(), val);
    }
    let all_keys_struct = config_factory(make_config_from_file(all_vals).await);
    let full_map = serde_json::to_value(&all_keys_struct).expect("failed to serialize struct with all keys set");
    let default_map = serde_json::to_value(&default_struct).expect("failed to serialize default struct");
    let mut unchanged = Vec::new();
    collect_unchanged_leaves(&full_map, &default_map, "", &mut unchanged);
    unchanged.retain(|path| !non_config_fields.contains(&path.as_str()));
    if !unchanged.is_empty() {
        failures.push(format!(
            "{} serialized field(s) are never changed by any registered config key: [{}]\n  \
             Fix: add a SalukiAnnotation for each field and include '{}' in its used_by list.\n  \
             Fix: if a field is intentionally not config-driven (for example, injected at runtime), \
             add its serialized name to the `non_config_fields` slice in this test call.",
            unchanged.len(),
            unchanged.join(", "),
            struct_name,
        ));
    }

    if !failures.is_empty() {
        panic!(
            "config smoke tests for '{}' failed with {} error(s):\n\n{}",
            struct_name,
            failures.len(),
            failures
                .iter()
                .enumerate()
                .map(|(i, msg)| format!("  [{}] {}", i + 1, msg))
                .collect::<Vec<_>>()
                .join("\n\n"),
        );
    }
}

#[cfg(test)]
mod tests {
    //! Meta-tests for the [`run_config_smoke_tests`] harness itself.
    //!
    //! [`run_config_smoke_tests`] documents three guarantees (supported keys, unsupported keys, full
    //! field coverage). These tests verify the harness actually *enforces* each guarantee by feeding it a
    //! `config_factory` that deliberately violates exactly one and asserting the harness reports that
    //! guarantee's specific failure, plus one case where no guarantee is violated and the harness passes.
    //!
    //! We drive the negative cases against a struct name with no registered keys (so every registered key
    //! is "foreign") or an ignore-everything factory, rather than a real config type. Faithfully
    //! reproducing a *passing* struct here would require a real component config type, which lives in
    //! `saluki-components` and isn't a dependency of this crate; the guarantee-1 passing path is therefore
    //! left to the real per-component smoke tests that call this harness.

    use saluki_config::GenericConfiguration;
    use serde_json::json;

    use super::run_config_smoke_tests;
    use crate::config_registry::structs;

    /// Struct name that no annotation's `used_by` references, so every registered key is "foreign" to it.
    const UNREGISTERED_STRUCT: &str = "NonExistentConfiguration";

    fn panic_message(payload: Box<dyn std::any::Any + Send>) -> String {
        payload
            .downcast_ref::<String>()
            .cloned()
            .or_else(|| payload.downcast_ref::<&str>().map(|s| s.to_string()))
            .unwrap_or_else(|| "<non-string panic payload>".to_string())
    }

    #[tokio::test]
    async fn flags_a_supported_key_that_never_changes_the_struct() {
        // `DOGSTATSD_CONFIGURATION` has registered (supported) keys. A factory that ignores the config
        // entirely means each supported key "produces the default struct", violating the supported-key
        // guarantee, which the harness must flag.
        let outcome = tokio::spawn(async {
            run_config_smoke_tests(
                structs::DOGSTATSD_CONFIGURATION,
                &[],
                json!({}),
                |_cfg: GenericConfiguration| json!({}),
            )
            .await
        })
        .await;

        let panic = outcome.expect_err("harness should panic when a supported key never changes the struct");
        let message = panic_message(panic.into_panic());
        assert!(
            message.contains("did not change from its default"),
            "expected supported-key failure, got: {message}"
        );
    }

    #[tokio::test]
    async fn flags_a_foreign_key_that_changes_the_struct() {
        // For a struct with no registered keys, every key is foreign and must leave the struct at its
        // default. A factory that reflects the entire merged config changes for any foreign key, violating
        // the unsupported-key guarantee.
        let outcome = tokio::spawn(async {
            run_config_smoke_tests(UNREGISTERED_STRUCT, &[], json!({}), |cfg: GenericConfiguration| {
                cfg.as_typed::<serde_json::Value>().unwrap_or(serde_json::Value::Null)
            })
            .await
        })
        .await;

        let panic = outcome.expect_err("harness should panic when a foreign key changes the struct");
        let message = panic_message(panic.into_panic());
        assert!(
            message.contains("unexpectedly changed the struct"),
            "expected unsupported-key failure, got: {message}"
        );
    }

    #[tokio::test]
    async fn flags_a_serialized_field_no_key_ever_changes() {
        // A factory that always serializes a constant field means that field is never driven by any
        // registered key, violating the full-field-coverage guarantee.
        let outcome = tokio::spawn(async {
            run_config_smoke_tests(
                UNREGISTERED_STRUCT,
                &[],
                json!({}),
                |_cfg: GenericConfiguration| json!({ "phantom": "constant" }),
            )
            .await
        })
        .await;

        let panic = outcome.expect_err("harness should panic about a serialized field no key changes");
        let message = panic_message(panic.into_panic());
        assert!(
            message.contains("never changed by any registered config key"),
            "expected full-field-coverage failure, got: {message}"
        );
    }

    #[tokio::test]
    async fn passes_when_no_guarantee_is_violated() {
        // A factory that ignores every (foreign) key and serializes no fields satisfies both the
        // unsupported-key and full-field-coverage guarantees for a struct with no registered keys, so the
        // harness returns without panicking.
        run_config_smoke_tests(UNREGISTERED_STRUCT, &[], json!({}), |_cfg: GenericConfiguration| {
            json!({})
        })
        .await;
    }
}