nlink 0.28.1

//! Configuration diffing.
//!
//! This module computes the difference between desired and current network state.

use std::{
    collections::{HashMap, HashSet},
    net::IpAddr,
};


use super::types::{
    DeclaredAddress, DeclaredLink, DeclaredLinkType, DeclaredQdisc, DeclaredQdiscType,
    DeclaredRoute, DeclaredRouteType, LinkState, NetworkConfig, QdiscParent,
};
use crate::netlink::{
    builder::MessageBuilder,
    connection::Connection,
    error::Result,
    messages::{AddressMessage, LinkMessage, RouteMessage, TcMessage},
    protocol::Route,
    tc::{
        ClsactConfig, IngressConfig, QdiscConfig,
    },
    types::{addr::Scope, route::RouteProtocol, route::RouteType},
};

/// Options controlling [`NetworkConfig::diff_with_options`](crate::netlink::config::NetworkConfig::diff_with_options).
///
/// `#[non_exhaustive]` (Plan 188 convention) — construct via
/// [`Default::default`] + the builder setters.
#[derive(Debug, Clone, Default)]
#[non_exhaustive]
pub struct DiffOptions {
    /// Compute removals for resources present in the kernel but not
    /// declared in the config ("full reconcile"). Default `false`.
    ///
    /// **Purge is destructive** — it populates
    /// [`ConfigDiff::addresses_to_remove`] /
    /// [`ConfigDiff::routes_to_remove`], which [`ConfigDiff::apply`]
    /// then deletes. It is deliberately reachable *only* through the
    /// explicit `diff_with_options` → inspect → `apply` flow (the
    /// one-shot [`NetworkConfig::apply`](crate::netlink::config::NetworkConfig::apply)
    /// never purges), so you always see the `-` lines in the diff
    /// before anything is deleted.
    ///
    /// Scope + safety rails:
    /// - **Addresses**: only `global`-scope addresses on interfaces
    ///   the config declares addresses on. IPv6 link-local,
    ///   loopback, and any non-global scope are excluded.
    /// - **Routes**: only `static`/`boot` protocol routes, and only
    ///   in the tables the config **owns**: the main table (254),
    ///   every table some declared route names via
    ///   `RouteBuilder::table`, and any listed in
    ///   [`Self::purge_tables`]. Kernel, RA, DHCP and redirect
    ///   routes are excluded, and so is every table the config never
    ///   mentions — `local`, `default`, and a VRF table nobody
    ///   declared into. Until 0.27 the fence was the main table
    ///   alone, so a route declared into a VRF table could be added
    ///   and updated but never removed by reconcile (#333, #335).
    /// - **Links and qdiscs are never purged** — deleting
    ///   interfaces is too destructive to infer; use the imperative
    ///   `Connection::del_link` / `del_qdisc` for those.
    pub purge: bool,

    /// Extra route tables to purge `static`/`boot` routes from, on
    /// top of main and the tables the config declares into. For a
    /// caller that owns a table but declares nothing into it *this*
    /// run (the last VRF route left the config) — without it, the
    /// table drops out of scope the moment it is empty in the
    /// declaration and its leftovers stay. Ignored unless
    /// [`Self::purge`] is on.
    pub purge_tables: Vec<u32>,
}

impl DiffOptions {
    /// Enable/disable purge (full-reconcile removals). See
    /// [`Self::purge`] for the safety scope.
    pub fn purge(mut self, on: bool) -> Self {
        self.purge = on;
        self
    }

    /// Add route tables to the purge scope. See [`Self::purge_tables`].
    pub fn purge_tables(mut self, tables: impl IntoIterator<Item = u32>) -> Self {
        self.purge_tables.extend(tables);
        self
    }

    /// The route tables a purge with these options touches, given
    /// the config: main, every table a declared route names, and
    /// [`Self::purge_tables`].
    pub(crate) fn purge_table_scope(&self, config: &NetworkConfig) -> HashSet<u32> {
        let mut scope: HashSet<u32> = HashSet::from([254]);
        scope.extend(config.routes.iter().filter_map(|r| r.table));
        scope.extend(self.purge_tables.iter().copied());
        scope
    }
}

/// Difference between desired and current network state.
///
/// `#[non_exhaustive]` since 0.24 (#165): new `*_to_add` /
/// `*_to_remove` categories can appear without a major bump.
/// Construct via [`NetworkConfig::diff`](super::NetworkConfig::diff),
/// not literally.
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "kebab-case"))]
#[derive(Debug, Default)]
#[non_exhaustive]
#[must_use = "Diffs do nothing unless passed to `.apply()` or stringified via `Display`"]
pub struct ConfigDiff {
    /// Links to create.
    pub links_to_add: Vec<DeclaredLink>,
    /// Links to modify (name, changes).
    pub links_to_modify: Vec<(String, LinkChanges)>,

    /// Addresses to add.
    pub addresses_to_add: Vec<DeclaredAddress>,

    /// Routes to add.
    pub routes_to_add: Vec<DeclaredRoute>,

    /// Qdiscs to add.
    pub qdiscs_to_add: Vec<DeclaredQdisc>,
    /// Qdiscs to replace (same position, different config).
    pub qdiscs_to_replace: Vec<DeclaredQdisc>,

    /// Addresses to remove (purge mode only — see
    /// [`DiffOptions::purge`]). Populated **only** when the diff is
    /// computed via
    /// [`NetworkConfig::diff_with_options`](crate::netlink::config::NetworkConfig::diff_with_options)
    /// with `purge` on; the default
    /// [`diff`](crate::netlink::config::NetworkConfig::diff) never
    /// removes anything. Kernel-managed addresses (IPv6 link-local,
    /// loopback, any non-`global` scope) are excluded, and only
    /// interfaces the config declares addresses on are touched.
    pub addresses_to_remove: Vec<DeclaredAddress>,

    /// Routes to remove (purge mode only). Populated only under
    /// [`DiffOptions::purge`]. Restricted to the main table and to
    /// admin/user-managed protocols (`static` / `boot`); kernel,
    /// RA, DHCP and redirect routes are excluded so dynamic and
    /// auto-configured routing is never clobbered.
    pub routes_to_remove: Vec<DeclaredRoute>,
}

impl ConfigDiff {
    /// Apply this pre-computed diff in-place without re-running
    /// [`crate::netlink::config::NetworkConfig::diff`].
    ///
    /// Mirrors [`crate::netlink::nftables::config::NftablesDiff::apply`]'s
    /// shape (Plan 188). Use this in the chain pattern when you
    /// already hold a diff:
    ///
    /// ```no_run
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # use nlink::netlink::config::ApplyOptions;
    /// # let conn = nlink::Connection::<nlink::Route>::new()?;
    /// # let cfg = nlink::netlink::config::NetworkConfig::new();
    /// let diff = cfg.diff(&conn).await?;
    /// println!("{diff}");                  // inspect before commit
    /// diff.apply(&conn, ApplyOptions::default()).await?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// More efficient than [`crate::netlink::config::NetworkConfig::apply`] when
    /// you already have a `ConfigDiff` — the latter re-runs
    /// `compute_diff` internally, costing one extra round-trip
    /// of dump traffic.
    pub async fn apply(
        &self,
        conn: &Connection<Route>,
        opts: super::apply::ApplyOptions,
    ) -> Result<super::apply::ApplyResult> {
        super::apply::apply_diff(self, conn, opts).await
    }

    /// Check if no changes are needed.
    pub fn is_empty(&self) -> bool {
        self.links_to_add.is_empty()
            && self.links_to_modify.is_empty()
            && self.addresses_to_add.is_empty()
            && self.routes_to_add.is_empty()
            && self.qdiscs_to_add.is_empty()
            && self.qdiscs_to_replace.is_empty()
            && self.addresses_to_remove.is_empty()
            && self.routes_to_remove.is_empty()
    }

    /// Get the total number of changes.
    pub fn change_count(&self) -> usize {
        self.links_to_add.len()
            + self.links_to_modify.len()
            + self.addresses_to_add.len()
            + self.routes_to_add.len()
            + self.qdiscs_to_add.len()
            + self.qdiscs_to_replace.len()
            + self.addresses_to_remove.len()
            + self.routes_to_remove.len()
    }

