nornir_rs/

lib.rs

#![cfg_attr(docsrs, feature(doc_cfg))]
//! Core types for describing Kore inventory models and transports.
//!
//! This crate is intentionally opinionated: every public structure mirrors the
//! flat data that Nornir (Python) consumes, so loaders, CLIs, and programmatic
//! callers can stitch together inventories without juggling bespoke schemas.
//! Whether the inventory originates from TOML files, HTTP APIs, or an adhoc
//! in-memory fixture, the goal is the same—normalize data into these structs,
//! merge them, and let higher layers run tasks with minimal ceremony.
//!
//! The types in this module power both the CLI binary shipped in this repo and
//! any downstream applications that want to embed Kore as a library.

pub mod builder;
pub mod cli;
pub mod collections;
pub mod config;
pub mod devices;
pub mod filter;
pub mod getters;
pub mod inventory;
pub mod nornir;
pub mod pipeline;
pub mod render;
pub mod sdk;
pub mod secrets;
pub mod tasks;
pub mod textfsm;
pub mod transport;
pub mod util;
pub mod vars;
pub mod vault;

use crate::util::env::{self, InterpolationMeta};
use clap::ValueEnum;
use indexmap::IndexMap;
use reqwest::Url;
use serde::{
    Deserialize, Serialize,
    de::{self, DeserializeOwned, Deserializer, Error as DeError},
};
use std::{
    collections::HashMap,
    fmt, fs,
    path::{Path, PathBuf},
    time::Duration,
};

/// CLI session mode requested by the task runner.
#[derive(Debug, Clone, Copy, ValueEnum)]
pub enum CliMode {
    /// Stay in exec/user mode.
    Exec,
    /// Elevate to enable/privileged mode.
    Enable,
    /// Enter configuration mode.
    Config,
}

impl<'de> serde::Deserialize<'de> for CliMode {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let raw = String::deserialize(deserializer)?;
        CliMode::from_str(&raw, true).map_err(DeError::custom)
    }
}

/// Generic key/value bag for metadata and user-defined variables.
///
/// Each [`Host`], [`Group`], and [`Defaults`] entry exposes a `data: Variables`
/// field so callers can stash arbitrary typed metadata alongside strongly-typed
/// credentials and connection parameters. The values gracefully accept any
/// serde-compatible JSON data, allowing hierarchies such as:
///
/// ```json
/// {
///   "site": "dc1",
///   "region": { "country": "US", "metro": "NYC" },
///   "maintenance": { "window": "sunday-night", "ticket": 1234 }
/// }
/// ```
///
/// These variables surface inside filters (`--filter data__site=dc1`) and are
/// preserved verbatim when inventories are serialized and reloaded.
pub type Variables = HashMap<String, serde_json::Value>;

/// Order-preserving map used for host/group inventories.
pub type OrderedMap<K, V> = IndexMap<K, V>;
/// Hosts keyed by name with deterministic iteration order.
pub type HostMap = OrderedMap<String, Host>;
/// Groups keyed by name with deterministic iteration order.
pub type GroupMap = OrderedMap<String, Group>;

/// Helper enum that lets hosts be specified as either a mapping or a sequence.
#[derive(Deserialize)]
#[serde(untagged)]
enum HostEntries {
    Map(HostMap),
    Seq(Vec<Host>),
}

/// Normalizes host entries by ensuring every host has a name and storing them
/// in a map keyed by name.
fn normalize_host_entries(entries: HostEntries) -> Result<HostMap, String> {
    match entries {
        HostEntries::Map(map) => {
            let mut normalized = HostMap::new();
            for (key, mut host) in map {
                if host.name.is_empty() {
                    host.name = key.clone();
                }
                if host.name.is_empty() {
                    return Err("host entry missing name".into());
                }
                normalized.insert(host.name.clone(), host);
            }
            Ok(normalized)
        }
        HostEntries::Seq(list) => {
            let mut normalized = HostMap::new();
            for host in list {
                if host.name.is_empty() {
                    return Err("host entry missing name".into());
                }
                normalized.insert(host.name.clone(), host);
            }
            Ok(normalized)
        }
    }
}

/// Custom deserializer that accepts hosts as either map or list form.
fn hosts_from_any<'de, D>(deserializer: D) -> Result<HostMap, D::Error>
where
    D: Deserializer<'de>,
{
    let entries = Option::<HostEntries>::deserialize(deserializer)?;
    match entries {
        Some(inner) => normalize_host_entries(inner).map_err(de::Error::custom),
        None => Ok(HostMap::new()),
    }
}

/// A fully materialized view of the network inventory.
///
/// [`Inventory`] is the lingua franca between every loader and consumer. File-,
/// HTTP-, or inline-based sources hydrate an `Inventory`, the builder merges
/// them, and finally executors read the resolved hosts/groups/defaults to wire
/// connections. The structure favors a flat, predictable layout so callers can
/// serialize it to YAML/JSON/TOML or manipulate it directly in Rust.
///
/// # Examples
/// Build a single-host inventory in-memory:
///
/// ```
/// use nornir_rs::{Host, Inventory};
///
/// let mut inventory = Inventory::default();
/// inventory.hosts.insert(
///     "rtr1".to_string(),
///     Host {
///         name: "rtr1".into(),
///         hostname: Some("10.0.0.1".into()),
///         platform: Some("iosxe".into()),
///         ..Host::default()
///     },
/// );
///
/// assert_eq!(inventory.host("rtr1").unwrap().hostname.as_deref(), Some("10.0.0.1"));
/// ```
///
/// Combine groups/defaults with host-specific overrides:
///
/// ```
/// # use nornir_rs::{
/// #     Credentials, Defaults, Group, Host, Inventory, InventoryBuilder, Secret, StaticInventorySource
/// # };
/// let mut inventory = Inventory::default();
/// inventory.defaults = Defaults {
///     credentials: Some(Credentials {
///         username: Some("netops".into()),
///         password: Some(Secret::new("hunter2")),
///         ..Credentials::default()
///     }),
///     ..Defaults::default()
/// };
/// inventory.groups.insert(
///     "core".into(),
///     Group {
///         name: "core".into(),
///         parents: vec![],
///         data: [("role".into(), serde_json::json!("core-router"))]
///             .into_iter()
///             .collect(),
///         ..Group::default()
///     },
/// );
/// inventory.hosts.insert(
///     "core-rt".into(),
///     Host {
///         name: "core-rt".into(),
///         hostname: Some("198.51.100.10".into()),
///         groups: vec!["core".into()],
///         ..Host::default()
///     },
/// );
///
/// let merged = InventoryBuilder::new()
///     .with_source(StaticInventorySource::new("inline", inventory))
///     .build()
///     .unwrap();
/// assert_eq!(
///     merged.host("core-rt").unwrap().credentials.as_ref().unwrap().username.as_deref(),
///     Some("netops")
/// );
/// ```
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct Inventory {
    /// All hosts keyed by logical name.
    #[serde(default, deserialize_with = "hosts_from_any")]
    pub hosts: HostMap,
    /// All groups keyed by logical name.
    #[serde(default)]
    pub groups: GroupMap,
    /// Defaults applied when hosts and groups omit a field.
    #[serde(default)]
    pub defaults: Defaults,
}

impl Inventory {
    /// Returns a host by name if it exists.
    ///
    /// Many helper APIs (filters, runners, tests) call this to grab a single
    /// host record after the builder has merged/normalized sources.
    pub fn host(&self, name: &str) -> Option<&Host> {
        self.hosts.get(name)
    }

    /// Layer another inventory on top of this one.
    ///
    /// Hosts, groups, and defaults are merged in place using intuitive
    /// precedence rules:
    ///
    /// * Hosts with the same name are merged field-by-field, so overriding
    ///   structures can selectively replace platform/connection details without
    ///   losing group membership.
    /// * Groups inherit parents and merged credentials/metadata when duplicates
    ///   appear.
    /// * Defaults act as the final fallback; the last merge wins.
    ///
    /// This mirrors how Nornir composes multiple SimpleInventory directories.
    pub fn merge(&mut self, other: Inventory) {
        for (name, host) in other.hosts {
            match self.hosts.get_mut(&name) {
                Some(existing) => existing.merge(host),
                None => {
                    self.hosts.insert(name, host);
                }
            }
        }

        for (name, group) in other.groups {
            match self.groups.get_mut(&name) {
                Some(existing) => existing.merge(group),
                None => {
                    self.groups.insert(name, group);
                }
            }
        }

        self.defaults.merge(other.defaults);
    }

    /// Applies defaults/groups to every host so downstream consumers see the
    /// fully merged view.
    fn apply_inheritance(&mut self) {
        let defaults = self.defaults.clone();
        let groups = self.groups.clone();
        for host in self.hosts.values_mut() {
            let original_creds = host.credentials.clone();
            let original_data = host.data.clone();
            let original_connections = host.connections.clone();

            apply_defaults(&defaults, host);
            apply_group_layers(&groups, host);

            if let Some(creds) = original_creds {
                match host.credentials.as_mut() {
                    Some(existing) => existing.merge(creds),
                    None => host.credentials = Some(creds),
                }
            }
            merge_connections(&mut host.connections, original_connections);
            merge_variables(&mut host.data, original_data);
        }
    }
}

/// Canonical representation of a network endpoint.
///
/// Hosts are intentionally lightweight: name, optional hostname, optional
/// platform, and a handful of connection/metadata fields. Groups/defaults fill
/// in missing values so this struct always reflects the fully merged view seen
/// by filters and task runners.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct Host {
    /// Logical host name.
    #[serde(default)]
    pub name: String,
    /// Reachable address or FQDN.
    pub hostname: Option<String>,
    /// Operating system or platform identifier.
    pub platform: Option<String>,
    /// TCP port to use when connecting.
    pub port: Option<u16>,
    /// Group names to inherit from.
    #[serde(default)]
    pub groups: Vec<String>,
    /// Inline credential overrides.
    pub credentials: Option<Credentials>,
    /// Transport connection settings keyed by transport id.
    #[serde(default)]
    pub connections: HashMap<String, TransportSettings>,
    /// User-defined metadata.
    #[serde(default)]
    pub data: Variables,
    /// Optional config capture overrides.
    pub config_store: Option<ConfigStoreOverride>,
}

impl Host {
    /// Merges another host (typically defaults or group material) into this one.
    fn merge(&mut self, other: Host) {
        if self.name.is_empty() {
            self.name = other.name;
        }
        if other.hostname.is_some() {
            self.hostname = other.hostname;
        }
        if other.platform.is_some() {
            self.platform = other.platform;
        }
        if other.port.is_some() {
            self.port = other.port;
        }
        for group in other.groups {
            if !self.groups.contains(&group) {
                self.groups.push(group);
            }
        }
        if let Some(creds) = other.credentials {
            match self.credentials.as_mut() {
                Some(existing) => existing.merge(creds),
                None => self.credentials = Some(creds),
            }
        }
        merge_connections(&mut self.connections, other.connections);
        merge_variables(&mut self.data, other.data);
        merge_config_store(&mut self.config_store, other.config_store);
    }
}

/// Per-host overrides when capturing configuration files (command, suffix, etc.).
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ConfigStoreOverride {
    pub command: Option<String>,
    pub default_command: Option<String>,
}

