Skip to main content

qualia_core_db/net/qdnf/bearer/
lifecycle.rs

1//! Bearer phase machine: init, MTU, drain, shutdown.
2//!
3//! `Failed` is terminal. A retry after `fail_init` requires a new
4//! `BearerLifecycle`. This struct does not own a `LeaseTable`.
5
6use crate::net::qdnf::errors::QdnfError;
7
8use super::contract::Bearer;
9use super::raw_ethernet::RawEthernet;
10
11#[repr(u8)]
12#[derive(Clone, Copy, Debug, PartialEq, Eq)]
13pub enum BearerPhase {
14    Uninitialized = 0,
15    Initializing = 1,
16    Ready = 2,
17    Draining = 3,
18    Closed = 4,
19    Failed = 5,
20}
21
22#[derive(Clone, Copy, Debug, PartialEq, Eq)]
23pub struct BearerLifecycle {
24    phase: BearerPhase,
25    mtu: u16,
26}
27
28impl BearerLifecycle {
29    /// Creates a default `BearerLifecycle`.
30    pub const fn new(mtu: u16) -> Self {
31        Self {
32            phase: BearerPhase::Uninitialized,
33            mtu,
34        }
35    }
36
37    /// Uninitialized → Initializing. Ready/Draining are Conflict.
38    /// Failed is terminal (Conflict). Closed stays Closed.
39    pub fn begin_init(&mut self) -> Result<(), QdnfError> {
40        match self.phase {
41            BearerPhase::Uninitialized => {
42                self.phase = BearerPhase::Initializing;
43                Ok(())
44            }
45            BearerPhase::Closed => Err(QdnfError::Closed),
46            BearerPhase::Failed
47            | BearerPhase::Initializing
48            | BearerPhase::Ready
49            | BearerPhase::Draining => Err(QdnfError::Conflict),
50        }
51    }
52
53    /// Initializing → Ready. Failed stays Failed.
54    pub fn finish_init(&mut self) -> Result<(), QdnfError> {
55        match self.phase {
56            BearerPhase::Initializing => {
57                self.phase = BearerPhase::Ready;
58                Ok(())
59            }
60            BearerPhase::Failed => Err(QdnfError::Conflict),
61            BearerPhase::Closed => Err(QdnfError::Closed),
62            BearerPhase::Uninitialized | BearerPhase::Ready | BearerPhase::Draining => {
63                Err(QdnfError::Conflict)
64            }
65        }
66    }
67
68    /// Initializing → Failed. Ready must use `shutdown`, not `fail_init`.
69    pub fn fail_init(&mut self) -> Result<(), QdnfError> {
70        match self.phase {
71            BearerPhase::Initializing => {
72                self.phase = BearerPhase::Failed;
73                Ok(())
74            }
75            BearerPhase::Closed => Err(QdnfError::Closed),
76            BearerPhase::Uninitialized
77            | BearerPhase::Ready
78            | BearerPhase::Draining
79            | BearerPhase::Failed => Err(QdnfError::Conflict),
80        }
81    }
82
83    /// Ready only. `mtu == 0` is Malformed. Decrease (degradation) is allowed.
84    pub fn set_mtu(&mut self, mtu: u16) -> Result<u16, QdnfError> {
85        match self.phase {
86            BearerPhase::Ready => {
87                if mtu == 0 {
88                    return Err(QdnfError::Malformed);
89                }
90                self.mtu = mtu;
91                Ok(mtu)
92            }
93            BearerPhase::Closed => Err(QdnfError::Closed),
94            _ => Err(QdnfError::Conflict),
95        }
96    }
97
98    /// Ready → Draining. Send wrappers must fail Closed after this.
99    pub fn begin_drain(&mut self) -> Result<(), QdnfError> {
100        match self.phase {
101            BearerPhase::Ready => {
102                self.phase = BearerPhase::Draining;
103                Ok(())
104            }
105            BearerPhase::Closed => Err(QdnfError::Closed),
106            _ => Err(QdnfError::Conflict),
107        }
108    }
109
110    /// Any non-Closed → Closed. Idempotent from Closed.
111    pub fn shutdown(&mut self) -> Result<(), QdnfError> {
112        self.phase = BearerPhase::Closed;
113        Ok(())
114    }
115
116    #[inline]
117    /// Phase.
118    pub const fn phase(&self) -> BearerPhase {
119        self.phase
120    }
121
122    #[inline]
123    /// `BearerLifecycle::mtu`.
124    pub const fn mtu(&self) -> u16 {
125        self.mtu
126    }
127
128    /// Probe raw Ethernet. `PlatformUnsupported` is an explicit failed init:
129    /// `RawEthernet::open` never retains a handle, so nothing leaks.
130    pub fn bind_raw_ethernet(&mut self, interface: &[u8]) -> Result<(), QdnfError> {
131        self.begin_init()?;
132        match RawEthernet::open(interface) {
133            Ok(mut adapter) => {
134                let _ = adapter.shutdown();
135                let _ = self.fail_init();
136                Err(QdnfError::Unsupported)
137            }
138            Err(e) => {
139                let _ = self.fail_init();
140                Err(e)
141            }
142        }
143    }
144}
145
146#[cfg(test)]
147mod tests {
148    use super::*;
149
150    fn ready(mtu: u16) -> BearerLifecycle {
151        let mut lc = BearerLifecycle::new(mtu);
152        lc.begin_init().unwrap();
153        lc.finish_init().unwrap();
154        lc
155    }
156
157    #[test]
158    fn init_happy_path_is_ready() {
159        let lc = ready(1280);
160        assert_eq!(lc.phase(), BearerPhase::Ready);
161        assert_eq!(lc.mtu(), 1280);
162    }
163
164    #[test]
165    fn fail_init_is_terminal() {
166        let mut lc = BearerLifecycle::new(1280);
167        lc.begin_init().unwrap();
168        lc.fail_init().unwrap();
169        assert_eq!(lc.phase(), BearerPhase::Failed);
170        assert_eq!(lc.begin_init(), Err(QdnfError::Conflict));
171        assert_eq!(lc.finish_init(), Err(QdnfError::Conflict));
172        assert_eq!(lc.phase(), BearerPhase::Failed);
173    }
174
175    #[test]
176    fn fail_init_from_ready_is_conflict() {
177        let mut lc = ready(1280);
178        assert_eq!(lc.fail_init(), Err(QdnfError::Conflict));
179        assert_eq!(lc.phase(), BearerPhase::Ready);
180    }
181
182    #[test]
183    fn set_mtu_rules() {
184        let mut uninit = BearerLifecycle::new(1280);
185        assert_eq!(uninit.set_mtu(512), Err(QdnfError::Conflict));
186
187        let mut lc = ready(1280);
188        assert_eq!(lc.set_mtu(0), Err(QdnfError::Malformed));
189        assert_eq!(lc.mtu(), 1280);
190        assert_eq!(lc.set_mtu(512).unwrap(), 512);
191        assert_eq!(lc.mtu(), 512);
192    }
193
194    #[test]
195    fn shutdown_is_idempotent() {
196        let mut lc = ready(1280);
197        lc.shutdown().unwrap();
198        assert_eq!(lc.phase(), BearerPhase::Closed);
199        lc.shutdown().unwrap();
200        assert_eq!(lc.phase(), BearerPhase::Closed);
201        assert_eq!(lc.begin_init(), Err(QdnfError::Closed));
202    }
203
204    #[test]
205    fn drain_from_ready() {
206        let mut lc = ready(1280);
207        lc.begin_drain().unwrap();
208        assert_eq!(lc.phase(), BearerPhase::Draining);
209        assert_eq!(lc.begin_drain(), Err(QdnfError::Conflict));
210        lc.shutdown().unwrap();
211        assert_eq!(lc.phase(), BearerPhase::Closed);
212    }
213
214    #[test]
215    fn raw_ethernet_open_fails_init_without_resource() {
216        let mut lc = BearerLifecycle::new(1500);
217        assert_eq!(
218            lc.bind_raw_ethernet(b"eth0"),
219            Err(QdnfError::PlatformUnsupported)
220        );
221        assert_eq!(lc.phase(), BearerPhase::Failed);
222        assert_eq!(lc.begin_init(), Err(QdnfError::Conflict));
223    }
224}