grafos_std/

net.rs

//! Network resource module.
//!
//! Provides typed access to fabric network resources via NET host
//! functions. Programs request leased network interfaces with optional
//! bandwidth guarantees. The underlying NET_ALLOC control op (0x0700)
//! is implemented in fabricbiosd with macvlan/SR-IOV VF allocation.
//! On `wasm32` targets, the host functions link to real imports
//! (`fabricbios_net_v0`). On native targets, mock implementations
//! allow testing without network hardware.
//!
//! # Example
//!
//! ```rust
//! use grafos_std::net::{NetBuilder, FabricNet};
//!
//! # grafos_std::host::reset_mock();
//! # grafos_std::host::mock_set_net_interface("eth-fab0", 1_000_000_000);
//! let lease = NetBuilder::new().min_bandwidth(1_000_000_000).acquire()?;
//! assert_eq!(lease.net().bandwidth(), 1_000_000_000);
//! assert_eq!(lease.net().interface_name(), "eth-fab0");
//! # Ok::<(), grafos_std::FabricError>(())
//! ```

extern crate alloc;
use alloc::string::String;

use crate::error::{FabricError, Result};
use crate::host;
use crate::lease::{self, LeaseInfo, LeaseStatus, SharedLeaseState};

const LEASE_TAG_NET: u8 = 0x03;

/// Safe handle to a leased fabric network interface.
///
/// Provides access to the interface name and guaranteed bandwidth
/// of a leased NIC (macvlan or SR-IOV VF). Created via
/// [`NetBuilder::acquire`].
#[derive(Debug)]
pub struct FabricNet {
    interface_name: String,
    bandwidth: u64,
}

impl FabricNet {
    /// Returns the guaranteed bandwidth in bits per second.
    pub fn bandwidth(&self) -> u64 {
        self.bandwidth
    }

    /// Returns the name of the leased network interface.
    pub fn interface_name(&self) -> &str {
        &self.interface_name
    }
}

/// A network lease that auto-frees on drop.
///
/// Wraps a [`FabricNet`] handle with RAII lifecycle management.
/// Created via [`NetBuilder::acquire`].
#[derive(Debug)]
pub struct NetLease {
    state: SharedLeaseState,
    net: FabricNet,
}

impl NetLease {
    /// Access the underlying [`FabricNet`] handle.
    pub fn net(&self) -> &FabricNet {
        &self.net
    }

    /// Lease metadata snapshot (id, creation time, expiry, and status).
    pub fn info(&self) -> LeaseInfo {
        lease::info(&self.state)
    }

    /// Unique lease identifier.
    pub fn lease_id(&self) -> u128 {
        lease::lease_id(&self.state)
    }

    /// Lease creation timestamp (unix seconds).
    pub fn created_at_unix_secs(&self) -> u64 {
        lease::created_at_unix_secs(&self.state)
    }

    /// Lease expiry timestamp (unix seconds).
    pub fn expires_at_unix_secs(&self) -> u64 {
        lease::expires_at_unix_secs(&self.state)
    }

    /// Current lease status.
    pub fn status(&self) -> LeaseStatus {
        lease::status(&self.state)
    }

    /// Renew the lease TTL by `duration_secs`.
    pub fn renew(&self, duration_secs: u64) -> Result<()> {
        lease::renew(&self.state, duration_secs)
    }

    /// Explicitly revoke/free this lease.
    pub fn free(&self) {
        lease::free(&self.state);
    }
}

impl Drop for NetLease {
    fn drop(&mut self) {
        lease::free(&self.state);
    }
}

/// Builder for acquiring a fabric network lease.
///
/// Allows specifying minimum bandwidth requirements.
///
/// # Examples
///
/// ```rust
/// use grafos_std::net::NetBuilder;
///
/// # grafos_std::host::reset_mock();
/// # grafos_std::host::mock_set_net_interface("eth-fab0", 10_000_000_000);
/// let lease = NetBuilder::new().min_bandwidth(1_000_000_000).acquire()?;
/// assert!(lease.net().bandwidth() >= 1_000_000_000);
/// # Ok::<(), grafos_std::FabricError>(())
/// ```
pub struct NetBuilder {
    min_bandwidth: u64,
    lease_secs: u64,
}