impl ConfigStoreOverride {
    fn merge(&mut self, other: ConfigStoreOverride) {
        if other.command.is_some() {
            self.command = other.command;
        }
        if other.default_command.is_some() {
            self.default_command = other.default_command;
        }
    }
}

/// Applies an incoming config-store override onto an existing option.
fn merge_config_store(
    target: &mut Option<ConfigStoreOverride>,
    incoming: Option<ConfigStoreOverride>,
) {
    if let Some(incoming) = incoming {
        match target {
            Some(existing) => existing.merge(incoming),
            None => *target = Some(incoming),
        }
    }
}

/// Applies a [`Defaults`] record to the host.
fn apply_defaults(defaults: &Defaults, host: &mut Host) {
    if let Some(creds) = defaults.credentials.clone() {
        match host.credentials.as_mut() {
            Some(existing) => existing.merge(creds),
            None => host.credentials = Some(creds),
        }
    }
    merge_connections(&mut host.connections, defaults.connections.clone());
    merge_variables(&mut host.data, defaults.data.clone());
    merge_config_store(&mut host.config_store, defaults.config_store.clone());
}

/// Walks the group hierarchy and applies every group's settings to the host.
fn apply_group_layers(groups: &GroupMap, host: &mut Host) {
    let mut visited = std::collections::HashSet::new();
    for group_name in host.groups.clone() {
        apply_group_recursive(host, &group_name, groups, &mut visited);
    }
}

/// Recursively applies a group's parents before merging the group's data.
fn apply_group_recursive(
    host: &mut Host,
    name: &str,
    groups: &GroupMap,
    visited: &mut std::collections::HashSet<String>,
) {
    if !visited.insert(name.to_string()) {
        return;
    }
    let Some(group) = groups.get(name) else {
        return;
    };

    for parent in &group.parents {
        apply_group_recursive(host, parent, groups, visited);
    }

    if let Some(creds) = group.credentials.clone() {
        match host.credentials.as_mut() {
            Some(existing) => existing.merge(creds),
            None => host.credentials = Some(creds),
        }
    }
    merge_connections(&mut host.connections, group.connections.clone());
    merge_variables(&mut host.data, group.data.clone());
    merge_config_store(&mut host.config_store, group.config_store.clone());
}

/// Collection of hosts that share credentials, connection tuning, or metadata.
///
/// Groups can inherit from parent groups (think: hierarchy of "dc" → "pod" →
/// "role") and every host listed in `groups` automatically benefits from those
/// shared settings. This is how you implement “all edge routers use this SSH
/// key” or “everything in dc1 has `data.region = us-east`”.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct Group {
    /// Logical group name.
    #[serde(default)]
    pub name: String,
    /// Parent group names to inherit from.
    #[serde(default)]
    pub parents: Vec<String>,
    /// Shared credential overrides.
    pub credentials: Option<Credentials>,
    /// Shared transport options keyed by transport id.
    #[serde(default)]
    pub connections: HashMap<String, TransportSettings>,
    /// Arbitrary metadata.
    #[serde(default)]
    pub data: Variables,
    /// Optional config capture overrides.
    pub config_store: Option<ConfigStoreOverride>,
}

impl Group {
    fn merge(&mut self, other: Group) {
        if self.name.is_empty() {
            self.name = other.name;
        }
        for parent in other.parents {
            if !self.parents.contains(&parent) {
                self.parents.push(parent);
            }
        }
        if let Some(creds) = other.credentials {
            match self.credentials.as_mut() {
                Some(existing) => existing.merge(creds),
                None => self.credentials = Some(creds),
            }
        }
        merge_connections(&mut self.connections, other.connections);
        merge_variables(&mut self.data, other.data);
        merge_config_store(&mut self.config_store, other.config_store);
    }
}

/// Global fallbacks applied to every host after groups inherit.
///
/// In practice this is where you place organization-wide credentials,
/// connection timeouts, or metadata such as `owner`, `environment`, or
/// `ticketing_queue`. Hosts and groups can still override fields; defaults are
/// only consulted when the more specific layers leave them empty.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct Defaults {
    /// Baseline credentials.
    pub credentials: Option<Credentials>,
    /// Baseline connection settings per transport.
    #[serde(default)]
    pub connections: HashMap<String, TransportSettings>,
    /// Baseline metadata.
    #[serde(default)]
    pub data: Variables,
    /// Optional config capture overrides applied to all hosts.
    pub config_store: Option<ConfigStoreOverride>,
}

impl Defaults {
    fn merge(&mut self, other: Defaults) {
        if let Some(creds) = other.credentials {
            match self.credentials.as_mut() {
                Some(existing) => existing.merge(creds),
                None => self.credentials = Some(creds),
            }
        }
        merge_connections(&mut self.connections, other.connections);
        merge_variables(&mut self.data, other.data);
    }
}

/// Authentication material shared by hosts, groups, and defaults.
///
/// All fields are optional to allow layered overrides. For example, defaults
/// can supply the username while a specific host overrides the private key.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct Credentials {
    /// Login username.
    pub username: Option<String>,
    /// Password or passphrase.
    pub password: Option<Secret>,
    /// Private key material or reference.
    pub private_key: Option<Secret>,
    /// Enable-mode secret used for privilege escalation (e.g., Cisco `enable`).
    pub enable_secret: Option<Secret>,
}

impl Credentials {
    fn merge(&mut self, other: Credentials) {
        if other.username.is_some() {
            self.username = other.username;
        }
        if other.password.is_some() {
            self.password = other.password;
        }
        if other.private_key.is_some() {
            self.private_key = other.private_key;
        }
        if other.enable_secret.is_some() {
            self.enable_secret = other.enable_secret;
        }
    }
}

/// Basic representation of sensitive text.
///
/// Secrets are intentionally lightweight. They exist to make field intent
/// explicit while still allowing serde to (de)serialize them. Consumers are
/// free to encrypt the contents before serialization and set `encrypted = true`
/// so downstream tooling can decide whether/how to decrypt them.

#[derive(Debug, Clone, Serialize, Default)]
pub struct Secret {
    /// Cleartext or encrypted payload; callers decide how to manage it.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub value: Option<String>,
    /// Whether the value still requires decryption.
    #[serde(default)]
    pub encrypted: bool,
    /// Optional reference resolved via a secrets provider.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reference: Option<SecretReference>,
}

impl Secret {
    /// Creates a new plaintext secret.
    pub fn new(value: impl Into<String>) -> Self {
        Self {
            value: Some(value.into()),
            encrypted: false,
            reference: None,
        }
    }

    /// Returns the inline value when present.
    pub fn as_str(&self) -> Option<&str> {
        self.value.as_deref()
    }
}

#[derive(Deserialize)]
#[serde(untagged)]
enum SecretRepr {
    String(String),
    Map(SecretFields),
}

#[derive(Deserialize, Default)]
struct SecretFields {
    #[serde(default)]
    value: Option<String>,
    #[serde(default)]
    encrypted: bool,
    #[serde(rename = "ref")]
    reference_key: Option<String>,
    #[serde(default)]
    provider: Option<String>,
    #[serde(default)]
    optional: Option<bool>,
    #[serde(default)]
    reference: Option<SecretReferenceRepr>,
}

#[derive(Deserialize)]
#[serde(untagged)]
enum SecretReferenceRepr {
    String(String),
    Map(SecretReferenceFields),
}

#[derive(Deserialize, Default)]
struct SecretReferenceFields {
    #[serde(rename = "ref")]
    key_ref: Option<String>,
    #[serde(default)]
    key: Option<String>,
    #[serde(default)]
    provider: Option<String>,
    #[serde(default)]
    optional: Option<bool>,
}

impl SecretReferenceRepr {
    fn into_reference(self) -> Result<SecretReference, String> {
        match self {
            SecretReferenceRepr::String(key) => Ok(SecretReference {
                provider: None,
                key,
                optional: false,
            }),
            SecretReferenceRepr::Map(fields) => {
                let key = fields
                    .key
                    .or(fields.key_ref)
                    .ok_or_else(|| "reference requires a key".to_string())?;
                Ok(SecretReference {
                    provider: fields.provider,
                    key,
                    optional: fields.optional.unwrap_or(false),
                })
            }
        }
    }
}

impl<'de> Deserialize<'de> for Secret {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        match SecretRepr::deserialize(deserializer)? {
            SecretRepr::String(value) => Ok(Secret {
                value: Some(value),
                encrypted: false,
                reference: None,
            }),
            SecretRepr::Map(fields) => {
                let mut reference = if let Some(raw) = fields.reference {
                    Some(raw.into_reference().map_err(de::Error::custom)?)
                } else {
                    None
                };
                if reference.is_none() {
                    if let Some(key) = fields.reference_key.clone() {
                        reference = Some(SecretReference {
                            provider: fields.provider.clone(),
                            key,
                            optional: fields.optional.unwrap_or(false),
                        });
                    }
                } else if let Some(ref mut reference) = reference {
                    if reference.provider.is_none() {
                        reference.provider = fields.provider.clone();
                    }
                    if let Some(optional) = fields.optional {
                        reference.optional = optional;
                    }
                }
                if fields.provider.is_some() && reference.is_none() {
                    return Err(de::Error::custom(
                        "secret provider requires a matching ref".to_string(),
                    ));
                }
                if fields.value.is_none() && reference.is_none() {
                    return Err(de::Error::custom(
                        "secret requires either value or ref".to_string(),
                    ));
                }
                Ok(Secret {
                    value: fields.value,
                    encrypted: fields.encrypted,
                    reference,
                })
            }
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SecretReference {
    /// Optional provider identifier (maps to entries in `secrets.providers`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub provider: Option<String>,
    /// Provider-specific key or lookup reference.
    #[serde(rename = "ref")]
    pub key: String,
    /// Whether missing references should be tolerated.
    #[serde(default)]
    pub optional: bool,
}

impl SecretReference {
    /// Convenience constructor for plain references without providers.
    pub fn new(key: impl Into<String>) -> Self {
        Self {
            provider: None,
            key: key.into(),
            optional: false,
        }
    }
}

/// Transport-specific configuration.
///
/// Each entry describes how to instantiate a particular transport (SSH, HTTP,
/// mock, etc.) for a host. The `transport` field names the registered factory,
/// and `params` holds the JSON-serializable options that the factory expects.
/// By keeping the payload loosely typed, inventories can express vendor-specific
/// knobs without bloating the core schema.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct TransportSettings {
    /// Transport identifier (e.g., "ssh", "netmiko").
    pub transport: String,
    /// Flat map of key/value settings consumed by the transport.
    #[serde(default)]
    pub params: Variables,
}

impl TransportSettings {
    /// Deserializes the parameter map into a strongly typed configuration.
    ///
    /// # Examples
    /// ```
    /// use nornir_rs::{TransportSettings, Variables};
    /// use serde::Deserialize;
    ///
    /// #[derive(Debug, Deserialize, PartialEq)]
    /// struct SshConfig {
    ///     username: String,
    ///     timeout: Option<u64>,
    /// }
    ///
    /// let mut params = Variables::default();
    /// params.insert("username".into(), serde_json::json!("netops"));
    /// params.insert("timeout".into(), serde_json::json!(30));
    ///
    /// let settings = TransportSettings {
    ///     transport: "ssh".into(),
    ///     params,
    /// };
    ///
    /// let parsed: SshConfig = settings.params_as().unwrap();
    /// assert_eq!(
    ///     parsed,
    ///     SshConfig {
    ///         username: "netops".into(),
    ///         timeout: Some(30)
    ///     }
    /// );
    /// ```
    pub fn params_as<T>(&self) -> Result<T, serde_json::Error>
    where
        T: DeserializeOwned,
    {
        let map = serde_json::Map::from_iter(self.params.clone());
        serde_json::from_value(serde_json::Value::Object(map))
    }
}

/// Merges transport settings, letting incoming values override the existing map.
fn merge_connections(
    existing: &mut HashMap<String, TransportSettings>,
    incoming: HashMap<String, TransportSettings>,
) {
    for (name, mut settings) in incoming {
        match existing.get_mut(&name) {
            Some(current) => {
                if settings.transport.is_empty() {
                    settings.transport = current.transport.clone();
                }
                if !settings.transport.is_empty() {
                    current.transport = settings.transport;
                }
                merge_variables(&mut current.params, settings.params);
            }
            None => {
                existing.insert(name, settings);
            }
        }
    }
}

/// Shallowly merges arbitrary metadata maps.
fn merge_variables(existing: &mut Variables, incoming: Variables) {
    for (k, v) in incoming {
        existing.insert(k, v);
    }
}

/// Errors raised by inventory loaders and builders.
///
/// Parsing and IO code funnels failures through this enum so callers receive
/// actionable diagnostics regardless of the backing source (files, HTTP,
/// custom implementations). The CLI surfaces these messages verbatim to help
/// contributors fix broken inventories quickly.
#[derive(Debug)]
pub enum InventoryError {
    /// Underlying file or network IO failure.
    Io(std::io::Error),
    /// HTTP request failed (connection errors, non-success status, etc.).
    Http(reqwest::Error),
    /// Structured data parsing error.
    Parse(String),
}

impl fmt::Display for InventoryError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            InventoryError::Io(err) => write!(f, "io error: {}", err),
            InventoryError::Http(err) => write!(f, "http error: {}", err),
            InventoryError::Parse(msg) => write!(f, "parse error: {}", msg),
        }
    }
}

