filament-interfaces · interface

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct InterfaceId(u64);

pub fn new() -> Self;

pub fn as_u64(&self) -> u64;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum InterfaceMode {
    /// Full meshing and transport functionality
    Full,
    /// Gateway with path discovery for downstream nodes
    Gateway,
    /// Access point mode (quiet, short-lived paths)
    AccessPoint,
    /// Roaming mode for mobile interfaces
    Roaming,
    /// Boundary mode for network segment transitions
    Boundary,
}

#[derive(Debug, Clone, Default)]
pub struct InterfaceStats {
/// Total packets sent

pub packets_sent: u64,
/// Total packets received

pub packets_received: u64,
/// Total bytes sent

pub bytes_sent: u64,
/// Total bytes received

pub bytes_received: u64,
/// Number of send errors

pub send_errors: u64,
/// Number of receive errors

pub recv_errors: u64,
/// Last send timestamp (unix millis)

pub last_send: Option<u64>,
/// Last receive timestamp (unix millis)

pub last_recv: Option<u64>
}

pub fn record_send(&mut self, bytes: usize);

pub fn record_recv(&mut self, bytes: usize);

pub fn record_send_error(&mut self);

pub fn record_recv_error(&mut self);

#[derive(Error, Debug)]
pub enum InterfaceError {
    /// Failed to send packet
    #[error("send failed: {0}")]
    SendFailed(String),

    /// Failed to receive packet
    #[error("receive failed: {0}")]
    ReceiveFailed(String),

    /// Interface is disconnected
    #[error("interface disconnected")]
    Disconnected,

    /// Interface is not enabled
    #[error("interface not enabled")]
    NotEnabled,

    /// Packet exceeds MTU
    #[error("packet size {size} exceeds MTU {mtu}")]
    PacketTooLarge {
        /// Packet size
        size: usize,
        /// Interface MTU
        mtu: usize,
    },

    /// Configuration error
    #[error("configuration error: {0}")]
    Configuration(String),

    /// I/O error
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),

    /// Timeout
    #[error("operation timed out")]
    Timeout,

    /// Authentication failure (IFAC)
    #[error("authentication failed: {0}")]
    AuthenticationFailed(String),

    /// Other error
    #[error("interface error: {0}")]
    Other(String),
}

#[async_trait]
pub trait Interface: Send + Sync {
    /// Get unique interface identifier
    fn id(&self) -> InterfaceId;

    /// Get human-readable interface name
    fn name(&self) -> &str;

    /// Get interface operating mode
    fn mode(&self) -> InterfaceMode;

    /// Get interface bitrate in bits per second
    ///
    /// Returns the nominal bitrate of the interface. For variable-rate interfaces,
    /// this should return a conservative estimate.
    fn bitrate(&self) -> u64;

    /// Get maximum transmission unit (MTU) in bytes
    ///
    /// Filament requires a minimum MTU of 500 bytes.
    fn mtu(&self) -> usize ;

    /// Transmit a packet on the interface
    ///
    /// # Errors
    ///
    /// - [`InterfaceError::PacketTooLarge`] if packet exceeds MTU
    /// - [`InterfaceError::SendFailed`] if transmission fails
    /// - [`InterfaceError::NotEnabled`] if interface is disabled
    async fn send(&mut self, packet: &[u8]) -> Result<(), InterfaceError>;

    /// Receive a packet from the interface
    ///
    /// This method should block until a packet is available. For non-blocking
    /// behavior, wrap calls in `tokio::select!` or similar.
    ///
    /// # Errors
    ///
    /// - [`InterfaceError::ReceiveFailed`] if reception fails
    /// - [`InterfaceError::Disconnected`] if interface is disconnected
    /// - [`InterfaceError::NotEnabled`] if interface is disabled
    async fn recv(&mut self) -> Result<Vec<u8>, InterfaceError>;

    /// Enable or disable the interface
    ///
    /// When disabled, send and receive operations should return errors.
    async fn set_enabled(&mut self, enabled: bool) -> Result<(), InterfaceError>;

    /// Check if interface is currently online and ready
    fn is_online(&self) -> bool;

    /// Get interface statistics
    fn stats(&self) -> InterfaceStats ;

    /// Get interface description (optional)
    fn description(&self) -> Option<&str> ;
}

pub type SharedInterface = Arc<tokio::sync::Mutex<Box<dyn Interface>>>;