    /// Get a human-readable summary of the changes.
    ///
    /// Equivalent to `format!("{self}")` — Plan 183 (0.18) made
    /// the [`std::fmt::Display`] impl share the same renderer.
    /// Prefer the `Display` form (`diff.to_string()` /
    /// `format!("{diff}")`) for new code.
    #[deprecated(
        since = "0.19.0",
        note = "use `Display` via `format!(\"{}\")` or `diff.to_string()` instead — Plan 188 §2.6"
    )]
    pub fn summary(&self) -> String {
        let mut lines = Vec::new();

        // Links
        for link in &self.links_to_add {
            lines.push(format!(
                "+ link {} ({})",
                link.name,
                link.link_type.kind().unwrap_or("physical")
            ));
        }
        for (name, changes) in &self.links_to_modify {
            lines.push(format!("~ link {} ({})", name, changes.summary()));
        }

        // Addresses
        for addr in &self.addresses_to_add {
            lines.push(format!(
                "+ address {}/{} on {}",
                addr.address, addr.prefix_len, addr.dev
            ));
        }
        // Routes
        for route in &self.routes_to_add {
            let via = route
                .gateway
                .map(|g| format!(" via {}", g))
                .unwrap_or_default();
            let dev = route
                .dev
                .as_ref()
                .map(|d| format!(" dev {}", d))
                .unwrap_or_default();
            lines.push(format!(
                "+ route {}/{}{}{}",
                route.destination, route.prefix_len, via, dev
            ));
        }
        // Qdiscs
        for qdisc in &self.qdiscs_to_add {
            lines.push(format!(
                "+ qdisc {} on {} ({:?})",
                qdisc.qdisc_type.kind(),
                qdisc.dev,
                qdisc.parent
            ));
        }
        for qdisc in &self.qdiscs_to_replace {
            lines.push(format!(
                "~ qdisc {} on {} ({:?})",
                qdisc.qdisc_type.kind(),
                qdisc.dev,
                qdisc.parent
            ));
        }

        // Purge removals (only present under `DiffOptions::purge`).
        for addr in &self.addresses_to_remove {
            lines.push(format!(
                "- address {}/{} on {}",
                addr.address, addr.prefix_len, addr.dev
            ));
        }
        for route in &self.routes_to_remove {
            let via = route
                .gateway
                .map(|g| format!(" via {}", g))
                .unwrap_or_default();
            let dev = route
                .dev
                .as_ref()
                .map(|d| format!(" dev {}", d))
                .unwrap_or_default();
            lines.push(format!(
                "- route {}/{}{}{}",
                route.destination, route.prefix_len, via, dev
            ));
        }

        if lines.is_empty() {
            "No changes needed".to_string()
        } else {
            lines.join("\n")
        }
    }
}

/// `Display` shares the renderer with the deprecated
/// `ConfigDiff::summary` so callers can `println!("{diff}")`
/// directly. Plan 183 (0.18) added this; Plan 188 §2.6 (0.19)
/// deprecated `summary()` in favor of this form. The
/// `#[allow(deprecated)]` is for the internal delegation —
/// users are not on the deprecated path.
impl std::fmt::Display for ConfigDiff {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        #[allow(deprecated)]
        f.write_str(&self.summary())
    }
}

/// Changes to make to an existing link.
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "kebab-case"))]
#[derive(Debug, Default)]
pub struct LinkChanges {
    /// Change state to up.
    pub set_up: bool,
    /// Change state to down.
    pub set_down: bool,
    /// New MTU value.
    pub set_mtu: Option<u32>,
    /// New master interface.
    pub set_master: Option<String>,
    /// Remove from master.
    pub unset_master: bool,
    /// New MAC address.
    ///
    /// A declared `address` was stored by the builder and compared by
    /// nothing, so `.link("eth0", |l| l.address(mac))` on an existing
    /// interface produced an empty diff forever and `apply()` reported
    /// zero changes (#275).
    pub set_address: Option<[u8; 6]>,
}

impl LinkChanges {
    /// Check if any changes are needed.
    pub fn is_empty(&self) -> bool {
        !self.set_up
            && !self.set_down
            && self.set_mtu.is_none()
            && self.set_master.is_none()
            && !self.unset_master
            && self.set_address.is_none()
    }

    /// Get a summary of the changes.
    ///
    /// Equivalent to `format!("{self}")` since Plan 188 §2.5
    /// (0.19) added the `Display` impl. Prefer `Display` for
    /// new code; this method may be deprecated in 0.20.
    pub fn summary(&self) -> String {
        let mut parts: Vec<String> = Vec::new();
        if self.set_up {
            parts.push("up".to_string());
        }
        if self.set_down {
            parts.push("down".to_string());
        }
        if let Some(mtu) = self.set_mtu {
            parts.push(format!("mtu={}", mtu));
        }
        if let Some(master) = &self.set_master {
            parts.push(format!("master={}", master));
        }
        if self.unset_master {
            parts.push("nomaster".to_string());
        }
        if let Some(a) = self.set_address {
            parts.push(format!(
                "address={:02x}:{:02x}:{:02x}:{:02x}:{:02x}:{:02x}",
                a[0], a[1], a[2], a[3], a[4], a[5]
            ));
        }
        parts.join(", ")
    }
}

/// `Display` for `LinkChanges` so a `links_to_modify` row in
/// `ConfigDiff::Display` can render the changes compactly:
/// `"~ link eth0 (mtu=9000, up)"`. Plan 188 §2.5 / feedback W6.
impl std::fmt::Display for LinkChanges {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.summary())
    }
}

/// Compute the difference between desired and current state.
pub async fn compute_diff(config: &NetworkConfig, conn: &Connection<Route>) -> Result<ConfigDiff> {
    compute_diff_with_options(config, conn, &DiffOptions::default()).await
}

/// Like [`compute_diff`] but honours [`DiffOptions`] (currently the
/// `purge` flag — see [`DiffOptions::purge`]).
pub async fn compute_diff_with_options(
    config: &NetworkConfig,
    conn: &Connection<Route>,
    opts: &DiffOptions,
) -> Result<ConfigDiff> {
    let mut diff = ConfigDiff::default();

    // Fetch current state
    let current_links = conn.get_links().await?;
    let current_addresses = conn.get_addresses().await?;
    let current_routes = conn.get_routes().await?;
    let current_qdiscs = conn.get_qdiscs().await?;

    // Build lookup maps
    let link_by_name: HashMap<&str, &LinkMessage> = current_links
        .iter()
        .filter_map(|l| l.name.as_deref().map(|n| (n, l)))
        .collect();

    let ifindex_to_name: HashMap<u32, &str> = current_links
        .iter()
        .filter_map(|l| l.name.as_deref().map(|n| (l.ifindex(), n)))
        .collect();

    // Diff links — pass the ifindex→name map so master changes
    // can be detected by resolving the kernel's master ifindex
    // back to a name (Plan 207b H2).
    diff_links(config, &link_by_name, &ifindex_to_name, &mut diff);

    // Plan 186 §3c — topo-sort `links_to_add` so a child whose
    // parent is also being created in this apply lands AFTER
    // its parent. Without this, a `NetworkConfig` that declares
    // a VLAN before its parent (because the declared order is
    // child-first, or because the source iterated a `HashMap`)
    // hits `InterfaceNotFound` on the second `create_link`.
    // Independent links keep their declared order — the sort
    // is stable.
    topo_sort_links_to_add(&mut diff.links_to_add);

    // Diff addresses
    diff_addresses(config, &current_addresses, &ifindex_to_name, opts.purge, &mut diff);

    // Diff routes
    diff_routes(config, &current_routes, &ifindex_to_name, opts, &mut diff);

    // Diff qdiscs
    diff_qdiscs(config, &current_qdiscs, &ifindex_to_name, &mut diff);

    Ok(diff)
}

fn diff_links(
    config: &NetworkConfig,
    current: &HashMap<&str, &LinkMessage>,
    ifindex_to_name: &HashMap<u32, &str>,
    diff: &mut ConfigDiff,
) {
    // Note: desired_names would be used for purge mode to find links to remove
    let _desired_names: HashSet<&str> = config.links.iter().map(|l| l.name.as_str()).collect();

    for declared in &config.links {
        if let Some(existing) = current.get(declared.name.as_str()) {
            // Link exists, check if it needs modification
            let changes = compute_link_changes(declared, existing, ifindex_to_name);
            if !changes.is_empty() {
                diff.links_to_modify.push((declared.name.clone(), changes));
            }
        } else {
            // Link doesn't exist, needs to be created
            // But only if it's not a physical interface
            if declared.link_type != DeclaredLinkType::Physical {
                diff.links_to_add.push(declared.clone());
            }
        }
    }

    // Note: We don't auto-remove links that aren't in the config
    // That requires explicit purge mode
}