impl std::error::Error for InventoryError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            InventoryError::Io(err) => Some(err),
            InventoryError::Http(err) => Some(err),
            InventoryError::Parse(_) => None,
        }
    }
}

impl From<std::io::Error> for InventoryError {
    fn from(value: std::io::Error) -> Self {
        InventoryError::Io(value)
    }
}

impl From<reqwest::Error> for InventoryError {
    fn from(value: reqwest::Error) -> Self {
        InventoryError::Http(value)
    }
}

/// Unified interface for inventory data sources.
///
/// Implementors may pull data from files, HTTP endpoints, databases, or
/// in-memory fixtures. Each source emits a fully merged [`Inventory`] snapshot
/// representing *just that source*. The [`InventoryBuilder`] then layers the
/// snapshots in order, making it trivial to stack defaults, groups, adhoc test
/// records, and remote inventories without worrying about parsing details in
/// consumer code.
pub trait InventorySource: Send + Sync {
    /// Loads inventory data.
    fn load(&self) -> Result<Inventory, InventoryError>;

    /// Human-friendly identifier for logging/observability.
    fn name(&self) -> &str;
}

/// Builder that merges multiple inventory sources.
///
/// Most callers never construct an [`Inventory`] manually. Instead, they add one
/// or more [`InventorySource`] implementations to the builder and let it merge
/// them in order, applying group/default inheritance once everything is loaded.
/// This mirrors how the CLI layers `defaults.yaml`, `groups.yaml`, and
/// `hosts.yaml` (plus optional HTTP responses) into a single view before
/// running tasks.
///
/// # Examples
/// ```
/// use nornir_rs::{Host, Inventory, InventoryBuilder, StaticInventorySource};
///
/// let mut inventory = Inventory::default();
/// inventory.hosts.insert(
///     "sw1".into(),
///     Host {
///         name: "sw1".into(),
///         hostname: Some("10.0.0.11".into()),
///         ..Host::default()
///     },
/// );
///
/// let built = InventoryBuilder::new()
///     .with_source(StaticInventorySource::new("memory", inventory))
///     .build()
///     .unwrap();
///
/// assert!(built.host("sw1").is_some());
/// ```
#[derive(Default)]
pub struct InventoryBuilder {
    sources: Vec<Box<dyn InventorySource>>,
}

impl InventoryBuilder {
    /// Starts a new builder with no sources.
    pub fn new() -> Self {
        Self::default()
    }

    /// Adds an inventory source, returning the builder for chaining.
    ///
    /// Use this in fluent style when composing multiple loaders:
    ///
    /// ```
    /// # use nornir_rs::{InventoryBuilder, StaticInventorySource, Inventory};
    /// # fn build_inline() -> Inventory { Inventory::default() }
    /// let builder = InventoryBuilder::new()
    ///     .with_source(StaticInventorySource::new("inline", build_inline()));
    /// let inventory = builder.build().unwrap();
    /// assert_eq!(inventory.hosts.len(), 0);
    /// ```
    pub fn with_source(mut self, source: impl InventorySource + 'static) -> Self {
        self.sources.push(Box::new(source));
        self
    }

    /// Adds an inventory source without consuming the builder.
    ///
    /// Useful when sources are determined dynamically (e.g., reading a plugin
    /// list at runtime or iterating over multiple directories).
    pub fn add_source(&mut self, source: impl InventorySource + 'static) {
        self.sources.push(Box::new(source));
    }

    /// Loads and merges all registered sources in order.
    ///
    /// Each source is loaded eagerly; failures bubble up immediately with an
    /// [`InventoryError`], so callers can surface useful diagnostics. After all
    /// sources succeed, the builder applies group/default inheritance so the
    /// resulting [`Inventory`] is ready for filtering and task execution.
    pub fn build(mut self) -> Result<Inventory, InventoryError> {
        let mut inventory = Inventory::default();
        for source in self.sources.drain(..) {
            let data = source.load()?;
            inventory.merge(data);
        }
        inventory.apply_inheritance();
        Ok(inventory)
    }
}

/// In-memory helper useful for tests, fixtures, and doc examples.
///
/// # Examples
/// ```
/// use nornir_rs::{Host, Inventory, InventorySource, StaticInventorySource};
///
/// let mut inventory = Inventory::default();
/// inventory.hosts.insert(
///     "r1".into(),
///     Host {
///         name: "r1".into(),
///         hostname: Some("10.0.0.1".into()),
///         ..Host::default()
///     },
/// );
///
/// let source = StaticInventorySource::new("inline", inventory);
/// let loaded = source.load().unwrap();
/// assert!(loaded.host("r1").is_some());
/// ```
/// In-memory implementation of [`InventorySource`] useful for tests, fixtures,
/// or precomputed inventories.
pub struct StaticInventorySource {
    name: String,
    inventory: Inventory,
}

impl StaticInventorySource {
    /// Creates a new source with a descriptive name.
    pub fn new(name: impl Into<String>, inventory: Inventory) -> Self {
        Self {
            name: name.into(),
            inventory,
        }
    }
}

impl InventorySource for StaticInventorySource {
    fn load(&self) -> Result<Inventory, InventoryError> {
        Ok(self.inventory.clone())
    }

    fn name(&self) -> &str {
        &self.name
    }
}

/// Supported file formats when loading from disk or HTTP.
///
/// The loader automatically infers formats from file extensions or explicit
/// labels and uses serde under the hood to deserialize them into [`Inventory`]
/// structures.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum InventoryFormat {
    Yaml,
    Json,
    Toml,
}

impl InventoryFormat {
    /// Infers format from a filesystem path using the extension.
    fn from_path(path: &Path) -> Option<Self> {
        path.extension()
            .and_then(|ext| ext.to_str())
            .and_then(Self::from_label)
    }

    /// Attempts to parse a file extension (without dot) into a format.
    pub fn from_extension(ext: &str) -> Option<Self> {
        match ext {
            "yaml" | "yml" => Some(InventoryFormat::Yaml),
            "json" => Some(InventoryFormat::Json),
            "toml" => Some(InventoryFormat::Toml),
            _ => None,
        }
    }

    /// Parses a user-provided label such as "yaml" or "json".
    pub fn from_label(label: &str) -> Option<Self> {
        let lowered = label.trim().to_ascii_lowercase();
        Self::from_extension(lowered.as_str())
    }
}

/// Reads inventory data from a file path.
///
/// # Examples
/// ```
/// use nornir_rs::{FileInventorySource, InventoryFormat, InventorySource};
/// use tempfile::NamedTempFile;
/// use std::io::Write;
///
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let mut file = NamedTempFile::new()?;
/// writeln!(
///     file,
///     r#"
/// hosts:
///   r1:
///     name: r1
///     hostname: 10.0.0.5
/// "#
/// )?;
///
/// let source = FileInventorySource::new(file.path(), InventoryFormat::Yaml);
/// let inventory = source.load()?;
/// assert_eq!(
///     inventory.host("r1").unwrap().hostname.as_deref(),
///     Some("10.0.0.5")
/// );
/// # Ok(())
/// # }
/// ```
/// Loads inventory documents from disk using serde.
pub struct FileInventorySource {
    path: PathBuf,
    format: InventoryFormat,
    name: String,
}

impl FileInventorySource {
    /// Creates a source inferring format from the file extension.
    pub fn infer(path: impl Into<PathBuf>) -> Result<Self, InventoryError> {
        let path = path.into();
        let format = InventoryFormat::from_path(&path).ok_or_else(|| {
            InventoryError::Parse(format!("unsupported file extension for {}", path.display()))
        })?;

        Ok(Self {
            name: path.display().to_string(),
            path,
            format,
        })
    }

    /// Creates a source using an explicit format.
    pub fn new(path: impl Into<PathBuf>, format: InventoryFormat) -> Self {
        let path = path.into();
        Self {
            name: path.display().to_string(),
            path,
            format,
        }
    }
}

/// Helper that annotates IO errors with the offending path for better logs.
fn io_error_with_path(err: std::io::Error, path: &Path) -> std::io::Error {
    let message = format!("{} ({})", err, path.display());
    std::io::Error::new(err.kind(), message)
}

impl InventorySource for FileInventorySource {
    fn load(&self) -> Result<Inventory, InventoryError> {
        let raw = fs::read_to_string(&self.path)
            .map_err(|err| InventoryError::Io(io_error_with_path(err, &self.path)))?;
        let meta = InterpolationMeta::for_path(&self.path);
        let processed = env::interpolate_with_meta(&raw, Some(&meta))
            .map_err(|err| InventoryError::Parse(err.to_string()))?;
        let inventory = match self.format {
            InventoryFormat::Yaml => serde_yaml::from_str(&processed)
                .map_err(|err| InventoryError::Parse(err.to_string()))?,
            InventoryFormat::Json => serde_json::from_str(&processed)
                .map_err(|err| InventoryError::Parse(err.to_string()))?,
            InventoryFormat::Toml => {
                toml::from_str(&processed).map_err(|err| InventoryError::Parse(err.to_string()))?
            }
        };
        Ok(inventory)
    }

    fn name(&self) -> &str {
        &self.name
    }
}

