batman-robin 1.2.1

Rust library and CLI tool for interacting with the BATMAN-adv kernel module for mesh networking
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

use macaddr::MacAddr;
use std::time::SystemTime;

/// Gateway change event emitted by batman-adv kernel module.
///
/// When a batman-adv node is in gateway client mode, it emits uevents
/// when the selected gateway changes. Applications can subscribe to these
/// events to perform actions like starting/renewing DHCP leases.
///
/// # Examples
///
/// ```ignore
/// let client = batman_robin::Client::new();
/// let mut events = client
///     .subscribe_gateway_events(batman_robin::MeshSelector::with_name("bat0"))
///     .await?;
///
/// while let Some(event) = events.next().await {
///     match event?.action {
///         GatewayEventAction::Add => println!("Gateway selected: {:?}", event?.gateway_mac),
///         GatewayEventAction::Change => println!("Better gateway found"),
///         GatewayEventAction::Delete => println!("Gateway lost"),
///     }
/// }
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GatewayEvent {
    /// Timestamp when the event was received
    pub timestamp: SystemTime,

    /// Mesh interface index (e.g. from `if_nametoindex("bat0")`)
    pub meshif: u32,

    /// Mesh interface name (e.g. "bat0")
    pub meshif_name: String,

    /// Type of gateway change event
    pub action: GatewayEventAction,

    /// MAC address of the selected gateway (present for ADD/CHANGE, absent for DELETE)
    pub gateway_mac: Option<MacAddr>,
}

/// Gateway event action types
///
/// These correspond to batman-adv's BATACTION uevent field.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u8)]
pub enum GatewayEventAction {
    /// First gateway was selected (ADD)
    ///
    /// This event is sent when a batman-adv node transitions to having a selected
    /// gateway. Applications should typically start a DHCP client on this event.
    Add = 1,

    /// A better gateway was found (CHANGE)
    ///
    /// This event is sent when a batman-adv node switches to a different gateway
    /// due to improved link quality or other selection criteria.
    /// Applications should typically renew their DHCP lease on this event.
    Change = 2,

    /// The selected gateway is no longer available (DEL)
    ///
    /// This event is sent when the currently selected gateway disappears
    /// and no alternative gateway is available. The `gateway_mac` field
    /// will be `None` for this action.
    Delete = 3,
}

impl GatewayEvent {
    /// Create a new gateway event
    pub fn new(
        meshif: u32,
        meshif_name: String,
        action: GatewayEventAction,
        gateway_mac: Option<MacAddr>,
    ) -> Self {
        Self {
            timestamp: SystemTime::now(),
            meshif,
            meshif_name,
            action,
            gateway_mac,
        }
    }

    /// Check if this event has a valid associated gateway MAC
    pub fn has_gateway(&self) -> bool {
        self.gateway_mac.is_some()
    }
}

impl std::fmt::Display for GatewayEventAction {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Add => write!(f, "ADD"),
            Self::Change => write!(f, "CHANGE"),
            Self::Delete => write!(f, "DELETE"),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_gateway_event_creation() {
        let mac = "60:09:c3:aa:bb:cc".parse().unwrap();
        let event = GatewayEvent::new(6, "bat0".to_string(), GatewayEventAction::Add, Some(mac));

        assert_eq!(event.meshif, 6);
        assert_eq!(event.meshif_name, "bat0");
        assert_eq!(event.action, GatewayEventAction::Add);
        assert_eq!(event.gateway_mac, Some(mac));
        assert!(event.has_gateway());
    }

    #[test]
    fn test_delete_event_no_gateway() {
        let event = GatewayEvent::new(6, "bat0".to_string(), GatewayEventAction::Delete, None);

        assert_eq!(event.action, GatewayEventAction::Delete);
        assert!(!event.has_gateway());
    }

    #[test]
    fn test_action_display() {
        assert_eq!(GatewayEventAction::Add.to_string(), "ADD");
        assert_eq!(GatewayEventAction::Change.to_string(), "CHANGE");
        assert_eq!(GatewayEventAction::Delete.to_string(), "DELETE");
    }
}