/// Plan 186 §3c — stable topological sort of `links_to_add`.
///
/// A child link (Vlan, Macvlan) whose parent is also in
/// `links_to_add` must land AFTER its parent. Independent
/// links keep their declared order — the sort is stable.
///
/// Cycles are theoretically impossible for the link types we
/// model (a `Vlan` parent can't be a `Vlan` child of itself
/// without a kernel that already would have refused), but we
/// still degrade gracefully: any node not in a topo order falls
/// to the tail in its declared position.
fn topo_sort_links_to_add(links: &mut Vec<DeclaredLink>) {
    if links.len() < 2 {
        return;
    }

    // Build set of names being added in this batch.
    let names_in_batch: HashSet<String> =
        links.iter().map(|l| l.name.clone()).collect();

    // Plan 207c M5 — collect ALL in-batch dependencies for a link.
    // Pre-0.19 only `Vlan { parent }` and `Macvlan { parent }`
    // were modeled, missing:
    //   - VXLAN `underlay_dev` (Plan 190 §2.1 added the field but
    //     forgot to wire it into topo-sort — same shape as the
    //     original Plan 186 bug)
    //   - `master` references (declaring `dummy0.master("br0")`
    //     before `br0` in the same batch silently failed at apply)
    fn deps_of(link: &DeclaredLink, names_in_batch: &HashSet<String>) -> Vec<String> {
        let mut deps = Vec::new();
        match &link.link_type {
            DeclaredLinkType::Vlan { parent, .. } => deps.push(parent.clone()),
            DeclaredLinkType::Macvlan { parent, .. } => deps.push(parent.clone()),
            DeclaredLinkType::Vxlan {
                underlay_dev: Some(dev),
                ..
            } => deps.push(dev.clone()),
            _ => {}
        }
        // `master` is a separate field on the link itself —
        // applies to any link type (Dummy, Veth, Bond member,
        // etc. enslaved to a bridge / bond / VRF master).
        if let Some(master) = &link.master {
            deps.push(master.clone());
        }
        deps.retain(|d| names_in_batch.contains(d));
        deps
    }

    // Stable Kahn's algorithm. Iterate `links` in current order;
    // emit a link only once all its in-batch dependencies have
    // been emitted. Use a simple two-pass loop — for the link
    // counts we expect (single-digit to low-double-digit), the
    // cost is negligible and the implementation stays obvious.
    let mut emitted: HashSet<String> = HashSet::new();
    let mut out: Vec<DeclaredLink> = Vec::with_capacity(links.len());
    let mut remaining: Vec<DeclaredLink> = std::mem::take(links);

    while !remaining.is_empty() {
        let before = remaining.len();
        let mut next_remaining = Vec::with_capacity(remaining.len());
        for link in remaining.into_iter() {
            let deps = deps_of(&link, &names_in_batch);
            let ready = deps.iter().all(|d| emitted.contains(d));
            if ready {
                emitted.insert(link.name.clone());
                out.push(link);
            } else {
                next_remaining.push(link);
            }
        }
        // No progress this round — cycle or unresolvable
        // dependency. Append the remainder in declared order
        // so the apply still attempts them (the kernel will
        // give the canonical error).
        if next_remaining.len() == before {
            out.extend(next_remaining);
            break;
        }
        remaining = next_remaining;
    }
    *links = out;
}

fn compute_link_changes(
    declared: &DeclaredLink,
    existing: &LinkMessage,
    ifindex_to_name: &HashMap<u32, &str>,
) -> LinkChanges {
    let mut changes = LinkChanges::default();

    // Plan 207a M10 — read the IFF_UP administrative flag from
    // ifi_flags, NOT the OperState (RFC 2863) field. OperState
    // reports the *carrier-dependent* operational state: dummy /
    // veth / bridge interfaces with no carrier stay
    // `Down`/`LowerLayerDown`/`Unknown` even when admin-up. The
    // pre-0.19 comparison silently no-op'd on
    // `LinkState::Down`-declared no-carrier admin-up interfaces
    // (because operstate was never `Up`, so "if up, set_down"
    // never fired) and unnecessarily fired `set_up` on every
    // re-apply (because operstate stayed non-`Up`).
    let is_admin_up = existing.is_up();
    match declared.state {
        LinkState::Up => {
            if !is_admin_up {
                changes.set_up = true;
            }
        }
        LinkState::Down => {
            if is_admin_up {
                changes.set_down = true;
            }
        }
        LinkState::Unchanged => {}
    }

    // Check MTU
    if let Some(desired_mtu) = declared.mtu
        && existing.mtu != Some(desired_mtu)
    {
        changes.set_mtu = Some(desired_mtu);
    }

    // Check MAC. `LinkMessage::address` is the raw `IFLA_ADDRESS`
    // payload, whose length is the link type's `addr_len` — 6 for
    // Ethernet, 0 for tunnels, 20 for InfiniBand — so compare only when
    // it is the shape a declared MAC can be.
    if let Some(desired_mac) = declared.address {
        let same = existing.address().is_some_and(|have| have == desired_mac);
        if !same {
            changes.set_address = Some(desired_mac);
        }
    }

    // Plan 207b H2 — resolve existing.master (ifindex) → name and
    // compare against the declared master string. Pre-0.19 the
    // comparison was `Option<String> vs Option<u32>` treating any
    // (Some, Some) pair as equal, so bridge-port reassignment
    // (declared `master: "br0"` vs kernel `master: ifindex(br1)`)
    // silently no-op'd — the single most common reconcile
    // operation in lab/CNI environments.
    let existing_master_name: Option<&str> = existing
        .master()
        .and_then(|idx| ifindex_to_name.get(&idx).copied());

    match (declared.master.as_deref(), existing_master_name) {
        (Some(want), Some(have)) if want == have => {
            // No change — declared master matches kernel master.
        }
        (Some(want), _) => {
            // Either kernel has no master, or has a different master.
            // Either way, queue a set_master operation.
            changes.set_master = Some(want.to_string());
        }
        (None, Some(_)) => {
            changes.unset_master = true;
        }
        (None, None) => {
            // Both no-master — no change.
        }
    }

    changes
}

fn diff_addresses(
    config: &NetworkConfig,
    current: &[AddressMessage],
    ifindex_to_name: &HashMap<u32, &str>,
    purge: bool,
    diff: &mut ConfigDiff,
) {
    // Build set of desired addresses: (dev, address, prefix_len)
    let desired: HashSet<(&str, IpAddr, u8)> = config
        .addresses
        .iter()
        .map(|a| (a.dev.as_str(), a.address, a.prefix_len))
        .collect();

    // Build set of current addresses
    let current_set: HashSet<(&str, IpAddr, u8)> = current
        .iter()
        .filter_map(|a| {
            let name = ifindex_to_name.get(&a.ifindex())?;
            let addr = a.address?;
            Some((*name, addr, a.prefix_len()))
        })
        .collect();

    // Find addresses to add
    for declared in &config.addresses {
        let key = (declared.dev.as_str(), declared.address, declared.prefix_len);
        if !current_set.contains(&key) {
            diff.addresses_to_add.push(declared.clone());
        }
    }

    if !purge {
        let _ = desired; // Silence unused warning in the non-purge path.
        return;
    }

    // Purge: remove global-scope addresses that the kernel has but
    // the config doesn't declare — but only on interfaces the config
    // declares *some* address on (we don't touch interfaces we're
    // not managing addresses for), and never kernel-managed
    // addresses (link-local / loopback / any non-global scope).
    let managed_devs: HashSet<&str> = config.addresses.iter().map(|a| a.dev.as_str()).collect();
    for a in current {
        // Only `global` (universe) scope — excludes IPv6 link-local
        // (fe80::, scope link), loopback (::1 / 127.0.0.1, scope
        // host), and other kernel-managed scopes.
        if a.scope() != Scope::Universe {
            continue;
        }
        let Some(name) = ifindex_to_name.get(&a.ifindex()) else {
            continue;
        };
        if !managed_devs.contains(name) {
            continue;
        }
        let Some(addr) = a.address else {
            continue;
        };
        let key = (*name, addr, a.prefix_len());
        if !desired.contains(&key) {
            diff.addresses_to_remove.push(DeclaredAddress {
                dev: name.to_string(),
                address: addr,
                prefix_len: a.prefix_len(),
            });
        }
    }
}

/// The metric the kernel gives an IPv6 route added without one
/// (`IP6_RT_PRIO_USER`, include/net/ip6_route.h). IPv4 leaves an
/// unspecified metric at 0; IPv6 does not, and a diff that assumes it
/// does never matches its own routes.
const IP6_RT_PRIO_USER: u32 = 1024;