/// Loads hosts/groups/defaults from separate files and merges them.
///
/// This mirrors Nornir’s `SimpleInventory` layout where each YAML file plays a
/// specific role. Environment variable tokens (`${VAR}`) inside the files are
/// interpolated automatically, making it trivial to keep sensitive values out
/// of version control.
///
/// # Examples
/// ```
/// use nornir_rs::{CompositeFileInventorySource, InventorySource};
/// use std::fs;
/// use tempfile::tempdir;
///
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let dir = tempdir()?;
/// let hosts_path = dir.path().join("hosts.yaml");
/// let groups_path = dir.path().join("groups.yaml");
///
/// fs::write(
///     &hosts_path,
///     "r1:\n  hostname: 10.0.0.10\n  groups: [core]\n",
/// )?;
/// fs::write(
///     &groups_path,
///     "core:\n  data:\n    role: access\n",
/// )?;
///
/// let inventory = CompositeFileInventorySource::new()
///     .hosts(&hosts_path)?
///     .groups(&groups_path)?
///     .load()?;
///
/// assert_eq!(
///     inventory.host("r1").unwrap().hostname.as_deref(),
///     Some("10.0.0.10")
/// );
/// assert_eq!(
///     inventory.groups.get("core").unwrap().data.get("role").unwrap(),
///     "access"
/// );
/// # Ok(())
/// # }
/// ```
/// Inventory source that loads separate hosts/groups/defaults files and merges
/// them into a single [`Inventory`].
pub struct CompositeFileInventorySource {
    hosts: Option<(PathBuf, InventoryFormat)>,
    groups: Option<(PathBuf, InventoryFormat)>,
    defaults: Option<(PathBuf, InventoryFormat)>,
    name: String,
}

impl Default for CompositeFileInventorySource {
    fn default() -> Self {
        Self::new()
    }
}

impl CompositeFileInventorySource {
    /// Creates a new source with no files configured.
    pub fn new() -> Self {
        Self {
            hosts: None,
            groups: None,
            defaults: None,
            name: "composite-files".into(),
        }
    }

    /// Sets the 'hosts' file.
    pub fn hosts(mut self, path: impl Into<PathBuf>) -> Result<Self, InventoryError> {
        let path = path.into();
        let format = InventoryFormat::from_path(&path).ok_or_else(|| {
            InventoryError::Parse(format!(
                "unsupported host file extension for {}",
                path.display()
            ))
        })?;
        self.hosts = Some((path, format));
        Ok(self)
    }

    /// Sets the groups file.
    pub fn groups(mut self, path: impl Into<PathBuf>) -> Result<Self, InventoryError> {
        let path = path.into();
        let format = InventoryFormat::from_path(&path).ok_or_else(|| {
            InventoryError::Parse(format!(
                "unsupported group file extension for {}",
                path.display()
            ))
        })?;
        self.groups = Some((path, format));
        Ok(self)
    }

    /// Sets the defaults file.
    pub fn defaults(mut self, path: impl Into<PathBuf>) -> Result<Self, InventoryError> {
        let path = path.into();
        let format = InventoryFormat::from_path(&path).ok_or_else(|| {
            InventoryError::Parse(format!(
                "unsupported defaults file extension for {}",
                path.display()
            ))
        })?;
        self.defaults = Some((path, format));
        Ok(self)
    }
}

impl InventorySource for CompositeFileInventorySource {
    fn load(&self) -> Result<Inventory, InventoryError> {
        let mut inventory = Inventory::default();

        if let Some((path, format)) = &self.hosts {
            let raw = fs::read_to_string(path)
                .map_err(|err| InventoryError::Io(io_error_with_path(err, path)))?;
            let meta = InterpolationMeta::for_path(path);
            let processed = env::interpolate_with_meta(&raw, Some(&meta))
                .map_err(|err| InventoryError::Parse(err.to_string()))?;
            let hosts = parse_hosts_document(&processed, *format)?;
            inventory.hosts.extend(hosts);
        }

        if let Some((path, format)) = &self.groups {
            let groups_map = fs::read_to_string(path)
                .map_err(|err| InventoryError::Io(io_error_with_path(err, path)))?;
            let meta = InterpolationMeta::for_path(path);
            let groups_map = env::interpolate_with_meta(&groups_map, Some(&meta))
                .map_err(|err| InventoryError::Parse(err.to_string()))?;
            let groups: GroupMap = match format {
                InventoryFormat::Yaml => serde_yaml::from_str(&groups_map)
                    .map_err(|err| InventoryError::Parse(err.to_string()))?,
                InventoryFormat::Json => serde_json::from_str(&groups_map)
                    .map_err(|err| InventoryError::Parse(err.to_string()))?,
                InventoryFormat::Toml => toml::from_str(&groups_map)
                    .map_err(|err| InventoryError::Parse(err.to_string()))?,
            };
            for (name, mut group) in groups.into_iter() {
                if group.name.is_empty() {
                    group.name = name.clone();
                }
                inventory.groups.insert(name, group);
            }
        }

        if let Some((path, format)) = &self.defaults {
            let raw = fs::read_to_string(path)
                .map_err(|err| InventoryError::Io(io_error_with_path(err, path)))?;
            let meta = InterpolationMeta::for_path(path);
            let raw = env::interpolate_with_meta(&raw, Some(&meta))
                .map_err(|err| InventoryError::Parse(err.to_string()))?;
            let defaults: Defaults = match format {
                InventoryFormat::Yaml => serde_yaml::from_str(&raw)
                    .map_err(|err| InventoryError::Parse(err.to_string()))?,
                InventoryFormat::Json => serde_json::from_str(&raw)
                    .map_err(|err| InventoryError::Parse(err.to_string()))?,
                InventoryFormat::Toml => {
                    toml::from_str(&raw).map_err(|err| InventoryError::Parse(err.to_string()))?
                }
            };
            inventory.defaults = defaults;
        }

        Ok(inventory)
    }

    fn name(&self) -> &str {
        &self.name
    }
}

/// Parses a host document (YAML/JSON/TOML) into the canonical host map.
fn parse_hosts_document(raw: &str, format: InventoryFormat) -> Result<HostMap, InventoryError> {
    let entries = match format {
        InventoryFormat::Yaml => serde_yaml::from_str::<HostEntries>(raw)
            .map_err(|err| InventoryError::Parse(err.to_string()))?,
        InventoryFormat::Json => serde_json::from_str::<HostEntries>(raw)
            .map_err(|err| InventoryError::Parse(err.to_string()))?,
        InventoryFormat::Toml => toml::from_str::<HostEntries>(raw)
            .map_err(|err| InventoryError::Parse(err.to_string()))?,
    };
    normalize_host_entries(entries).map_err(InventoryError::Parse)
}

/// Fetches inventory data from an HTTP endpoint.
///
/// Perfect for dynamic inventories backed by CMDBs, GraphQL, REST APIs, or
/// static web-hosted files. The client eagerly fetches the document,
/// interpolates environment variables, and parses it using the requested
/// [`InventoryFormat`]. Convenience builders make it easy to add headers or
/// authentication inline—ideal for CI pipelines or tooling that needs to
/// refresh inventory snapshots periodically.
///
/// # Examples
/// ```no_run
/// use nornir_rs::{HttpInventorySource, InventoryFormat};
///
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let source = HttpInventorySource::new("https://example.com/inventory", InventoryFormat::Json)?;
/// // Configure headers or TLS options here.
/// let _source = source.with_header("Authorization", "Bearer <token>");
/// # Ok(())
/// # }
/// ```
pub struct HttpInventorySource {
    client: reqwest::blocking::Client,
    url: String,
    format: InventoryFormat,
    headers: Vec<(String, String)>,
    auth: Option<HttpAuth>,
}

#[derive(Debug, Clone)]
enum HttpAuth {
    Basic { username: String, password: String },
    Bearer { token: String },
}

impl HttpInventorySource {
    /// Creates a source that fetches data from `url` and parses it using `format`.
    pub fn new(url: impl Into<String>, format: InventoryFormat) -> Result<Self, InventoryError> {
        Ok(Self {
            client: reqwest::blocking::Client::new(),
            url: url.into(),
            format,
            headers: Vec::new(),
            auth: None,
        })
    }

    /// Adds an HTTP header to the GET request.
    pub fn with_header(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.headers.push((key.into(), value.into()));
        self
    }

    /// Configures HTTP basic authentication.
    pub fn with_basic_auth(
        mut self,
        username: impl Into<String>,
        password: impl Into<String>,
    ) -> Self {
        self.auth = Some(HttpAuth::Basic {
            username: username.into(),
            password: password.into(),
        });
        self
    }

    /// Configures bearer token authentication.
    pub fn with_bearer_token(mut self, token: impl Into<String>) -> Self {
        self.auth = Some(HttpAuth::Bearer {
            token: token.into(),
        });
        self
    }

    /// Adds an API key header (e.g., `X-API-Key`).
    pub fn with_api_key(mut self, header: impl Into<String>, value: impl Into<String>) -> Self {
        self.headers.push((header.into(), value.into()));
        self
    }
}

impl InventorySource for HttpInventorySource {
    fn load(&self) -> Result<Inventory, InventoryError> {
        let mut request = self.client.get(&self.url);
        for (key, value) in &self.headers {
            request = request.header(key, value);
        }
        if let Some(auth) = &self.auth {
            match auth {
                HttpAuth::Basic { username, password } => {
                    request = request.basic_auth(username, Some(password));
                }
                HttpAuth::Bearer { token } => {
                    request = request.bearer_auth(token);
                }
            }
        }
        let response = request.send()?.error_for_status()?;
        let body = response.text()?;
        parse_inventory_body(self.format, &body)
    }

    fn name(&self) -> &str {
        &self.url
    }
}

/// Deserializes an inventory document fetched from HTTP.
fn parse_inventory_body(format: InventoryFormat, body: &str) -> Result<Inventory, InventoryError> {
    match format {
        InventoryFormat::Yaml => {
            serde_yaml::from_str(body).map_err(|err| InventoryError::Parse(err.to_string()))
        }
        InventoryFormat::Json => {
            serde_json::from_str(body).map_err(|err| InventoryError::Parse(err.to_string()))
        }
        InventoryFormat::Toml => {
            toml::from_str(body).map_err(|err| InventoryError::Parse(err.to_string()))
        }
    }
}

const NAUTOBOT_DEVICES_ENDPOINT: &str = "dcim/devices/";
const NAUTOBOT_VMS_ENDPOINT: &str = "virtualization/virtual-machines/";
const NAUTOBOT_DEFAULT_DEPTH: &str = "1";
const NETBOX_DEVICES_ENDPOINT: &str = "api/dcim/devices/";
const NETBOX_VMS_ENDPOINT: &str = "api/virtualization/virtual-machines/";
const NETBOX_PLATFORMS_ENDPOINT: &str = "api/dcim/platforms/";

/// Configuration consumed by the Nautobot inventory source.
pub struct NautobotInventoryConfig {
    pub base_url: String,
    pub token: String,
    pub verify_tls: bool,
    pub timeout: Duration,
    pub include_virtual_machines: bool,
    pub flatten_custom_fields: bool,
    pub tags_as_groups: bool,
    pub sites_as_groups: bool,
    pub roles_as_groups: bool,
    pub tenants_as_groups: bool,
    pub page_size: u32,
    pub device_filters: Vec<(String, String)>,
    pub virtual_machine_filters: Vec<(String, String)>,
}