impl NetBuilder {
    /// Create a new builder with no bandwidth constraint.
    pub fn new() -> Self {
        NetBuilder {
            min_bandwidth: 0,
            lease_secs: 300,
        }
    }

    /// Set the minimum bandwidth required in bits per second.
    pub fn min_bandwidth(mut self, bps: u64) -> Self {
        self.min_bandwidth = bps;
        self
    }

    /// Set the lease TTL in seconds.
    pub fn lease_secs(mut self, secs: u64) -> Self {
        self.lease_secs = secs.max(1);
        self
    }

    /// Acquire a network lease.
    ///
    /// Calls the host `net_hello` function with the requested minimum
    /// bandwidth. The host allocates a NIC (macvlan or SR-IOV VF) and
    /// returns the interface name and actual bandwidth.
    ///
    /// # Errors
    ///
    /// Returns [`FabricError::CapacityExceeded`] if the host cannot
    /// satisfy the bandwidth requirement, or [`FabricError::Disconnected`]
    /// if the host connection fails.
    pub fn acquire(self) -> Result<NetLease> {
        let state = lease::new_shared_lease(LEASE_TAG_NET, self.lease_secs);
        let (interface_name, actual_bandwidth) = host::net_hello(self.min_bandwidth)?;
        if actual_bandwidth < self.min_bandwidth {
            return Err(FabricError::CapacityExceeded);
        }
        Ok(NetLease {
            state,
            net: FabricNet {
                interface_name,
                bandwidth: actual_bandwidth,
            },
        })
    }
}

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

#[cfg(test)]
mod tests {
    use super::*;
    use crate::error::FabricError;
    use crate::host;

    #[test]
    fn net_acquire_succeeds_with_mock() {
        host::reset_mock();
        host::mock_set_net_interface("eth-fab0", 1_000_000_000);

        let lease = NetBuilder::new()
            .min_bandwidth(1_000_000_000)
            .acquire()
            .expect("acquire");
        assert_eq!(lease.net().interface_name(), "eth-fab0");
        assert_eq!(lease.net().bandwidth(), 1_000_000_000);
    }

    #[test]
    fn net_acquire_rejects_insufficient_bandwidth() {
        host::reset_mock();
        host::mock_set_net_interface("eth-fab0", 100_000_000);

        let result = NetBuilder::new().min_bandwidth(1_000_000_000).acquire();
        assert_eq!(result.unwrap_err(), FabricError::CapacityExceeded);
    }

    #[test]
    fn net_acquire_no_constraint() {
        host::reset_mock();
        host::mock_set_net_interface("eth-fab1", 10_000_000_000);

        let lease = NetBuilder::new().acquire().expect("acquire");
        assert_eq!(lease.net().interface_name(), "eth-fab1");
        assert_eq!(lease.net().bandwidth(), 10_000_000_000);
    }

    #[test]
    fn net_hello_error_propagates() {
        host::reset_mock();
        host::mock_set_net_hello_error(Some(-1));

        let result = NetBuilder::new().acquire();
        assert_eq!(result.unwrap_err(), FabricError::Disconnected);

        host::mock_set_net_hello_error(None);
    }

    #[test]
    fn net_builder_default() {
        let builder = NetBuilder::default();
        assert_eq!(builder.min_bandwidth, 0);
    }

    #[test]
    fn net_bandwidth_reported_correctly() {
        host::reset_mock();
        host::mock_set_net_interface("macvlan0", 25_000_000_000);

        let lease = NetBuilder::new()
            .min_bandwidth(10_000_000_000)
            .acquire()
            .expect("acquire");
        assert_eq!(lease.net().bandwidth(), 25_000_000_000);
    }

    #[test]
    fn net_lease_status_and_renew() {
        host::reset_mock();
        host::mock_set_net_interface("eth-fab0", 1_000_000_000);
        host::mock_set_unix_time_secs(3_000);

        let lease = NetBuilder::new().lease_secs(10).acquire().expect("acquire");
        assert_eq!(lease.status(), LeaseStatus::Active);
        assert_eq!(lease.expires_at_unix_secs(), 3_010);
        lease.renew(30).expect("renew");
        assert_eq!(lease.expires_at_unix_secs(), 3_030);
    }
}