fn diff_routes(
    config: &NetworkConfig,
    current: &[RouteMessage],
    ifindex_to_name: &HashMap<u32, &str>,
    opts: &DiffOptions,
    diff: &mut ConfigDiff,
) {
    let purge = opts.purge;
    // Plan 207d H3 — compare the FULL route identity (dst, prefix,
    // table, gateway, oif, metric) when deciding "no change",
    // not just (dst, prefix, table). Pre-0.19 a gateway/dev/metric
    // change on the same `(dst, prefix, table)` silently no-op'd
    // because the key matched and the diff had no
    // `routes_to_modify` collection.
    //
    // We DON'T grow the diff struct; instead any non-trivial
    // mismatch goes into `routes_to_add`, and `add_route` uses
    // `NLM_F_REPLACE` so the kernel atomically swaps the
    // existing route (Plan 207d implementation).

    // Build a name→ifindex map (inverse of `ifindex_to_name`)
    // so we can resolve declared `dev: Option<String>` to compare
    // against the kernel's `oif: Option<u32>`.
    let name_to_ifindex: HashMap<&str, u32> = ifindex_to_name
        .iter()
        .map(|(idx, name)| (*name, *idx))
        .collect();

    // Index current routes by (dst, prefix, table) for fast lookup
    // of every matching kernel route. ECMP / multi-metric setups
    // can have multiple entries per key.
    let mut current_by_key: HashMap<(IpAddr, u8, u32), Vec<&RouteMessage>> = HashMap::new();
    for r in current.iter().filter(|r| {
        matches!(
            r.route_type(),
            RouteType::Unicast
                | RouteType::Blackhole
                | RouteType::Unreachable
                | RouteType::Prohibit
        )
    }) {
        let dst = r.destination.unwrap_or_else(|| {
            if r.is_ipv4() {
                IpAddr::V4(std::net::Ipv4Addr::UNSPECIFIED)
            } else {
                IpAddr::V6(std::net::Ipv6Addr::UNSPECIFIED)
            }
        });
        current_by_key
            .entry((dst, r.dst_len(), r.table_id()))
            .or_default()
            .push(r);
    }

    // For each declared route, check if any kernel route at the
    // same (dst, prefix, table) MATCHES gateway+dev+metric. If yes,
    // no-op. If not, queue for add (which uses NLM_F_REPLACE).
    for declared in &config.routes {
        let table = declared.table.unwrap_or(254);
        let key = (declared.destination, declared.prefix_len, table);
        // `name_to_ifindex` comes from the *pre-apply* link dump, so a
        // config that declares both a link and a route out of it
        // resolves to `None` on the first pass. That mattered: the
        // `(None, Some(_)) => true` arm below then treated *any* kernel
        // route at `(dst, prefix, table)` as a match, so declaring
        // `vx0` plus `10.0.0.0/8 dev vx0` on a host that already had
        // `10.0.0.0/8 dev eth0` omitted the route entirely and a second
        // apply was needed to converge (#281).
        //
        // Distinguish "no dev declared" from "declared a dev we cannot
        // resolve yet": the latter is drift, not a match.
        let declared_dev_unresolved =
            declared.dev.is_some() && {
                let d = declared.dev.as_deref().expect("is_some");
                !name_to_ifindex.contains_key(d)
            };
        let declared_oif = declared
            .dev
            .as_deref()
            .and_then(|d| name_to_ifindex.get(d).copied());

        // A route out of an interface this apply is about to create
        // cannot already be right, whatever the kernel currently has at
        // that destination.
        let matches_existing = !declared_dev_unresolved
            && current_by_key.get(&key).is_some_and(|kernel_routes| {
            kernel_routes.iter().any(|r| {
                // Gateway: compare Option<IpAddr> ↔ Option<&IpAddr>.
                let gw_match = match (declared.gateway, r.gateway()) {
                    (None, None) => true,
                    (Some(a), Some(b)) => a == *b,
                    _ => false,
                };
                // Output interface (ifindex).
                let dev_match = match (declared_oif, r.oif()) {
                    (None, None) => true,
                    (Some(a), Some(b)) => a == b,
                    // declared has no `dev` but kernel oif is
                    // set — accept (the kernel auto-selects oif
                    // from gateway). Treat as match to avoid
                    // unnecessary REPLACE churn.
                    (None, Some(_)) => true,
                    (Some(_), None) => false,
                };
                // Metric (priority). A route added without an explicit
                // metric does not come back as 0 for both families:
                // IPv4 leaves it 0, but IPv6 substitutes
                // `IP6_RT_PRIO_USER` (1024, include/net/ip6_route.h).
                // Comparing a declared `None` against 0 therefore never
                // matched an IPv6 route, so every one of them sat in
                // `routes_to_add` on every diff — forever, and with
                // `apply` reporting no changes at the same time,
                // because the apply path does not go through here
                // (#366).
                let kernel_default_metric = if declared.destination.is_ipv6() {
                    IP6_RT_PRIO_USER
                } else {
                    0
                };
                let metric_match =
                    declared.metric.unwrap_or(kernel_default_metric) == r.priority().unwrap_or(0);
                gw_match && dev_match && metric_match
            })
            });

        if !matches_existing {
            diff.routes_to_add.push(declared.clone());
        }
    }

    if !purge {
        return;
    }

    // Purge: remove admin/user routes the kernel has but the config
    // doesn't declare. Heavily fenced for safety:
    //   - only the tables the config owns: main (254), every table a
    //     declared route names, and `opts.purge_tables` — leaves
    //     local/default and any VRF table nobody declared into
    //     (#333, #335: main-only made a declared VRF route a one-way
    //     street — added and updated, never removed),
    //   - `static`/`boot` protocol only — never kernel-derived,
    //     RA, DHCP or redirect routes (those are dynamic / auto),
    //   - same route-type filter as the add path (unicast +
    //     blackhole/unreachable/prohibit).
    // Identity for "is it declared" is `(dst, prefix, table)`, the
    // same key the add path uses, so a route being replaced is never
    // also queued for removal.
    let desired_keys: HashSet<(IpAddr, u8, u32)> = config
        .routes
        .iter()
        .map(|r| (r.destination, r.prefix_len, r.table.unwrap_or(254)))
        .collect();
    let tables = opts.purge_table_scope(config);

    for r in current {
        if !tables.contains(&r.table_id()) {
            continue;
        }
        if !matches!(r.protocol(), RouteProtocol::Static | RouteProtocol::Boot) {
            continue;
        }
        let route_type = match r.route_type() {
            RouteType::Unicast => DeclaredRouteType::Unicast,
            RouteType::Blackhole => DeclaredRouteType::Blackhole,
            RouteType::Unreachable => DeclaredRouteType::Unreachable,
            RouteType::Prohibit => DeclaredRouteType::Prohibit,
            // Local/broadcast/multicast/anycast/… are kernel-managed
            // — never purge them.
            _ => continue,
        };
        let dst = r.destination.unwrap_or_else(|| {
            if r.is_ipv4() {
                IpAddr::V4(std::net::Ipv4Addr::UNSPECIFIED)
            } else {
                IpAddr::V6(std::net::Ipv6Addr::UNSPECIFIED)
            }
        });
        let key = (dst, r.dst_len(), r.table_id());
        if desired_keys.contains(&key) {
            continue;
        }
        let dev = r
            .oif()
            .and_then(|idx| ifindex_to_name.get(&idx))
            .map(|n| n.to_string());
        diff.routes_to_remove.push(DeclaredRoute {
            destination: dst,
            prefix_len: r.dst_len(),
            gateway: r.gateway().copied(),
            dev,
            metric: r.priority(),
            table: Some(r.table_id()),
            route_type,
        });
    }
}

fn diff_qdiscs(
    config: &NetworkConfig,
    current: &[TcMessage],
    ifindex_to_name: &HashMap<u32, &str>,
    diff: &mut ConfigDiff,
) {
    // Build map of current root qdiscs by device
    let mut current_root_qdisc: HashMap<&str, &TcMessage> = HashMap::new();
    let mut current_ingress_qdisc: HashMap<&str, &TcMessage> = HashMap::new();

    for qdisc in current {
        if let Some(name) = ifindex_to_name.get(&qdisc.ifindex()) {
            if qdisc.is_root() {
                current_root_qdisc.insert(*name, qdisc);
            } else if qdisc.is_ingress() {
                current_ingress_qdisc.insert(*name, qdisc);
            }
        }
    }

    for declared in &config.qdiscs {
        let current_map = match declared.effective_parent() {
            QdiscParent::Root => &current_root_qdisc,
            QdiscParent::Ingress => &current_ingress_qdisc,
        };

        if let Some(existing) = current_map.get(declared.dev.as_str()) {
            // Qdisc exists, check if it matches
            let existing_kind = existing.kind().unwrap_or("");
            let desired_kind = declared.qdisc_type.kind();

            if existing_kind != desired_kind {
                // Different type, need to replace.
                diff.qdiscs_to_replace.push(declared.clone());
            } else if !qdisc_params_match(&declared.qdisc_type, existing) {
                // Same kind, different parameters — replace.
                diff.qdiscs_to_replace.push(declared.clone());
            }
        } else {
            // No qdisc at this position, need to add.
            diff.qdiscs_to_add.push(declared.clone());
        }
    }
}