/// Inventory source that pulls devices/VMs from Nautobot's REST API.
pub struct NautobotInventorySource {
    client: reqwest::blocking::Client,
    base_url: Url,
    token: String,
    include_virtual_machines: bool,
    flatten_custom_fields: bool,
    tags_as_groups: bool,
    sites_as_groups: bool,
    roles_as_groups: bool,
    tenants_as_groups: bool,
    page_size: u32,
    device_filters: Vec<(String, String)>,
    vm_filters: Vec<(String, String)>,
}

impl NautobotInventorySource {
    /// Creates a new source using the provided configuration.
    pub fn new(config: NautobotInventoryConfig) -> Result<Self, InventoryError> {
        let mut builder = reqwest::blocking::Client::builder()
            .timeout(config.timeout)
            .user_agent("kore/nautobot");
        if !config.verify_tls {
            builder = builder.danger_accept_invalid_certs(true);
        }
        let client = builder.build()?;
        let base_url = Url::parse(&config.base_url)
            .map_err(|err| InventoryError::Parse(format!("invalid Nautobot url: {err}")))?;
        Ok(Self {
            client,
            base_url,
            token: config.token,
            include_virtual_machines: config.include_virtual_machines,
            flatten_custom_fields: config.flatten_custom_fields,
            tags_as_groups: config.tags_as_groups,
            sites_as_groups: config.sites_as_groups,
            roles_as_groups: config.roles_as_groups,
            tenants_as_groups: config.tenants_as_groups,
            page_size: config.page_size.max(1),
            device_filters: config.device_filters,
            vm_filters: config.virtual_machine_filters,
        })
    }

    fn fetch_collection(
        &self,
        endpoint: &str,
        filters: &[(String, String)],
    ) -> Result<Vec<serde_json::Value>, InventoryError> {
        let mut cursor = Some(self.base_url.join(endpoint).map_err(|err| {
            InventoryError::Parse(format!("failed to construct Nautobot URL: {err}"))
        })?);
        if let Some(current) = cursor.as_mut() {
            {
                let mut pairs = current.query_pairs_mut();
                pairs.append_pair("limit", &self.page_size.to_string());
                pairs.append_pair("offset", "0");
                pairs.append_pair("depth", NAUTOBOT_DEFAULT_DEPTH);
                for (key, value) in filters {
                    pairs.append_pair(key, value);
                }
            }
        }
        let mut results = Vec::new();
        while let Some(current) = cursor.take() {
            let payload = self.get_page(current)?;
            results.extend(payload.results.into_iter());
            cursor = match payload.next {
                Some(next) => Some(self.parse_next_url(&next)?),
                None => None,
            };
        }
        Ok(results)
    }

    fn get_page(&self, url: Url) -> Result<NautobotListResponse, InventoryError> {
        let response = self
            .client
            .get(url.clone())
            .header("Authorization", format!("Token {}", self.token))
            .header("Accept", "application/json")
            .send()?
            .error_for_status()?;
        Ok(response.json()?)
    }

    fn parse_next_url(&self, raw: &str) -> Result<Url, InventoryError> {
        match Url::parse(raw) {
            Ok(url) => Ok(url),
            Err(_) => self.base_url.join(raw).map_err(|err| {
                InventoryError::Parse(format!("invalid Nautobot pagination URL: {err}"))
            }),
        }
    }

    fn build_device_host(&self, record: &serde_json::Value) -> Result<Host, InventoryError> {
        self.build_host(record, NautobotObjectKind::Device)
    }

    fn build_vm_host(&self, record: &serde_json::Value) -> Result<Host, InventoryError> {
        self.build_host(record, NautobotObjectKind::VirtualMachine)
    }

    fn build_host(
        &self,
        record: &serde_json::Value,
        kind: NautobotObjectKind,
    ) -> Result<Host, InventoryError> {
        let name = self
            .string_field(record, "name")
            .or_else(|| self.string_field(record, "display"))
            .or_else(|| record.get("id").map(|id| id.to_string()))
            .ok_or_else(|| InventoryError::Parse("nautobot record missing name".into()))?;
        let hostname = self
            .primary_ip(record)
            .or_else(|| self.string_field(record, "name"))
            .unwrap_or_else(|| name.clone());
        let mut host = Host {
            name: name.clone(),
            hostname: Some(hostname),
            platform: self.platform_slug(record),
            ..Host::default()
        };
        host.groups = self.derive_groups(record, kind);
        host.data = self.build_data(record, kind);
        Ok(host)
    }

    fn build_data(&self, record: &serde_json::Value, kind: NautobotObjectKind) -> Variables {
        let mut data = Variables::new();
        data.insert("nautobot".into(), record.clone());
        data.insert("kind".into(), serde_json::json!(kind.as_str()));
        if let Some(status) = self.nested_field(record, &["status", "value"]) {
            data.insert("status".into(), serde_json::json!(status));
        }
        if let Some(serial) = self.string_field(record, "serial") {
            data.insert("serial".into(), serde_json::json!(serial));
        }
        if let Some(asset) = self.string_field(record, "asset_tag") {
            data.insert("asset_tag".into(), serde_json::json!(asset));
        }
        if let Some(role) = self
            .nested_field(record, &["role", "slug"])
            .or_else(|| self.nested_field(record, &["device_role", "slug"]))
        {
            data.insert("role".into(), serde_json::json!(role));
        }
        if let Some(site) = self.nested_field(record, &["site", "slug"]) {
            data.insert("site".into(), serde_json::json!(site));
        }
        if let Some(cluster) = self.nested_field(record, &["cluster", "slug"]) {
            data.insert("cluster".into(), serde_json::json!(cluster));
        }
        if let Some(tenant) = self.nested_field(record, &["tenant", "slug"]) {
            data.insert("tenant".into(), serde_json::json!(tenant));
        }
        if let Some(ipv4) = self.primary_ip_field(record, "primary_ip4") {
            data.insert("primary_ip4".into(), serde_json::json!(ipv4));
        }
        if let Some(ipv6) = self.primary_ip_field(record, "primary_ip6") {
            data.insert("primary_ip6".into(), serde_json::json!(ipv6));
        }
        if let Some(primary) = self.primary_ip_field(record, "primary_ip") {
            data.insert("primary_ip".into(), serde_json::json!(primary));
        }
        if let Some(tags) = record
            .get("tags")
            .and_then(|value| value.as_array())
            .map(|list| {
                list.iter()
                    .filter_map(Self::tag_slug)
                    .map(|slug| serde_json::json!(slug))
                    .collect::<Vec<_>>()
            })
        {
            data.insert("tags".into(), serde_json::Value::Array(tags));
        }
        if let Some(cf) = record.get("custom_fields") {
            if self.flatten_custom_fields {
                if let Some(map) = cf.as_object() {
                    for (key, value) in map {
                        data.insert(key.clone(), value.clone());
                    }
                }
            } else {
                data.insert("custom_fields".into(), cf.clone());
            }
        }
        data
    }

    fn derive_groups(&self, record: &serde_json::Value, kind: NautobotObjectKind) -> Vec<String> {
        let mut groups = Vec::new();
        self.push_group(&mut groups, Some(kind.as_str()), "kind:");
        if self.roles_as_groups
            && let Some(role) = self
                .nested_field(record, &["role", "slug"])
                .or_else(|| self.nested_field(record, &["device_role", "slug"]))
        {
            self.push_group(&mut groups, Some(&role), "role:");
        }
        if self.sites_as_groups
            && let Some(site) = self.nested_field(record, &["site", "slug"])
        {
            self.push_group(&mut groups, Some(&site), "site:");
        }
        if self.tenants_as_groups
            && let Some(tenant) = self.nested_field(record, &["tenant", "slug"])
        {
            self.push_group(&mut groups, Some(&tenant), "tenant:");
        }
        if let NautobotObjectKind::VirtualMachine = kind
            && let Some(cluster) = self.nested_field(record, &["cluster", "slug"])
        {
            self.push_group(&mut groups, Some(&cluster), "cluster:");
        }
        if self.tags_as_groups
            && let Some(tags) = record.get("tags").and_then(|value| value.as_array())
        {
            for tag in tags {
                if let Some(slug) = Self::tag_slug(tag) {
                    self.push_group(&mut groups, Some(slug.as_str()), "tag:");
                }
            }
        }
        groups
    }

    fn push_group(&self, groups: &mut Vec<String>, value: Option<&str>, prefix: &str) {
        if let Some(val) = value {
            let entry = format!("{prefix}{val}");
            if !groups.contains(&entry) {
                groups.push(entry);
            }
        }
    }

    fn string_field(&self, record: &serde_json::Value, key: &str) -> Option<String> {
        record.get(key)?.as_str().map(|value| value.to_string())
    }

    fn nested_field(&self, record: &serde_json::Value, path: &[&str]) -> Option<String> {
        let mut cursor = record;
        for segment in path.iter().take(path.len().saturating_sub(1)) {
            cursor = cursor.get(*segment)?;
        }
        cursor
            .get(*path.last()?)
            .and_then(|value| value.as_str().map(|s| s.to_string()))
    }

    fn primary_ip_field(&self, record: &serde_json::Value, field: &str) -> Option<String> {
        let address = record.get(field)?.get("address")?.as_str()?;
        Some(address.split('/').next().unwrap_or(address).to_string())
    }

    fn primary_ip(&self, record: &serde_json::Value) -> Option<String> {
        self.primary_ip_field(record, "primary_ip4")
            .or_else(|| self.primary_ip_field(record, "primary_ip"))
            .or_else(|| self.primary_ip_field(record, "primary_ip6"))
    }

    fn platform_slug(&self, record: &serde_json::Value) -> Option<String> {
        self.nested_field(record, &["platform", "slug"])
            .or_else(|| self.nested_field(record, &["platform", "network_driver"]))
    }

    fn tag_slug(value: &serde_json::Value) -> Option<String> {
        value
            .get("slug")
            .and_then(|field| field.as_str())
            .map(|slug| slug.to_string())
            .or_else(|| {
                value
                    .get("name")
                    .and_then(|field| field.as_str())
                    .map(|name| name.to_string())
            })
            .or_else(|| {
                value
                    .get("display")
                    .and_then(|field| field.as_str())
                    .map(|display| display.to_string())
            })
            .or_else(|| {
                value
                    .get("natural_slug")
                    .and_then(|field| field.as_str())
                    .map(|slug| slug.to_string())
            })
    }
}

impl InventorySource for NautobotInventorySource {
    fn load(&self) -> Result<Inventory, InventoryError> {
        let mut inventory = Inventory::default();
        for device in self.fetch_collection(NAUTOBOT_DEVICES_ENDPOINT, &self.device_filters)? {
            let host = self.build_device_host(&device)?;
            inventory.hosts.insert(host.name.clone(), host);
        }
        if self.include_virtual_machines {
            for vm in self.fetch_collection(NAUTOBOT_VMS_ENDPOINT, &self.vm_filters)? {
                let host = self.build_vm_host(&vm)?;
                inventory.hosts.insert(host.name.clone(), host);
            }
        }
        Ok(inventory)
    }

