feat: support complete boot-interface targets

A caller can know both a boot interface's MAC address and its vendor-native Redfish interface ID, but `BootInterfaceRef` could only accept one at a time. If the first call changed the BMC before returning an error, retrying the complete mutation with the other identifier can repeat that work.

So, `BootInterfaceRef::Pair` keeps both identifiers together for one operation. `resolve_boot_interface_mac` uses the supplied MAC without another Redfish lookup, while Dell uses the interface ID for `NetworkDeviceFunction` matching and slot selection without falling back to the MAC.

The existing `Mac` and `InterfaceId` variants keep their behavior. Since `BootInterfaceRef` is a public exhaustive enum, downstream exhaustive matches need a `Pair` arm when they update to this version.

Tests added!

This supports #109

Signed-off-by: Chet Nichols III <chetn@nvidia.com>

Author: chet

src/dell.rs

@@ -72,6 +72,8 @@ const MAX_ACCOUNT_ID: u8 = 16;
 ///   matches partition `NIC.Slot.7-1-1`. Equality also matches. This lets us
 ///   locate the NDF for partitions whose MAC has been stripped (the
 ///   NicMode-Disabled case).
+/// - [`BootInterfaceRef::Pair`] uses the same interface-ID match as
+///   [`BootInterfaceRef::InterfaceId`]. Its MAC is not a fallback.
 fn nw_dev_func_matches(
     nw_dev_func: &NetworkDeviceFunction,
     boot_interface: crate::BootInterfaceRef<'_>,
@@ -82,7 +84,11 @@ fn nw_dev_func_matches(
             .as_ref()
             .and_then(|e| e.mac_address.as_ref())
             .is_some_and(|m| m.eq_ignore_ascii_case(&target.to_string())),
-        crate::BootInterfaceRef::InterfaceId(target) => nw_dev_func
+        crate::BootInterfaceRef::InterfaceId(target)
+        | crate::BootInterfaceRef::Pair {
+            interface_id: target,
+            ..
+        } => nw_dev_func
             .id
             .as_deref()
             .is_some_and(|ndf_id| target == ndf_id || target.starts_with(&format!("{ndf_id}-"))),
@@ -2496,18 +2502,21 @@ impl Bmc {
     /// `HttpDev1Interface` BIOS attribute and the first-boot-option check key on
     /// for a boot interface.
     ///
-    /// A [`crate::BootInterfaceRef::InterfaceId`] already *is* the slot id, so it
-    /// is used directly -- this is the stable identifier that survives a NicMode
-    /// flip (or any case where the `NetworkDeviceFunction`'s `Ethernet.MACAddress`
-    /// is empty): a by-MAC lookup can't find the NDF, but the partition id still
-    /// resolves it. A [`crate::BootInterfaceRef::Mac`] is resolved to the slot via
-    /// the `NetworkDeviceFunction`, matched by MAC. `None` is the zero-DPU case.
+    /// [`crate::BootInterfaceRef::InterfaceId`] and
+    /// [`crate::BootInterfaceRef::Pair`] already contain the slot id, so it is
+    /// used directly. This stable identifier survives a NicMode flip or any case
+    /// where the `NetworkDeviceFunction`'s `Ethernet.MACAddress` is empty.
+    /// [`crate::BootInterfaceRef::Mac`] is resolved to the slot through the
+    /// `NetworkDeviceFunction`, matched by MAC. `None` is the zero-DPU case.
     async fn nic_slot_for(
         &self,
         boot_interface: Option<crate::BootInterfaceRef<'_>>,
     ) -> Result<String, RedfishError> {
         Ok(match boot_interface {
-            Some(crate::BootInterfaceRef::InterfaceId(id)) => id.to_string(),
+            Some(crate::BootInterfaceRef::InterfaceId(id))
+            | Some(crate::BootInterfaceRef::Pair {
+                interface_id: id, ..
+            }) => id.to_string(),
             Some(crate::BootInterfaceRef::Mac(mac)) => self.dpu_nic_slot(&mac.to_string()).await?,
             None => String::new(),
         })
@@ -2778,9 +2787,9 @@ impl std::fmt::Display for XmlPcdata<'_> {
 
 #[cfg(test)]
 mod tests {
-    use super::{boot_option_name_matches, nw_dev_func_matches, XmlPcdata};
+    use super::{boot_option_name_matches, nw_dev_func_matches, Bmc, XmlPcdata};
     use crate::model::network_device_function::{Ethernet, NetworkDeviceFunction};
-    use crate::BootInterfaceRef;
+    use crate::{BootInterfaceRef, Endpoint, RedfishClientPool};
     use std::collections::HashMap;
 
     fn ndf_with(id: Option<&str>, mac: Option<&str>) -> NetworkDeviceFunction {
@@ -2840,6 +2849,56 @@ mod tests {
         assert!(nw_dev_func_matches(&populated, BootInterfaceRef::Mac(mac)));
     }
 
+    #[test]
+    fn nw_dev_func_pair_matches_by_interface_id() {
+        let mac: mac_address::MacAddress = "C4:70:BD:2C:3C:0A".parse().unwrap();
+        let pair = BootInterfaceRef::Pair {
+            mac_address: mac,
+            interface_id: "NIC.Slot.40-1-1",
+        };
+
+        assert!(nw_dev_func_matches(
+            &ndf_with(Some("NIC.Slot.40-1-1"), None),
+            pair,
+        ));
+        assert!(nw_dev_func_matches(
+            &ndf_with(Some("NIC.Slot.40-1"), None),
+            pair,
+        ));
+    }
+
+    #[test]
+    fn nw_dev_func_pair_does_not_fall_back_to_mac() {
+        let mac: mac_address::MacAddress = "C4:70:BD:2C:3C:0A".parse().unwrap();
+        let pair = BootInterfaceRef::Pair {
+            mac_address: mac,
+            interface_id: "NIC.Slot.40-1-1",
+        };
+        let matching_mac_wrong_id = ndf_with(Some("NIC.Slot.7-1-1"), Some("c4:70:bd:2c:3c:0a"));
+
+        assert!(!nw_dev_func_matches(&matching_mac_wrong_id, pair));
+    }
+
+    #[tokio::test]
+    async fn nic_slot_for_pair_uses_interface_id_directly() {
+        let pool = RedfishClientPool::builder().build().unwrap();
+        let standard = pool
+            .create_standard_client(Endpoint::default())
+            .expect("test Redfish client should be constructed without a request");
+        let bmc = Bmc::new(*standard).unwrap();
+        let mac: mac_address::MacAddress = "C4:70:BD:2C:3C:0A".parse().unwrap();
+
+        let got = bmc
+            .nic_slot_for(Some(BootInterfaceRef::Pair {
+                mac_address: mac,
+                interface_id: "NIC.Slot.40-1-1",
+            }))
+            .await
+            .expect("pair should use its interface ID without querying the empty endpoint");
+
+        assert_eq!(got, "NIC.Slot.40-1-1");
+    }
+
     #[test]
     fn boot_option_name_matches_legacy_and_extended_names() {
         let expected = "HTTP Device 1: NIC in Slot 4 Port 1 Partition 1";

src/lib.rs

@@ -224,13 +224,12 @@ pub trait Redfish: Send + Sync + 'static {
 
     /// Sets up a reasonable UEFI configuration.
     /// remember to call lockdown() afterwards to secure the server
-    /// - boot_interface: identifies the NIC you wish to boot from. Either a
-    ///   `BootInterfaceRef::Mac` (existing behavior: vendor impl looks up
-    ///   the partition by MAC via its BMC enumeration) or a
-    ///   `BootInterfaceRef::InterfaceId` (vendor-native Redfish
-    ///   `EthernetInterface.Id` — used when we already know the interface
-    ///   partition ID (and don't need to look it up by MAC). One case
-    ///   being if we flip a DPU to NIC mode.
+    /// - boot_interface: identifies the NIC you wish to boot from. A
+    ///   `BootInterfaceRef::Mac` uses the existing vendor lookup by MAC, while
+    ///   `BootInterfaceRef::InterfaceId` uses a vendor-native Redfish
+    ///   `EthernetInterface.Id`. `BootInterfaceRef::Pair` supplies both so each
+    ///   vendor can use its native identifier without resolving one from the
+    ///   other.
     ///   If not given we look for a Mellanox Bluefield DPU and use that.
     ///   Not applicable to Supermicro and the DPU itself.
     ///   bios_profiles: Map of vendor/model (with spaces replaced by underscores)/profile/type
@@ -537,11 +536,11 @@ pub trait Redfish: Send + Sync + 'static {
 
     /// Change the boot order so the system will boot from the chosen NIC first.
     ///
-    /// `boot_interface` selects the target NIC. A `BootInterfaceRef::Mac` is the
-    /// classic path: the vendor impl looks the NIC up via its BMC enumeration
-    /// by MAC. A `BootInterfaceRef::InterfaceId` is the vendor-native Redfish
-    /// `EthernetInterface.Id` -- used when the caller already knows the
-    /// partition ID.
+    /// `boot_interface` selects the target NIC. A `BootInterfaceRef::Mac` uses
+    /// the existing vendor lookup by MAC, while `BootInterfaceRef::InterfaceId`
+    /// uses a vendor-native Redfish `EthernetInterface.Id`.
+    /// `BootInterfaceRef::Pair` supplies both so the vendor can use its native
+    /// identifier directly.
     fn set_boot_order_dpu_first<'a>(
         &'a self,
         boot_interface: BootInterfaceRef<'a>,
@@ -772,8 +771,7 @@ impl Status {
 }
 
 /// How a caller identifies a boot interface to [`Redfish::machine_setup`]
-/// and supporting query methods. Callers can pass either form; vendor
-/// impls handle both.
+/// and supporting query methods.
 #[derive(Debug, Clone, Copy)]
 pub enum BootInterfaceRef<'a> {
     /// MAC address of the boot interface. Vendor impl translates it into
@@ -783,25 +781,34 @@ pub enum BootInterfaceRef<'a> {
     /// interface (e.g. `"NIC.Slot.7-1-1"`). Vendor impl uses it
     /// directly.
     InterfaceId(&'a str),
+    /// Complete identity for one boot interface. Both fields must identify the
+    /// same interface; this is one target, not an instruction to try both.
+    /// MAC-oriented vendor paths use `mac_address`, while interface-ID-oriented
+    /// paths use `interface_id`.
+    Pair {
+        mac_address: mac_address::MacAddress,
+        interface_id: &'a str,
+    },
 }
 
 impl BootInterfaceRef<'_> {
-    /// Returns the MAC if this is the [`BootInterfaceRef::Mac`] variant.
-    /// Returns `None` if this is the [`BootInterfaceRef::InterfaceId`]
-    /// variant.
+    /// Returns the supplied MAC when this selector contains one.
     pub fn mac(&self) -> Option<mac_address::MacAddress> {
         match self {
-            BootInterfaceRef::Mac(mac) => Some(*mac),
+            BootInterfaceRef::Mac(mac)
+            | BootInterfaceRef::Pair {
+                mac_address: mac, ..
+            } => Some(*mac),
             BootInterfaceRef::InterfaceId(_) => None,
         }
     }
 }
 
 /// Returns the MAC address for a [`BootInterfaceRef`].
-/// [`BootInterfaceRef::Mac`] is a pass-through; [`BootInterfaceRef::InterfaceId`]
-/// is resolved by fetching `Systems/{}/EthernetInterfaces/{id}` via the
-/// Redfish-standard `EthernetInterface` resource (every vendor
-/// implements it).
+/// [`BootInterfaceRef::Mac`] and [`BootInterfaceRef::Pair`] pass through their
+/// supplied MAC. [`BootInterfaceRef::InterfaceId`] is resolved by fetching
+/// `Systems/{}/EthernetInterfaces/{id}` via the Redfish-standard
+/// `EthernetInterface` resource (every vendor implements it).
 ///
 /// Used by methods that compare against a MAC (verification paths that
 /// walk boot options by MAC substring, etc.) so the caller can pass
@@ -811,7 +818,10 @@ pub async fn resolve_boot_interface_mac<R: Redfish + ?Sized>(
     boot_interface: BootInterfaceRef<'_>,
 ) -> Result<String, RedfishError> {
     match boot_interface {
-        BootInterfaceRef::Mac(mac) => Ok(mac.to_string()),
+        BootInterfaceRef::Mac(mac)
+        | BootInterfaceRef::Pair {
+            mac_address: mac, ..
+        } => Ok(mac.to_string()),
         BootInterfaceRef::InterfaceId(id) => {
             let eif = redfish.get_system_ethernet_interface(id).await?;
             extract_resolved_mac(eif.mac_address.as_deref(), id)
@@ -945,6 +955,37 @@ mod tests {
         assert!(r.mac().is_none());
     }
 
+    #[test]
+    fn boot_interface_ref_pair_mac_returns_inner() {
+        let mac: mac_address::MacAddress = "AA:BB:CC:DD:EE:01".parse().unwrap();
+        let r = BootInterfaceRef::Pair {
+            mac_address: mac,
+            interface_id: "NIC.Slot.7-1-1",
+        };
+        assert_eq!(r.mac(), Some(mac));
+    }
+
+    #[tokio::test]
+    async fn resolve_boot_interface_mac_uses_pair_mac_without_lookup() {
+        let pool = RedfishClientPool::builder().build().unwrap();
+        let redfish = pool
+            .create_standard_client(Endpoint::default())
+            .expect("test Redfish client should be constructed without a request");
+        let mac: mac_address::MacAddress = "AA:BB:CC:DD:EE:01".parse().unwrap();
+
+        let got = resolve_boot_interface_mac(
+            redfish.as_ref(),
+            BootInterfaceRef::Pair {
+                mac_address: mac,
+                interface_id: "NIC.Slot.7-1-1",
+            },
+        )
+        .await
+        .expect("pair should use its MAC without querying the empty endpoint");
+
+        assert_eq!(got, mac.to_string());
+    }
+
     #[test]
     fn extract_resolved_mac_passes_through_populated_mac() {
         let got = super::extract_resolved_mac(Some("AA:BB:CC:DD:EE:01"), "NIC.Slot.7-1-1")