/// Decide whether the live qdisc already *is* the declared one.
///
/// Compares field by field, through the parsed [`QdiscOptions`] the
/// kernel reports, wherever nlink has a parser for the kind — netem via
/// `tc_recipe_internals::netem_matches` (the same gate `PerPeerImpairer`
/// uses to leave a leaf alone), and tbf / htb / fq_codel / sfq / prio
/// here. The comparison is in the kernel's own units and quantisation:
/// probabilities through `Percent::as_kernel_probability`, codel times
/// through `codel_round_trip_us` (a 20 ms target reads back as 19999 µs).
///
/// This used to byte-compare the declared config's rendered
/// `TCA_OPTIONS` against the kernel's blob. The kernel does not echo what
/// it was sent: netem always reports `CORR`/`RATE`/`ECN`/`LATENCY64`/
/// `JITTER64`, rounds latency to ticks and orders attributes its own way;
/// fq_codel echoes every field with its defaults filled in. So an
/// unchanged declaration was "different" on every `diff()`, landed in
/// `qdiscs_to_replace`, and each `apply()` replaced the qdisc — resetting
/// its statistics, disturbing traffic, and reporting `changes_made >= 1`
/// forever, which broke the "second apply converges" property everything
/// else in `NetworkConfig` has (#346).
///
/// Kinds without a parser, or a live qdisc that carries no options, fall
/// back to the byte compare, so nothing that matched before stops
/// matching now.
///
/// [`QdiscOptions`]: crate::netlink::tc_options::QdiscOptions
fn qdisc_params_match(declared: &DeclaredQdiscType, existing: &TcMessage) -> bool {
    use crate::netlink::tc_options::QdiscOptions;
    use crate::netlink::tc_recipe_internals::{codel_round_trip_us, netem_matches};

    match (declared, existing.options()) {
        (DeclaredQdiscType::Netem { .. }, _) => {
            let cfg = declared.netem_config().expect("matched the Netem arm");
            netem_matches(&cfg, existing)
        }
        (DeclaredQdiscType::Tbf { .. }, Some(QdiscOptions::Tbf(live))) => {
            let cfg = declared.tbf_config().expect("matched the Tbf arm");
            // The kernel echoes the byte-valued TCA_TBF_BURST, so burst is
            // exact; rate is `tc_ratespec.rate` (or RATE64), limit is
            // `tc_tbf_qopt.limit`. `peakrate` is PRATE64/`tc_ratespec`
            // in bytes/sec, and `mtu` comes back through TCA_TBF_PBURST,
            // which the encoder always sends — both are normalised to
            // bytes by `parse_tbf_options`, so neither needs the tick
            // round-trip `codel_round_trip_us` does for fq_codel (#361).
            // Compared against the *lowered* config rather than the
            // declared `Option`s, because the lowering's defaults (mtu
            // 1514, no peakrate) are what actually goes on the wire.
            let declared_peak = cfg
                .peakrate
                .map_or(0, |r| r.as_bytes_per_sec());
            live.rate == cfg.rate.as_bytes_per_sec()
                && live.burst == cfg.burst.as_u32_saturating()
                && live.limit == cfg.limit.as_u32_saturating()
                && live.peakrate == declared_peak
                && live.mtu == cfg.mtu
        }
        (DeclaredQdiscType::Htb { .. }, Some(QdiscOptions::Htb(live))) => {
            let cfg = declared.htb_config().expect("matched the Htb arm");
            live.default_class == cfg.default_class && live.rate2quantum == cfg.r2q
        }
        (
            DeclaredQdiscType::FqCodel {
                limit,
                target_us,
                interval_us,
                quantum,
                ecn,
                ..
            },
            Some(QdiscOptions::FqCodel(live)),
        ) => {
            // Only the fields the declaration sets are written; the kernel
            // chooses the rest, so only those are compared.
            //
            // `flows` is deliberately *not* compared. It sizes the flow
            // table, which the kernel allocates at init and refuses to
            // resize, so a declared-vs-live difference cannot be acted
            // on: reporting it would put the qdisc in
            // `qdiscs_to_replace` on every diff, and the replace — which
            // must omit the attribute to avoid EINVAL — would never
            // close the gap. Changing `flows` needs the qdisc deleted
            // and re-added, which is the caller's decision to make, not
            // something to churn on (#361).
            limit.is_none_or(|l| live.limit == l)
                && target_us.is_none_or(|t| codel_round_trip_us(t) == live.target_us)
                && interval_us.is_none_or(|i| codel_round_trip_us(i) == live.interval_us)
                && quantum.is_none_or(|q| live.quantum == q)
                && ecn.is_none_or(|e| live.ecn == e)
        }
        (
            DeclaredQdiscType::Sfq {
                perturb_secs,
                limit,
                quantum,
                ..
            },
            Some(QdiscOptions::Sfq(live)),
        ) => {
            perturb_secs.is_none_or(|p| live.perturb_period == i32::try_from(p).unwrap_or(i32::MAX))
                && limit.is_none_or(|l| live.limit == l)
                && quantum.is_none_or(|q| live.quantum == q)
        }
        (DeclaredQdiscType::Prio { .. }, Some(QdiscOptions::Prio(live))) => {
            let cfg = declared.prio_config().expect("matched the Prio arm");
            live.bands == cfg.bands && live.priomap == cfg.priomap
        }
        // Same kind (the caller checked) and no options either way.
        (DeclaredQdiscType::Ingress | DeclaredQdiscType::Clsact, _) => true,
        // No parser for this kind, or no options reported: the old byte
        // compare, which errs towards "differs".
        (_, _) => {
            declared_options_bytes(declared).as_slice() == existing.raw_options().unwrap_or(&[])
        }
    }
}