    fn name(&self) -> &str {
        self.base_url.as_str()
    }
}

#[derive(Deserialize)]
struct NautobotListResponse {
    next: Option<String>,
    results: Vec<serde_json::Value>,
}

#[derive(Clone, Copy)]
enum NautobotObjectKind {
    Device,
    VirtualMachine,
}

impl NautobotObjectKind {
    fn as_str(&self) -> &'static str {
        match self {
            NautobotObjectKind::Device => "device",
            NautobotObjectKind::VirtualMachine => "virtual_machine",
        }
    }
}

/// Configuration consumed by the NetBox inventory source.
pub struct NetboxInventoryConfig {
    pub base_url: String,
    pub token: String,
    pub verify_tls: bool,
    pub timeout: Duration,
    pub include_virtual_machines: bool,
    pub flatten_custom_fields: bool,
    pub tags_as_groups: bool,
    pub sites_as_groups: bool,
    pub roles_as_groups: bool,
    pub tenants_as_groups: bool,
    pub use_platform_slug: bool,
    pub use_platform_napalm_driver: bool,
    pub page_size: u32,
    pub device_filters: Vec<(String, String)>,
    pub virtual_machine_filters: Vec<(String, String)>,
    pub group_file: Option<PathBuf>,
    pub defaults_file: Option<PathBuf>,
}

/// Inventory source backed by NetBox's REST API.
pub struct NetboxInventorySource {
    client: reqwest::blocking::Client,
    base_url: Url,
    auth_header: String,
    include_virtual_machines: bool,
    flatten_custom_fields: bool,
    tags_as_groups: bool,
    sites_as_groups: bool,
    roles_as_groups: bool,
    tenants_as_groups: bool,
    use_platform_slug: bool,
    use_platform_napalm_driver: bool,
    page_size: u32,
    device_filters: Vec<(String, String)>,
    vm_filters: Vec<(String, String)>,
    group_file: Option<PathBuf>,
    defaults_file: Option<PathBuf>,
}

impl NetboxInventorySource {
    /// Creates a source with the provided NetBox connection details.
    pub fn new(config: NetboxInventoryConfig) -> Result<Self, InventoryError> {
        let mut builder = reqwest::blocking::Client::builder()
            .timeout(config.timeout)
            .user_agent("kore/netbox");
        if !config.verify_tls {
            builder = builder.danger_accept_invalid_certs(true);
        }
        let client = builder.build()?;
        let base_url = Url::parse(&config.base_url)
            .map_err(|err| InventoryError::Parse(format!("invalid NetBox url: {err}")))?;
        Ok(Self {
            client,
            base_url,
            auth_header: Self::format_auth_header(&config.token),
            include_virtual_machines: config.include_virtual_machines,
            flatten_custom_fields: config.flatten_custom_fields,
            tags_as_groups: config.tags_as_groups,
            sites_as_groups: config.sites_as_groups,
            roles_as_groups: config.roles_as_groups,
            tenants_as_groups: config.tenants_as_groups,
            use_platform_slug: config.use_platform_slug,
            use_platform_napalm_driver: config.use_platform_napalm_driver,
            page_size: config.page_size.max(1),
            device_filters: config.device_filters,
            vm_filters: config.virtual_machine_filters,
            group_file: config.group_file,
            defaults_file: config.defaults_file,
        })
    }

    fn fetch_collection(
        &self,
        endpoint: &str,
        filters: &[(String, String)],
    ) -> Result<Vec<serde_json::Value>, InventoryError> {
        let mut cursor = Some(self.base_url.join(endpoint).map_err(|err| {
            InventoryError::Parse(format!("failed to construct NetBox URL: {err}"))
        })?);
        if let Some(current) = cursor.as_mut() {
            {
                let mut pairs = current.query_pairs_mut();
                pairs.append_pair("limit", &self.page_size.to_string());
                pairs.append_pair("offset", "0");
                for (key, value) in filters {
                    pairs.append_pair(key, value);
                }
            }
        }
        let mut results = Vec::new();
        while let Some(current) = cursor.take() {
            let payload = self.get_page(current)?;
            results.extend(payload.results.into_iter());
            cursor = match payload.next {
                Some(next) => Some(self.parse_next_url(&next)?),
                None => None,
            };
        }
        Ok(results)
    }

    fn get_page(&self, url: Url) -> Result<NetboxListResponse, InventoryError> {
        let response = self
            .client
            .get(url.clone())
            .header("Authorization", self.auth_header.clone())
            .header("Accept", "application/json")
            .send()?
            .error_for_status()?;
        Ok(response.json()?)
    }

    fn format_auth_header(token: &str) -> String {
        let trimmed = token.trim();
        if trimmed.starts_with("Bearer ") {
            trimmed.to_string()
        } else if trimmed.starts_with("nbt_") {
            format!("Bearer {trimmed}")
        } else {
            format!("Token {trimmed}")
        }
    }

    fn parse_next_url(&self, raw: &str) -> Result<Url, InventoryError> {
        match Url::parse(raw) {
            Ok(url) => Ok(url),
            Err(_) => self.base_url.join(raw).map_err(|err| {
                InventoryError::Parse(format!("invalid NetBox pagination URL: {err}"))
            }),
        }
    }

    fn fetch_platform_drivers(&self) -> Result<HashMap<String, String>, InventoryError> {
        let mut lookup = HashMap::new();
        for platform in self.fetch_collection(NETBOX_PLATFORMS_ENDPOINT, &[])? {
            if let (Some(slug), Some(driver)) = (
                platform.get("slug").and_then(|v| v.as_str()),
                platform.get("napalm_driver").and_then(|v| v.as_str()),
            ) {
                lookup.insert(slug.to_string(), driver.to_string());
            }
        }
        Ok(lookup)
    }

    fn build_device_host(
        &self,
        record: &serde_json::Value,
        platform_lookup: Option<&HashMap<String, String>>,
    ) -> Result<Host, InventoryError> {
        self.build_host(record, NetboxObjectKind::Device, platform_lookup)
    }

    fn build_vm_host(
        &self,
        record: &serde_json::Value,
        platform_lookup: Option<&HashMap<String, String>>,
    ) -> Result<Host, InventoryError> {
        self.build_host(record, NetboxObjectKind::VirtualMachine, platform_lookup)
    }

    fn build_host(
        &self,
        record: &serde_json::Value,
        kind: NetboxObjectKind,
        platform_lookup: Option<&HashMap<String, String>>,
    ) -> Result<Host, InventoryError> {
        let name = self
            .string_field(record, "name")
            .or_else(|| self.string_field(record, "display"))
            .or_else(|| record.get("id").map(|id| id.to_string()))
            .ok_or_else(|| InventoryError::Parse("netbox record missing name".into()))?;
        let hostname = self
            .primary_ip(record)
            .or_else(|| self.string_field(record, "name"))
            .unwrap_or_else(|| name.clone());
        let mut host = Host {
            name: name.clone(),
            hostname: Some(hostname),
            platform: self.platform_value(record, platform_lookup),
            ..Host::default()
        };
        host.groups = self.derive_groups(record, kind);
        host.data = self.build_data(record, kind);
        Ok(host)
    }

    fn build_data(&self, record: &serde_json::Value, kind: NetboxObjectKind) -> Variables {
        let mut data = Variables::new();
        data.insert("netbox".into(), record.clone());
        data.insert("kind".into(), serde_json::json!(kind.as_str()));
        if let Some(status) = self.nested_field(record, &["status", "value"]) {
            data.insert("status".into(), serde_json::json!(status));
        }
        if let Some(serial) = self.string_field(record, "serial") {
            data.insert("serial".into(), serde_json::json!(serial));
        }
        if let Some(asset) = self.string_field(record, "asset_tag") {
            data.insert("asset_tag".into(), serde_json::json!(asset));
        }
        if let Some(role) = self
            .nested_field(record, &["device_role", "slug"])
            .or_else(|| self.nested_field(record, &["role", "slug"]))
        {
            data.insert("role".into(), serde_json::json!(role));
        }
        if let Some(site) = self.nested_field(record, &["site", "slug"]) {
            data.insert("site".into(), serde_json::json!(site));
        }
        if let Some(tenant) = self.nested_field(record, &["tenant", "slug"]) {
            data.insert("tenant".into(), serde_json::json!(tenant));
        }
        if let Some(cluster) = self.nested_field(record, &["cluster", "slug"]) {
            data.insert("cluster".into(), serde_json::json!(cluster));
        }
        if let Some(primary) = self.primary_ip_field(record, "primary_ip") {
            data.insert("primary_ip".into(), serde_json::json!(primary));
        }
        if let Some(primary) = self.primary_ip_field(record, "primary_ip4") {
            data.insert("primary_ip4".into(), serde_json::json!(primary));
        }
        if let Some(primary) = self.primary_ip_field(record, "primary_ip6") {
            data.insert("primary_ip6".into(), serde_json::json!(primary));
        }
        if let Some(tags) = record
            .get("tags")
            .and_then(|value| value.as_array())
            .map(|list| {
                list.iter()
                    .filter_map(Self::tag_slug)
                    .map(serde_json::Value::String)
                    .collect::<Vec<_>>()
            })
        {
            data.insert("tags".into(), serde_json::Value::Array(tags));
        }
        if let Some(cf) = record.get("custom_fields") {
            if self.flatten_custom_fields {
                if let Some(map) = cf.as_object() {
                    for (key, value) in map {
                        data.insert(key.clone(), value.clone());
                    }
                }
            } else {
                data.insert("custom_fields".into(), cf.clone());
            }
        }
        data
    }

    fn derive_groups(&self, record: &serde_json::Value, kind: NetboxObjectKind) -> Vec<String> {
        let mut groups = Vec::new();
        self.push_group(&mut groups, Some(kind.as_str()), "kind:");
        if self.roles_as_groups
            && let Some(role) = self
                .nested_field(record, &["device_role", "slug"])
                .or_else(|| self.nested_field(record, &["role", "slug"]))
        {
            self.push_group(&mut groups, Some(&role), "role:");
        }
        if self.sites_as_groups
            && let Some(site) = self.nested_field(record, &["site", "slug"])
        {
            self.push_group(&mut groups, Some(&site), "site:");
        }
        if self.tenants_as_groups
            && let Some(tenant) = self.nested_field(record, &["tenant", "slug"])
        {
            self.push_group(&mut groups, Some(&tenant), "tenant:");
        }
        if matches!(kind, NetboxObjectKind::VirtualMachine)
            && let Some(cluster) = self.nested_field(record, &["cluster", "slug"])
        {
            self.push_group(&mut groups, Some(&cluster), "cluster:");
        }
        if let Some(platform) = self.nested_field(record, &["platform", "slug"]) {
            self.push_group(&mut groups, Some(&platform), "platform:");
        }
        if let Some(device_type) = self.nested_field(record, &["device_type", "slug"]) {
            self.push_group(&mut groups, Some(&device_type), "device_type:");
        }
        if let Some(manufacturer) =
            self.nested_field(record, &["device_type", "manufacturer", "slug"])
        {
            self.push_group(&mut groups, Some(&manufacturer), "manufacturer:");
        }
        if self.tags_as_groups
            && let Some(tags) = record.get("tags").and_then(|value| value.as_array())
        {
            for tag in tags {
                if let Some(slug) = Self::tag_slug(tag) {
                    self.push_group(&mut groups, Some(&slug), "tag:");
                }
            }
        }
        groups
    }

    fn push_group(&self, groups: &mut Vec<String>, value: Option<&str>, prefix: &str) {
        if let Some(val) = value {
            let entry = format!("{prefix}{val}");
            if !groups.contains(&entry) {
                groups.push(entry);
            }
        }
    }

    fn string_field(&self, record: &serde_json::Value, key: &str) -> Option<String> {
        record.get(key)?.as_str().map(|value| value.to_string())
    }

    fn nested_field(&self, record: &serde_json::Value, path: &[&str]) -> Option<String> {
        let mut cursor = record;
        for segment in path.iter().take(path.len().saturating_sub(1)) {
            cursor = cursor.get(*segment)?;
        }
        cursor
            .get(*path.last()?)
            .and_then(|value| value.as_str().map(|s| s.to_string()))
    }

    fn primary_ip_field(&self, record: &serde_json::Value, field: &str) -> Option<String> {
        let address = record.get(field)?.get("address")?.as_str()?;
        Some(address.split('/').next().unwrap_or(address).to_string())
    }

    fn primary_ip(&self, record: &serde_json::Value) -> Option<String> {
        self.primary_ip_field(record, "primary_ip4")
            .or_else(|| self.primary_ip_field(record, "primary_ip"))
            .or_else(|| self.primary_ip_field(record, "primary_ip6"))
    }

    fn platform_value(
        &self,
        record: &serde_json::Value,
        platform_lookup: Option<&HashMap<String, String>>,
    ) -> Option<String> {
        let platform = record.get("platform")?;
        match platform {
            serde_json::Value::String(value) => Some(value.clone()),
            serde_json::Value::Object(map) => {
                if self.use_platform_napalm_driver
                    && let Some(slug) = map.get("slug").and_then(|v| v.as_str())
                    && let Some(lookup) = platform_lookup
                    && let Some(driver) = lookup.get(slug)
                {
                    return Some(driver.clone());
                }
                if self.use_platform_slug {
                    map.get("slug")
                        .and_then(|value| value.as_str())
                        .map(|s| s.to_string())
                        .or_else(|| {
                            map.get("name")
                                .and_then(|value| value.as_str())
                                .map(|s| s.to_string())
                        })
                } else {
                    map.get("name")
                        .and_then(|value| value.as_str())
                        .map(|s| s.to_string())
                }
            }
            _ => None,
        }
    }

    fn tag_slug(value: &serde_json::Value) -> Option<String> {
        value
            .get("slug")
            .and_then(|field| field.as_str())
            .map(|slug| slug.to_string())
            .or_else(|| {
                value
                    .get("name")
                    .and_then(|field| field.as_str())
                    .map(|name| name.to_string())
            })
            .or_else(|| {
                value
                    .get("display")
                    .and_then(|field| field.as_str())
                    .map(|display| display.to_string())
            })
            .or_else(|| {
                value
                    .get("natural_slug")
                    .and_then(|field| field.as_str())
                    .map(|slug| slug.to_string())
            })
    }

    fn load_overlays(&self) -> Result<Option<Inventory>, InventoryError> {
        let mut overlays = CompositeFileInventorySource::new();
        let mut has_files = false;
        if let Some(path) = &self.group_file
            && path.exists()
        {
            overlays = overlays.groups(path.clone())?;
            has_files = true;
        }
        if let Some(path) = &self.defaults_file
            && path.exists()
        {
            overlays = overlays.defaults(path.clone())?;
            has_files = true;
        }
        if has_files {
            overlays.load().map(Some)
        } else {
            Ok(None)
        }
    }
}

impl InventorySource for NetboxInventorySource {
    fn load(&self) -> Result<Inventory, InventoryError> {
        let platform_lookup = if self.use_platform_napalm_driver {
            Some(self.fetch_platform_drivers()?)
        } else {
            None
        };
        let mut inventory = Inventory::default();
        for device in self.fetch_collection(NETBOX_DEVICES_ENDPOINT, &self.device_filters)? {
            let host = self.build_device_host(&device, platform_lookup.as_ref())?;
            inventory.hosts.insert(host.name.clone(), host);
        }
        if self.include_virtual_machines {
            for vm in self.fetch_collection(NETBOX_VMS_ENDPOINT, &self.vm_filters)? {
                let host = self.build_vm_host(&vm, platform_lookup.as_ref())?;
                inventory.hosts.insert(host.name.clone(), host);
            }
        }
        if let Some(overlays) = self.load_overlays()? {
            inventory.merge(overlays);
        }
        Ok(inventory)
    }

    fn name(&self) -> &str {
        self.base_url.as_str()
    }
}

#[derive(Deserialize)]
struct NetboxListResponse {
    next: Option<String>,
    results: Vec<serde_json::Value>,
}

#[derive(Clone, Copy, PartialEq, Eq)]
enum NetboxObjectKind {
    Device,
    VirtualMachine,
}

impl NetboxObjectKind {
    fn as_str(&self) -> &'static str {
        match self {
            NetboxObjectKind::Device => "device",
            NetboxObjectKind::VirtualMachine => "virtual_machine",
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;
    use std::{fs, io::Write, path::Path, time::Duration};
    use tempfile::{NamedTempFile, tempdir};

    #[test]
    fn merges_host_data() {
        let mut base = Inventory::default();
        base.hosts.insert(
            "r1".into(),
            Host {
                name: "r1".into(),
                hostname: Some("10.0.0.1".into()),
                port: Some(22),
                ..Host::default()
            },
        );

        let mut override_inv = Inventory::default();
        override_inv.hosts.insert(
            "r1".into(),
            Host {
                name: "r1".into(),
                platform: Some("ios".into()),
                port: Some(2222),
                ..Host::default()
            },
        );

        base.merge(override_inv);

        let host = base.host("r1").unwrap();
        assert_eq!(host.hostname.as_deref(), Some("10.0.0.1"));
        assert_eq!(host.platform.as_deref(), Some("ios"));
        assert_eq!(host.port, Some(2222));
    }

    #[test]
    fn merges_group_and_default_credentials() {
        let mut inventory = Inventory::default();
        inventory.groups.insert(
            "core".into(),
            Group {
                name: "core".into(),
                credentials: Some(Credentials {
                    username: Some("group-user".into()),
                    password: Some(Secret::new("group-pass")),
                    ..Credentials::default()
                }),
                ..Group::default()
            },
        );

        let mut override_inv = Inventory::default();
        override_inv.defaults.credentials = Some(Credentials {
            username: Some("default-user".into()),
            password: Some(Secret::new("default-pass")),
            private_key: Some(Secret::new("key")),
            enable_secret: None,
        });
        override_inv.groups.insert(
            "core".into(),
            Group {
                name: "core".into(),
                credentials: Some(Credentials {
                    username: Some("override-user".into()),
                    ..Credentials::default()
                }),
                ..Group::default()
            },
        );

        inventory.merge(override_inv);

        let group = inventory.groups.get("core").unwrap();
        assert_eq!(
            group.credentials.as_ref().unwrap().username.as_deref(),
            Some("override-user")
        );
        assert_eq!(
            group
                .credentials
                .as_ref()
                .unwrap()
                .password
                .as_ref()
                .unwrap()
                .as_str(),
            Some("group-pass")
        );
        assert_eq!(
            inventory
                .defaults
                .credentials
                .as_ref()
                .unwrap()
                .private_key
                .as_ref()
                .unwrap()
                .as_str(),
            Some("key")
        );
    }

    #[test]
    fn merges_connection_parameters() {
        let mut inventory = Inventory::default();
        inventory.defaults.connections.insert(
            "ssh".into(),
            TransportSettings {
                transport: "ssh".into(),
                params: [("port".into(), json!(22))].into_iter().collect(),
            },
        );

        let mut override_inv = Inventory::default();
        override_inv.defaults.connections.insert(
            "ssh".into(),
            TransportSettings {
                transport: "".into(),
                params: [("timeout".into(), json!(30))].into_iter().collect(),
            },
        );

        inventory.merge(override_inv);

        let conn = inventory.defaults.connections.get("ssh").unwrap();
        assert_eq!(conn.transport, "ssh");
        assert_eq!(conn.params.get("port").unwrap(), &json!(22));
        assert_eq!(conn.params.get("timeout").unwrap(), &json!(30));
    }

    #[test]
    fn transport_settings_params_to_struct() {
        #[derive(Deserialize, PartialEq, Debug)]
        struct Config {
            username: String,
            retries: Option<u8>,
        }

        let mut params = Variables::default();
        params.insert("username".into(), json!("automation"));
        params.insert("retries".into(), json!(3));

        let settings = TransportSettings {
            transport: "ssh".into(),
            params,
        };

        let config: Config = settings.params_as().unwrap();
        assert_eq!(
            config,
            Config {
                username: "automation".into(),
                retries: Some(3)
            }
        );
    }

    #[test]
    fn builder_combines_sources() {
        let mut first = Inventory::default();
        first.hosts.insert(
            "r1".into(),
            Host {
                name: "r1".into(),
                hostname: Some("10.0.0.1".into()),
                ..Host::default()
            },
        );

        let mut second = Inventory::default();
        second.hosts.insert(
            "r2".into(),
            Host {
                name: "r2".into(),
                hostname: Some("10.0.0.2".into()),
                ..Host::default()
            },
        );

        let built = InventoryBuilder::new()
            .with_source(StaticInventorySource::new("first", first))
            .with_source(StaticInventorySource::new("second", second))
            .build()
            .unwrap();

        assert!(built.host("r1").is_some());
        assert!(built.host("r2").is_some());
    }

    #[test]
    fn host_inherits_group_and_defaults_data() {
        let mut hosts_inv = Inventory::default();
        hosts_inv.hosts.insert(
            "r1".into(),
            Host {
                name: "r1".into(),
                groups: vec!["core".into()],
                ..Host::default()
            },
        );

        let mut groups_inv = Inventory::default();
        groups_inv.groups.insert(
            "core".into(),
            Group {
                name: "core".into(),
                data: {
                    let mut data = Variables::default();
                    data.insert("tier".into(), json!("core"));
                    data
                },
                ..Group::default()
            },
        );

        let mut defaults_inv = Inventory::default();
        defaults_inv
            .defaults
            .data
            .insert("owner".into(), json!("netops"));

        let built = InventoryBuilder::new()
            .with_source(StaticInventorySource::new("hosts", hosts_inv))
            .with_source(StaticInventorySource::new("groups", groups_inv))
            .with_source(StaticInventorySource::new("defaults", defaults_inv))
            .build()
            .unwrap();

        let host = built.host("r1").expect("host");
        assert_eq!(host.data.get("tier").unwrap(), "core");
        assert_eq!(host.data.get("owner").unwrap(), "netops");
    }

    #[test]
    fn io_errors_note_path() {
        let err = io_error_with_path(
            std::io::Error::new(std::io::ErrorKind::NotFound, "missing"),
            Path::new("/tmp/demo.yaml"),
        );
        assert!(
            err.to_string().contains("/tmp/demo.yaml"),
            "io error should mention path: {}",
            err
        );
    }

    #[test]
    fn file_loader_reads_yaml() {
        let mut file = NamedTempFile::new().unwrap();
        let yaml = r#"
hosts:
  r1:
    name: r1
    hostname: 10.0.0.5
defaults:
  data:
    env: lab
"#;
        file.write_all(yaml.as_bytes()).unwrap();

        let source = FileInventorySource::new(file.path(), InventoryFormat::Yaml);
        let inventory = source.load().unwrap();

        assert_eq!(
            inventory.host("r1").unwrap().hostname.as_deref(),
            Some("10.0.0.5")
        );
        assert_eq!(inventory.defaults.data.get("env").unwrap(), "lab");
    }

    #[test]
    fn file_loader_reads_sequence_hosts() {
        let mut file = NamedTempFile::new().unwrap();
        let yaml = r#"
hosts:
  - name: core-rt
    hostname: 10.0.0.6
    port: 2222
"#;
        file.write_all(yaml.as_bytes()).unwrap();

        let source = FileInventorySource::new(file.path(), InventoryFormat::Yaml);
        let inventory = source.load().unwrap();
        let host = inventory.host("core-rt").unwrap();
        assert_eq!(host.hostname.as_deref(), Some("10.0.0.6"));
        assert_eq!(host.port, Some(2222));
    }

    #[test]
    fn composite_file_source_merges_parts() {
        let dir = tempdir().unwrap();
        let hosts_path = dir.path().join("hosts.yaml");
        let groups_path = dir.path().join("groups.yaml");
        let defaults_path = dir.path().join("defaults.yaml");

        fs::write(
            &hosts_path,
            r#"
r1:
  hostname: 10.0.0.8
  groups: ["core"]
"#,
        )
        .unwrap();

        fs::write(
            &groups_path,
            r#"
core:
  data:
    role: spine
"#,
        )
        .unwrap();

        fs::write(
            &defaults_path,
            r#"
data:
  owner: neteng
"#,
        )
        .unwrap();

        let source = CompositeFileInventorySource::new()
            .hosts(&hosts_path)
            .unwrap()
            .groups(&groups_path)
            .unwrap()
            .defaults(&defaults_path)
            .unwrap();

        let inventory = source.load().unwrap();

        assert_eq!(
            inventory.host("r1").unwrap().hostname.as_deref(),
            Some("10.0.0.8")
        );
        assert_eq!(
            inventory
                .groups
                .get("core")
                .unwrap()
                .data
                .get("role")
                .unwrap(),
            "spine"
        );
        assert_eq!(inventory.defaults.data.get("owner").unwrap(), "neteng");
    }

    #[test]
    fn http_source_parses_payload() {
        let inventory = parse_inventory_body(
            InventoryFormat::Json,
            r#"{
                    "hosts": {
                        "r1": {
                            "name": "r1",
                            "hostname": "10.0.0.9"
                        }
                    }
                }"#,
        )
        .unwrap();

        assert_eq!(
            inventory.host("r1").unwrap().hostname.as_deref(),
            Some("10.0.0.9")
        );
    }