/// Render the `TCA_OPTIONS` payload bytes for a declared qdisc type.
/// Every kind goes through its one shared lowering on
/// `DeclaredQdiscType` (`netem_config`, `tbf_config`, …), the same ones
/// `apply.rs::add_qdisc` installs from (#332, #349, #346). Used by
/// [`qdisc_params_match`] only as the fallback for kinds it cannot
/// compare field by field.
fn declared_options_bytes(t: &DeclaredQdiscType) -> Vec<u8> {
    let mut builder = MessageBuilder::new(0, 0);
    let start = builder.len();
    let write_result: Result<()> = match t {
        DeclaredQdiscType::Netem { .. } => t
            .netem_config()
            .expect("matched the Netem arm")
            .write_options(&mut builder),
        DeclaredQdiscType::Htb { .. } => t
            .htb_config()
            .expect("matched the Htb arm")
            .write_options(&mut builder),
        DeclaredQdiscType::FqCodel { .. } => t
            .fq_codel_config(true)
            .expect("matched the FqCodel arm")
            .write_options(&mut builder),
        DeclaredQdiscType::Tbf { .. } => t
            .tbf_config()
            .expect("matched the Tbf arm")
            .write_options(&mut builder),
        DeclaredQdiscType::Sfq { .. } => t
            .sfq_config()
            .expect("matched the Sfq arm")
            .write_options(&mut builder),
        DeclaredQdiscType::Prio { .. } => t
            .prio_config()
            .expect("matched the Prio arm")
            .write_options(&mut builder),
        DeclaredQdiscType::Ingress => IngressConfig::new().write_options(&mut builder),
        DeclaredQdiscType::Clsact => ClsactConfig::new().write_options(&mut builder),
    };
    let end = builder.len();
    // If write_options failed, return empty bytes — the diff will then
    // see "declared = empty, existing = something" → replace. Safe
    // failure mode.
    if write_result.is_err() {
        return Vec::new();
    }
    builder.as_bytes()[start..end].to_vec()
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::netlink::config::types::MacvlanMode;

    fn declared(name: &str, link_type: DeclaredLinkType) -> DeclaredLink {
        DeclaredLink {
            name: name.to_string(),
            link_type,
            state: LinkState::Unchanged,
            mtu: None,
            master: None,
            address: None,
        }
    }

    // -------------------------------------------------------------
    // Plan 186 §3c — topo-sort regression coverage (unit-level).
    // -------------------------------------------------------------

    #[test]
    fn topo_sort_no_op_when_empty_or_singleton() {
        let mut links: Vec<DeclaredLink> = vec![];
        topo_sort_links_to_add(&mut links);
        assert!(links.is_empty());

        let mut links = vec![declared("eth0", DeclaredLinkType::Dummy)];
        topo_sort_links_to_add(&mut links);
        assert_eq!(links.len(), 1);
        assert_eq!(links[0].name, "eth0");
    }

    #[test]
    fn topo_sort_independent_links_preserve_declared_order() {
        let mut links = vec![
            declared("eth1", DeclaredLinkType::Dummy),
            declared("eth0", DeclaredLinkType::Dummy),
            declared("br0", DeclaredLinkType::Bridge),
        ];
        topo_sort_links_to_add(&mut links);
        assert_eq!(
            links.iter().map(|l| l.name.clone()).collect::<Vec<_>>(),
            vec!["eth1", "eth0", "br0"],
            "independent links must keep declared order (stable sort)"
        );
    }

    #[test]
    fn topo_sort_promotes_parent_before_child_vlan() {
        // VLAN declared first, parent dummy declared second.
        let mut links = vec![
            declared(
                "eth0.42",
                DeclaredLinkType::Vlan {
                    parent: "eth0".into(),
                    vlan_id: 42, protocol: None,
                },
            ),
            declared("eth0", DeclaredLinkType::Dummy),
        ];
        topo_sort_links_to_add(&mut links);
        assert_eq!(
            links.iter().map(|l| l.name.clone()).collect::<Vec<_>>(),
            vec!["eth0", "eth0.42"],
            "parent must precede child after topo-sort"
        );
    }

    #[test]
    fn topo_sort_keeps_correct_order_when_already_sorted() {
        // Parent first, child second — already correct; preserved as-is.
        let mut links = vec![
            declared("eth0", DeclaredLinkType::Dummy),
            declared(
                "eth0.42",
                DeclaredLinkType::Vlan {
                    parent: "eth0".into(),
                    vlan_id: 42, protocol: None,
                },
            ),
        ];
        topo_sort_links_to_add(&mut links);
        assert_eq!(
            links.iter().map(|l| l.name.clone()).collect::<Vec<_>>(),
            vec!["eth0", "eth0.42"]
        );
    }

    #[test]
    fn topo_sort_handles_parent_not_in_batch() {
        // Parent "eth0" is NOT in links_to_add (created
        // out-of-band). The VLAN's parent ref doesn't count
        // for the sort — the link is emitted in declared order.
        let mut links = vec![
            declared("br0", DeclaredLinkType::Bridge),
            declared(
                "eth0.42",
                DeclaredLinkType::Vlan {
                    parent: "eth0".into(), // not in batch
                    vlan_id: 42, protocol: None,
                },
            ),
        ];
        topo_sort_links_to_add(&mut links);
        assert_eq!(
            links.iter().map(|l| l.name.clone()).collect::<Vec<_>>(),
            vec!["br0", "eth0.42"],
            "out-of-batch parent does NOT trigger reorder"
        );
    }

    #[test]
    fn topo_sort_handles_macvlan_parent_dep() {
        let mut links = vec![
            declared(
                "macv0",
                DeclaredLinkType::Macvlan {
                    parent: "eth0".into(),
                    mode: MacvlanMode::default(),
                },
            ),
            declared("eth0", DeclaredLinkType::Dummy),
        ];
        topo_sort_links_to_add(&mut links);
        assert_eq!(
            links.iter().map(|l| l.name.clone()).collect::<Vec<_>>(),
            vec!["eth0", "macv0"]
        );
    }

    #[test]
    fn topo_sort_chain_three_levels() {
        // Build dummy -> bridge (master via top) -> vlan(parent=bridge).
        // The chain we model is parent-child via Vlan only; bridge as
        // a parent reference doesn't fit the link_type's parent slot,
        // so this test pins a 2-level chain plus an unrelated link.
        let mut links = vec![
            declared(
                "eth0.42",
                DeclaredLinkType::Vlan {
                    parent: "eth0".into(),
                    vlan_id: 42, protocol: None,
                },
            ),
            declared("br0", DeclaredLinkType::Bridge), // unrelated
            declared("eth0", DeclaredLinkType::Dummy),
        ];
        topo_sort_links_to_add(&mut links);
        // After sort: eth0 + br0 are both root-level (no in-batch
        // parent dep) and emitted in declared order (eth0.42 deferred,
        // br0 ready, eth0 ready). Then eth0.42 lands.
        // Pass 1 ready set: br0, eth0 (declared order: eth0.42 deferred).
        // The pass iterates remaining in declared order, so output is:
        //   br0, eth0, eth0.42
        assert_eq!(
            links.iter().map(|l| l.name.clone()).collect::<Vec<_>>(),
            vec!["br0", "eth0", "eth0.42"]
        );
    }

    #[test]
    fn declared_options_bytes_differs_when_param_changes() {
        // Two HTB configs with different default_class should produce
        // different option bytes.
        let a = DeclaredQdiscType::Htb { default_class: 0x10 };
        let b = DeclaredQdiscType::Htb { default_class: 0x20 };
        assert_ne!(declared_options_bytes(&a), declared_options_bytes(&b));
    }

    #[test]
    fn declared_options_bytes_stable_for_same_input() {
        let cfg = DeclaredQdiscType::Netem {
            delay_us: Some(100_000),
            jitter_us: Some(10_000),
            loss_percent: Some(0.5),
            limit: Some(1000),
            duplicate_percent: None,
            corrupt_percent: None,
            reorder_percent: None,
            loss_correlation: None,
            delay_correlation: None,
            rate_bps: None,
            duplicate_correlation: None,
            corrupt_correlation: None,
            reorder_correlation: None,
            gap: None,
        };
        assert_eq!(declared_options_bytes(&cfg), declared_options_bytes(&cfg));
    }

    #[test]
    fn declared_options_bytes_differs_across_netem_params() {
        let a = DeclaredQdiscType::Netem {
            delay_us: Some(100_000),
            jitter_us: None,
            loss_percent: None,
            limit: None,
            duplicate_percent: None,
            corrupt_percent: None,
            reorder_percent: None,
            loss_correlation: None,
            delay_correlation: None,
            rate_bps: None,
            duplicate_correlation: None,
            corrupt_correlation: None,
            reorder_correlation: None,
            gap: None,
        };
        let b = DeclaredQdiscType::Netem {
            delay_us: Some(200_000),
            jitter_us: None,
            loss_percent: None,
            limit: None,
            duplicate_percent: None,
            corrupt_percent: None,
            reorder_percent: None,
            loss_correlation: None,
            delay_correlation: None,
            rate_bps: None,
            duplicate_correlation: None,
            corrupt_correlation: None,
            reorder_correlation: None,
            gap: None,
        };
        assert_ne!(declared_options_bytes(&a), declared_options_bytes(&b));
    }

    /// A live qdisc as a dump would report it: kind + raw `TCA_OPTIONS`.
    fn live(kind: &str, options: Option<Vec<u8>>) -> TcMessage {
        TcMessage {
            kind: Some(kind.to_string()),
            options,
            ..TcMessage::default()
        }
    }

    /// One native-endian `u32` attribute, the way the kernel writes it.
    fn attr_u32(attr_type: u16, value: u32) -> Vec<u8> {
        let mut out = Vec::with_capacity(8);
        out.extend_from_slice(&8u16.to_ne_bytes());
        out.extend_from_slice(&attr_type.to_ne_bytes());
        out.extend_from_slice(&value.to_ne_bytes());
        out
    }

    fn netem_declared(delay_us: u32) -> DeclaredQdiscType {
        DeclaredQdiscType::Netem {
            delay_us: Some(delay_us),
            jitter_us: Some(10_000),
            loss_percent: Some(0.5),
            limit: Some(1000),
            duplicate_percent: None,
            corrupt_percent: None,
            reorder_percent: Some(3.0),
            loss_correlation: None,
            delay_correlation: None,
            rate_bps: Some(12_500_000),
            duplicate_correlation: None,
            corrupt_correlation: None,
            reorder_correlation: Some(50.0),
            gap: Some(5),
        }
    }

    #[test]
    fn qdisc_params_match_treats_empty_existing_as_mismatch_when_declared_nonempty() {
        let cfg = DeclaredQdiscType::Htb { default_class: 0x10 };
        // Existing has no options at all — should not match a non-empty declared.
        assert!(!qdisc_params_match(&cfg, &live("htb", None)));
        assert!(!qdisc_params_match(&cfg, &live("htb", Some(Vec::new()))));
    }

    #[test]
    fn qdisc_params_match_clsact_has_no_options() {
        // Clsact emits zero option bytes; matches an empty existing.
        let cfg = DeclaredQdiscType::Clsact;
        assert!(qdisc_params_match(&cfg, &live("clsact", Some(Vec::new()))));
        assert!(qdisc_params_match(&cfg, &live("clsact", None)));
    }

    // ---- #346 — field compare against the kernel's echo, not a byte compare ----

    /// The kernel reports attributes netem was never sent (`ECN`, `CORR`,
    /// …). A declaration must still match its own qdisc.
    #[test]
    fn netem_matches_the_kernels_echo_with_extra_attributes() {
        use crate::netlink::types::tc::qdisc::netem::TCA_NETEM_ECN;
        let declared = netem_declared(100_000);
        let mut echo = declared_options_bytes(&declared);
        echo.extend(attr_u32(TCA_NETEM_ECN, 0));
        assert_ne!(declared_options_bytes(&declared), echo, "the byte compare would say differs");
        assert!(qdisc_params_match(&declared, &live("netem", Some(echo.clone()))));
        // …and a real change is still a change.
        assert!(!qdisc_params_match(&netem_declared(200_000), &live("netem", Some(echo))));
    }

    /// codel stores time in 2^-10 s units: a 20 ms target is echoed as
    /// 19999 µs. Compare in the kernel's quantisation, and only the fields
    /// the declaration sets.
    #[test]
    fn fq_codel_compares_in_codel_ticks_and_only_declared_fields() {
        use crate::netlink::types::tc::qdisc::fq_codel::TCA_FQ_CODEL_TARGET;
        let fq = |target_us, flows, quantum, ecn| DeclaredQdiscType::FqCodel {
            limit: None,
            target_us,
            interval_us: None,
            flows,
            quantum,
            ecn,
        };
        let declared = fq(Some(20_000), None, None, None);
        let echo = live("fq_codel", Some(attr_u32(TCA_FQ_CODEL_TARGET, 19_999)));
        assert!(qdisc_params_match(&declared, &echo));
        let other = fq(Some(18_000), None, None, None);
        assert!(!qdisc_params_match(&other, &echo));
        // Nothing declared: whatever the kernel chose is fine.
        let bare = fq(None, None, None, None);
        assert!(qdisc_params_match(&bare, &echo));
    }

    /// The 0.28 fq_codel knobs (#361) take part in the comparison, and
    /// keep the "only what was declared" rule: an undeclared field must
    /// not make the diff fire, and a declared one that drifted must.
    ///
    /// `flows` is the exception and is asserted *not* to fire — see the
    /// comment in `qdisc_params_match`: the kernel will not resize the
    /// flow table, so a difference there is not something a replace can
    /// close, and comparing it would mean churning on every diff.
    #[test]
    fn fq_codel_compares_the_0_28_knobs() {
        use crate::netlink::types::tc::qdisc::fq_codel::{
            TCA_FQ_CODEL_ECN, TCA_FQ_CODEL_FLOWS, TCA_FQ_CODEL_QUANTUM,
        };
        let fq = |flows, quantum, ecn| DeclaredQdiscType::FqCodel {
            limit: None,
            target_us: None,
            interval_us: None,
            flows,
            quantum,
            ecn,
        };
        let mut opts = attr_u32(TCA_FQ_CODEL_FLOWS, 1024);
        opts.extend(attr_u32(TCA_FQ_CODEL_QUANTUM, 300));
        opts.extend(attr_u32(TCA_FQ_CODEL_ECN, 1));
        let echo = live("fq_codel", Some(opts));

        assert!(qdisc_params_match(&fq(Some(1024), Some(300), Some(true)), &echo));
        assert!(
            qdisc_params_match(&fq(None, None, None), &echo),
            "undeclared knobs must not make the diff fire"
        );
        assert!(
            qdisc_params_match(&fq(Some(512), None, None), &echo),
            "a flows difference is not actionable, so it must not make the diff fire"
        );
        assert!(!qdisc_params_match(&fq(None, Some(1514), None), &echo));
        assert!(!qdisc_params_match(&fq(None, None, Some(false)), &echo));
    }

    #[test]
    fn htb_default_class_is_compared_as_a_field() {
        use crate::netlink::types::tc::qdisc::htb::TCA_HTB_DIRECT_QLEN;
        let declared = DeclaredQdiscType::Htb { default_class: 0x10 };
        let mut echo = declared_options_bytes(&declared);
        echo.extend(attr_u32(TCA_HTB_DIRECT_QLEN, 1000));
        assert!(qdisc_params_match(&declared, &live("htb", Some(echo.clone()))));
        let other = DeclaredQdiscType::Htb { default_class: 0x20 };
        assert!(!qdisc_params_match(&other, &live("htb", Some(echo))));
    }

    #[test]
    fn tbf_rate_burst_and_limit_are_compared_as_fields() {
        let tbf = |rate_bps, burst_bytes, peakrate_bps, mtu| DeclaredQdiscType::Tbf {
            rate_bps,
            burst_bytes,
            limit_bytes: Some(65_536),
            peakrate_bps,
            mtu,
        };
        let declared = tbf(125_000, 32_768, None, None);
        let echo = live("tbf", Some(declared_options_bytes(&declared)));
        assert!(qdisc_params_match(&declared, &echo));
        let faster = tbf(250_000, 32_768, None, None);
        assert!(!qdisc_params_match(&faster, &echo));
        let bigger_bucket = tbf(125_000, 65_536, None, None);
        assert!(!qdisc_params_match(&bigger_bucket, &echo));

        // 0.28 (#361): peakrate and mtu are part of the comparison too,
        // so a drift in either is not silently accepted. Both come back
        // in bytes (PRATE64 and TCA_TBF_PBURST), so no tick round-trip.
        let peaked = tbf(125_000, 32_768, Some(250_000), Some(1600));
        let peaked_echo = live("tbf", Some(declared_options_bytes(&peaked)));
        assert!(qdisc_params_match(&peaked, &peaked_echo));
        assert!(
            !qdisc_params_match(&tbf(125_000, 32_768, Some(500_000), Some(1600)), &peaked_echo),
            "a changed peakrate must be seen"
        );
        assert!(
            !qdisc_params_match(&tbf(125_000, 32_768, Some(250_000), Some(9000)), &peaked_echo),
            "a changed mtu must be seen"
        );
        assert!(
            !qdisc_params_match(&declared, &peaked_echo),
            "dropping the peakrate must be seen"
        );
    }

    #[test]
    fn sfq_and_prio_compare_their_declared_fields() {
        let mk_sfq = |perturb_secs, limit, quantum| DeclaredQdiscType::Sfq {
            perturb_secs,
            limit,
            quantum,
        };
        let sfq = mk_sfq(Some(10), None, None);
        let echo = live("sfq", Some(declared_options_bytes(&sfq)));
        assert!(qdisc_params_match(&sfq, &echo));
        let other = mk_sfq(Some(20), None, None);
        assert!(!qdisc_params_match(&other, &echo));

        // 0.28 (#361): sfq's limit and quantum are declarable now, and
        // compared the same "only what was declared" way.
        let tuned = mk_sfq(Some(10), Some(200), Some(1514));
        let tuned_echo = live("sfq", Some(declared_options_bytes(&tuned)));
        assert!(qdisc_params_match(&tuned, &tuned_echo));
        assert!(qdisc_params_match(&mk_sfq(None, None, None), &tuned_echo));
        assert!(!qdisc_params_match(&mk_sfq(None, Some(64), None), &tuned_echo));
        assert!(!qdisc_params_match(&mk_sfq(None, None, Some(300)), &tuned_echo));

        let prio = DeclaredQdiscType::Prio { bands: Some(3) };
        let echo = live("prio", Some(declared_options_bytes(&prio)));
        assert!(qdisc_params_match(&prio, &echo));
        let other = DeclaredQdiscType::Prio { bands: Some(4) };
        assert!(!qdisc_params_match(&other, &echo));
    }

    // ---- Plan 188 §2.2 — ApplyOptions builders ----

    #[test]
    fn apply_options_builders_compose() {
        use super::super::apply::ApplyOptions;
        let opts = ApplyOptions::default()
            .with_dry_run(true)
            .with_continue_on_error(true);
        assert!(opts.dry_run);
        assert!(opts.continue_on_error);
    }

    #[test]
    fn apply_options_default_is_safe() {
        use super::super::apply::ApplyOptions;
        let opts = ApplyOptions::default();
        assert!(!opts.dry_run);
        assert!(!opts.continue_on_error);
    }

    // ---- Plan 188 §2.5 — LinkChanges::Display ----

    #[test]
    fn link_changes_display_matches_summary() {
        let c = LinkChanges {
            set_mtu: Some(9000),
            set_up: true,
            ..LinkChanges::default()
        };
        assert_eq!(c.to_string(), c.summary());
        assert!(c.to_string().contains("mtu=9000"));
        assert!(c.to_string().contains("up"));
    }

    #[test]
    fn link_changes_display_empty_when_no_changes() {
        let c = LinkChanges::default();
        assert_eq!(c.to_string(), "");
    }

    // ---- Plan 188 §2.3 — RouteBuilder::default_v{4,6} ----

    #[test]
    fn default_v4_route_is_zero_zero() {
        use super::super::types::RouteBuilder;
        let r = RouteBuilder::default_v4();
        // Internal state — verify via the via() chain works
        // and the destination round-trips.
        let with_gw = r.via("192.0.2.1");
        // Smoke-test by constructing; the field isn't directly
        // exposed but apply paths read it.
        drop(with_gw);
    }

    #[test]
    fn default_v6_route_is_unspecified_slash_zero() {
        use super::super::types::RouteBuilder;
        let r = RouteBuilder::default_v6();
        let with_gw = r.via("2001:db8::1");
        drop(with_gw);
    }

    // ----- Plan 207c M5 — topo-sort dep coverage -----

    #[test]
    fn topo_sort_promotes_vxlan_underlay_before_vxlan() {
        // Pre-Plan 207c, VXLAN underlay was NOT a recognized
        // dep — declaring VXLAN before underlay dummy
        // reproduced the Plan 186 bug class.
        let mut links = vec![
            declared(
                "vxlan42",
                DeclaredLinkType::Vxlan {
                    vni: 42,
                    remote: None,
                    local: None,
                    port: None,
                    underlay_dev: Some("eth0".into()),
                },
            ),
            declared("eth0", DeclaredLinkType::Dummy),
        ];
        topo_sort_links_to_add(&mut links);
        let positions: HashMap<String, usize> = links
            .iter()
            .enumerate()
            .map(|(i, l)| (l.name.clone(), i))
            .collect();
        assert!(
            positions["eth0"] < positions["vxlan42"],
            "underlay must be created before VXLAN"
        );
    }

    #[test]
    fn topo_sort_promotes_master_before_slave() {
        // Declaring `dummy0.master("br0")` before `br0` should
        // get reordered so br0 lands first.
        let mut dummy = declared("dummy0", DeclaredLinkType::Dummy);
        dummy.master = Some("br0".into());
        let mut links = vec![dummy, declared("br0", DeclaredLinkType::Bridge)];
        topo_sort_links_to_add(&mut links);
        let positions: HashMap<String, usize> = links
            .iter()
            .enumerate()
            .map(|(i, l)| (l.name.clone(), i))
            .collect();
        assert!(
            positions["br0"] < positions["dummy0"],
            "master must be created before slave"
        );
    }

    // ---- Plan 183 — Display for NetworkDiff ----

    #[test]
    fn display_matches_summary() {
        let diff = ConfigDiff::default();
        // Plan 188 §2.6 — `summary()` is deprecated; this test
        // pins the equivalence guarantee for the deprecation
        // window (removed in 0.20). Plan 205 (0.19) removed the
        // `links_to_remove` collection along with the purge knob,
        // so the second assertion now exercises the
        // `links_to_modify` collection instead.
        #[allow(deprecated)]
        {
            assert_eq!(format!("{diff}"), diff.summary());
            let mut d = ConfigDiff::default();
            d.links_to_modify
                .push(("eth0".to_string(), LinkChanges::default()));
            assert_eq!(format!("{d}"), d.summary());
        }
    }

    // ---- Plan 205 (re-wired) — purge diff accounting + options ----

    fn declared_addr(dev: &str, addr: &str, plen: u8) -> DeclaredAddress {
        DeclaredAddress {
            dev: dev.to_string(),
            address: addr.parse().unwrap(),
            prefix_len: plen,
        }
    }

    fn declared_route(dst: &str, plen: u8) -> DeclaredRoute {
        DeclaredRoute {
            destination: dst.parse().unwrap(),
            prefix_len: plen,
            gateway: None,
            dev: None,
            metric: None,
            table: Some(254),
            route_type: DeclaredRouteType::Unicast,
        }
    }

    #[test]
    fn diff_options_purge_builder_toggles_flag() {
        assert!(!DiffOptions::default().purge);
        assert!(DiffOptions::default().purge(true).purge);
        assert!(!DiffOptions::default().purge(true).purge(false).purge);
    }

    // ---- #333 / #335 — purge scope beyond the main table ----

    /// A kernel `static` unicast route in `table`, as the dump reports it.
    fn kernel_static_route(dst: &str, plen: u8, table: u32) -> RouteMessage {
        crate::netlink::messages::RouteMessageBuilder::new()
            .destination(dst.parse().unwrap(), plen)
            .table(table)
            .protocol(RouteProtocol::Static)
            .route_type(RouteType::Unicast)
            .build()
    }

    fn purge_routes(config: &NetworkConfig, current: &[RouteMessage], opts: DiffOptions) -> Vec<(String, u32)> {
        let mut diff = ConfigDiff::default();
        diff_routes(config, current, &HashMap::new(), &opts, &mut diff);
        diff.routes_to_remove
            .iter()
            .map(|r| (format!("{}/{}", r.destination, r.prefix_len), r.table.unwrap()))
            .collect()
    }

    #[test]
    fn purge_scope_is_main_plus_declared_plus_listed_tables() {
        let config = NetworkConfig::new()
            .route("10.1.0.0/24", |r| r.table(100))
            .unwrap();
        let opts = DiffOptions::default().purge(true);
        assert_eq!(
            opts.purge_table_scope(&config),
            HashSet::from([254, 100]),
            "main plus the table a declared route names"
        );
        let opts = DiffOptions::default().purge(true).purge_tables([200, 201]);
        assert_eq!(opts.purge_table_scope(&config), HashSet::from([254, 100, 200, 201]));
        assert_eq!(
            DiffOptions::default().purge_table_scope(&NetworkConfig::new()),
            HashSet::from([254]),
            "a config with no routes owns main and nothing else"
        );
    }

    #[test]
    fn purge_removes_an_undeclared_route_from_a_declared_table() {
        // Table 100 is owned: the config declares 10.1.0.0/24 into it.
        // 10.2.0.0/24 in the same table left the declaration → purged.
        let config = NetworkConfig::new()
            .route("10.1.0.0/24", |r| r.table(100))
            .unwrap();
        let current = [
            kernel_static_route("10.1.0.0", 24, 100),
            kernel_static_route("10.2.0.0", 24, 100),
        ];
        let removed = purge_routes(&config, &current, DiffOptions::default().purge(true));
        assert_eq!(removed, vec![("10.2.0.0/24".to_string(), 100)]);
    }

    #[test]
    fn purge_leaves_tables_the_config_never_mentions_alone() {
        // Table 100 is not owned by a config that only declares into
        // main — its routes are somebody else's.
        let config = NetworkConfig::new().route("10.1.0.0/24", |r| r).unwrap();
        let current = [
            kernel_static_route("10.1.0.0", 24, 254),
            kernel_static_route("10.9.0.0", 24, 254),
            kernel_static_route("10.2.0.0", 24, 100),
        ];
        let removed = purge_routes(&config, &current, DiffOptions::default().purge(true));
        assert_eq!(
            removed,
            vec![("10.9.0.0/24".to_string(), 254)],
            "only the undeclared main-table route; table 100 is out of scope"
        );
    }

    #[test]
    fn purge_tables_reaches_a_table_with_no_declared_route_left() {
        // The last VRF route left the declaration; the caller still
        // owns the table and says so.
        let config = NetworkConfig::new();
        let current = [kernel_static_route("10.2.0.0", 24, 100)];
        assert!(
            purge_routes(&config, &current, DiffOptions::default().purge(true)).is_empty(),
            "without purge_tables the now-unmentioned table is left alone"
        );
        let removed = purge_routes(
            &config,
            &current,
            DiffOptions::default().purge(true).purge_tables([100]),
        );
        assert_eq!(removed, vec![("10.2.0.0/24".to_string(), 100)]);
    }

    #[test]
    fn purge_never_touches_local_or_kernel_protocol_routes_in_scope() {
        let config = NetworkConfig::new()
            .route("10.1.0.0/24", |r| r.table(100))
            .unwrap();
        let kernel_proto = crate::netlink::messages::RouteMessageBuilder::new()
            .destination("10.3.0.0".parse().unwrap(), 24)
            .table(100)
            .protocol(RouteProtocol::Kernel)
            .route_type(RouteType::Unicast)
            .build();
        let local = crate::netlink::messages::RouteMessageBuilder::new()
            .destination("10.1.0.1".parse().unwrap(), 32)
            .table(255)
            .protocol(RouteProtocol::Kernel)
            .route_type(RouteType::Local)
            .build();
        let removed = purge_routes(&config, &[kernel_proto, local], DiffOptions::default().purge(true));
        assert!(removed.is_empty(), "got {removed:?}");
    }

    #[test]
    fn removal_collections_count_toward_is_empty_and_change_count() {
        let mut d = ConfigDiff::default();
        assert!(d.is_empty());
        assert_eq!(d.change_count(), 0);

        d.addresses_to_remove
            .push(declared_addr("eth0", "10.0.0.5", 24));
        assert!(!d.is_empty());
        assert_eq!(d.change_count(), 1);

        d.routes_to_remove.push(declared_route("10.1.0.0", 24));
        assert!(!d.is_empty());
        assert_eq!(d.change_count(), 2);
    }

    #[test]
    fn display_renders_removal_lines() {
        let mut d = ConfigDiff::default();
        d.addresses_to_remove
            .push(declared_addr("eth0", "10.0.0.5", 24));
        d.routes_to_remove.push(declared_route("10.1.0.0", 24));
        let rendered = format!("{d}");
        assert!(
            rendered.contains("- address 10.0.0.5/24 on eth0"),
            "address removal line missing: {rendered}"
        );
        assert!(
            rendered.contains("- route 10.1.0.0/24"),
            "route removal line missing: {rendered}"
        );
    }
}