    #[test]
    fn inventory_format_parses_labels() {
        assert!(matches!(
            InventoryFormat::from_label("YAML"),
            Some(InventoryFormat::Yaml)
        ));
        assert!(matches!(
            InventoryFormat::from_label("json"),
            Some(InventoryFormat::Json)
        ));
        assert!(InventoryFormat::from_label("bogus").is_none());
    }

    #[test]
    fn secret_deserializes_from_string() {
        #[derive(Deserialize)]
        struct Wrapper {
            password: Secret,
        }
        let parsed: Wrapper = serde_yaml::from_str("password: hunter2").unwrap();
        assert_eq!(parsed.password.as_str(), Some("hunter2"));
        assert!(parsed.password.reference.is_none());
    }

    #[test]
    fn secret_supports_reference_fields() {
        let yaml = r#"
password:
  ref: netops/password
  provider: vault
  optional: true
"#;
        #[derive(Deserialize)]
        struct Wrapper {
            password: Secret,
        }
        let parsed: Wrapper = serde_yaml::from_str(yaml).unwrap();
        let reference = parsed.password.reference.as_ref().unwrap();
        assert_eq!(reference.key, "netops/password");
        assert_eq!(reference.provider.as_deref(), Some("vault"));
        assert!(reference.optional);
        assert!(parsed.password.as_str().is_none());
    }

    #[test]
    fn nautobot_device_host_merges_expected_fields() {
        let source = NautobotInventorySource::new(NautobotInventoryConfig {
            base_url: "https://example/api/".into(),
            token: "abc123".into(),
            verify_tls: true,
            timeout: Duration::from_secs(1),
            include_virtual_machines: true,
            flatten_custom_fields: true,
            tags_as_groups: true,
            sites_as_groups: true,
            roles_as_groups: true,
            tenants_as_groups: true,
            page_size: 50,
            device_filters: Vec::new(),
            virtual_machine_filters: Vec::new(),
        })
        .unwrap();
        let record = serde_json::json!({
            "id": 1,
            "name": "core1-rt",
            "primary_ip4": { "address": "10.0.0.1/32" },
            "platform": { "slug": "iosxe" },
            "device_role": { "slug": "core" },
            "site": { "slug": "lab" },
            "tenant": { "slug": "test" },
            "status": { "value": "active" },
            "tags": [{ "slug": "edge" }],
            "custom_fields": { "region": "us-east" }
        });
        let host = source.build_device_host(&record).unwrap();
        assert_eq!(host.name, "core1-rt");
        assert_eq!(host.hostname.as_deref(), Some("10.0.0.1"));
        assert_eq!(host.platform.as_deref(), Some("iosxe"));
        assert!(host.groups.contains(&"role:core".into()));
        assert!(host.groups.contains(&"site:lab".into()));
        assert!(host.groups.contains(&"tag:edge".into()));
        assert!(host.groups.contains(&"tenant:test".into()));
        assert_eq!(
            host.data.get("region").and_then(|v| v.as_str()),
            Some("us-east")
        );
        assert_eq!(
            host.data
                .get("nautobot")
                .and_then(|v| v.get("name"))
                .and_then(|v| v.as_str()),
            Some("core1-rt")
        );
    }

    #[test]
    fn nautobot_vm_host_sets_cluster_groups_and_primary_ip() {
        let source = NautobotInventorySource::new(NautobotInventoryConfig {
            base_url: "https://example/api/".into(),
            token: "xyz".into(),
            verify_tls: true,
            timeout: Duration::from_secs(1),
            include_virtual_machines: true,
            flatten_custom_fields: true,
            tags_as_groups: false,
            sites_as_groups: true,
            roles_as_groups: true,
            tenants_as_groups: true,
            page_size: 50,
            device_filters: Vec::new(),
            virtual_machine_filters: Vec::new(),
        })
        .unwrap();
        let record = serde_json::json!({
            "id": 2,
            "name": "dc1-vm1",
            "primary_ip": { "address": "192.0.2.10/32" },
            "platform": { "slug": "linux" },
            "role": { "slug": "app" },
            "cluster": { "slug": "compute" },
            "tenant": { "slug": "tenant1" },
            "status": { "value": "active" },
            "custom_fields": { "tier": "app" }
        });
        let host = source.build_vm_host(&record).unwrap();
        assert_eq!(host.hostname.as_deref(), Some("192.0.2.10"));
        assert!(host.groups.contains(&"role:app".into()));
        assert!(host.groups.contains(&"cluster:compute".into()));
        assert!(host.groups.contains(&"kind:virtual_machine".into()));
        assert_eq!(host.data.get("tier").and_then(|v| v.as_str()), Some("app"));
    }

    #[test]
    fn netbox_device_host_sets_expected_fields() {
        let source = NetboxInventorySource::new(NetboxInventoryConfig {
            base_url: "https://netbox/api/".into(),
            token: "abc123".into(),
            verify_tls: true,
            timeout: Duration::from_secs(1),
            include_virtual_machines: true,
            flatten_custom_fields: true,
            tags_as_groups: true,
            sites_as_groups: true,
            roles_as_groups: true,
            tenants_as_groups: true,
            use_platform_slug: true,
            use_platform_napalm_driver: false,
            page_size: 50,
            device_filters: Vec::new(),
            virtual_machine_filters: Vec::new(),
            group_file: None,
            defaults_file: None,
        })
        .unwrap();
        let record = serde_json::json!({
            "id": 101,
            "name": "dc1-edge-1",
            "primary_ip": { "address": "10.10.10.10/32" },
            "platform": { "slug": "iosxe", "name": "IOS-XE" },
            "device_role": { "slug": "edge" },
            "site": { "slug": "lab" },
            "tenant": { "slug": "prod" },
            "device_type": {
                "slug": "c9300",
                "manufacturer": { "slug": "cisco" }
            },
            "tags": [{ "slug": "core" }],
            "custom_fields": { "region": "us-east" }
        });
        let host = source.build_device_host(&record, None).unwrap();
        assert_eq!(host.name, "dc1-edge-1");
        assert_eq!(host.hostname.as_deref(), Some("10.10.10.10"));
        assert!(host.groups.contains(&"site:lab".into()));
        assert!(host.groups.contains(&"role:edge".into()));
        assert!(host.groups.contains(&"manufacturer:cisco".into()));
        assert!(host.groups.contains(&"tag:core".into()));
        assert_eq!(
            host.data.get("region").and_then(|value| value.as_str()),
            Some("us-east")
        );
        assert_eq!(
            host.data
                .get("netbox")
                .and_then(|value| value.get("name"))
                .and_then(|value| value.as_str()),
            Some("dc1-edge-1")
        );
    }

    #[test]
    fn netbox_vm_host_sets_cluster_group() {
        let source = NetboxInventorySource::new(NetboxInventoryConfig {
            base_url: "https://netbox/api/".into(),
            token: "xyz".into(),
            verify_tls: true,
            timeout: Duration::from_secs(1),
            include_virtual_machines: true,
            flatten_custom_fields: false,
            tags_as_groups: false,
            sites_as_groups: true,
            roles_as_groups: true,
            tenants_as_groups: false,
            use_platform_slug: true,
            use_platform_napalm_driver: false,
            page_size: 50,
            device_filters: Vec::new(),
            virtual_machine_filters: Vec::new(),
            group_file: None,
            defaults_file: None,
        })
        .unwrap();
        let record = serde_json::json!({
            "id": 202,
            "name": "app-vm1",
            "primary_ip4": { "address": "192.0.2.10/32" },
            "role": { "slug": "app" },
            "cluster": { "slug": "compute" },
            "custom_fields": {}
        });
        let host = source.build_vm_host(&record, None).unwrap();
        assert_eq!(host.hostname.as_deref(), Some("192.0.2.10"));
        assert!(host.groups.contains(&"role:app".into()));
        assert!(host.groups.contains(&"cluster:compute".into()));
        assert!(host.groups.contains(&"kind:virtual_machine".into()));
    }

    #[test]
    fn netbox_authorization_header_supports_bearer_tokens() {
        assert_eq!(
            NetboxInventorySource::format_auth_header("foo"),
            "Token foo"
        );
        assert_eq!(
            NetboxInventorySource::format_auth_header("nbt_abc123"),
            "Bearer nbt_abc123"
        );
        assert_eq!(
            NetboxInventorySource::format_auth_header("Bearer nbt_token"),
            "Bearer nbt_token"
        );
    }
}