Skip to main content

qualia_core_db/net/peer/fabric/
kernel.rs

1//! Bounded fabric kernel. Same admitted inputs produce the same effects.
2
3use super::carrier::{prohibited, PathClass};
4use super::contact::ContactDescriptor;
5use super::intent::ConnectionIntent;
6use super::lease::RelayLease;
7
8#[derive(Debug, Clone, Copy, PartialEq, Eq)]
9pub enum FabricError {
10    PolicyDenied,
11    StaleDescriptor,
12    Expired,
13    Capacity,
14    LeaseDead,
15    GrantRevoked,
16    Illegal,
17}
18
19#[derive(Debug, Clone, Copy, PartialEq, Eq)]
20pub enum FabricState {
21    Idle,
22    IntentLive,
23    ContactResolved,
24    LeaseHeld,
25    PathLive,
26    SessionLive,
27    OfflineQueued,
28    Closed,
29}
30
31#[derive(Debug, Clone, Copy, PartialEq, Eq)]
32pub enum KernelEvent {
33    IntentAdmitted,
34    Descriptor {
35        stale: bool,
36        expired: bool,
37        direct_locator: bool,
38    },
39    LeaseLive,
40    LeaseExpired,
41    PathValidated {
42        class: PathClass,
43    },
44    NetworkGenerationChanged,
45    GrantRevoked,
46    SessionAuthenticated,
47    Deadline,
48}
49
50#[derive(Debug, Clone, Copy, PartialEq, Eq)]
51pub enum KernelEffect {
52    None,
53    Probe { class: PathClass },
54    Exclude { class: PathClass },
55    QueueOffline,
56    AdmitSession,
57    Close,
58    Deny,
59}
60
61#[derive(Debug, Clone, Copy, PartialEq, Eq)]
62pub struct Kernel {
63    pub state: FabricState,
64    pub generation: u32,
65    pub last_contact_generation: u32,
66    pub grant_live: bool,
67    pub grant_generation: u32,
68    pub direct_probe_count: u32,
69    pub selected: Option<PathClass>,
70    intent: Option<ConnectionIntent>,
71    lease_live: bool,
72}
73
74impl Kernel {
75    /// Creates a default `Kernel`.
76    pub const fn new() -> Self {
77        Self {
78            state: FabricState::Idle,
79            generation: 1,
80            last_contact_generation: 0,
81            grant_live: true,
82            grant_generation: 1,
83            direct_probe_count: 0,
84            selected: None,
85            intent: None,
86            lease_live: false,
87        }
88    }
89
90    /// `Kernel::intent`.
91    pub const fn intent(&self) -> Option<ConnectionIntent> {
92        self.intent
93    }
94
95    /// Admits a connection intent; `FabricError` on policy/capacity failure.
96    pub fn admit(&mut self, intent: ConnectionIntent, now_ms: u64) -> Result<(), FabricError> {
97        if self.state != FabricState::Idle && self.state != FabricState::Closed {
98            return Err(FabricError::Illegal);
99        }
100        if intent.expired(now_ms) {
101            return Err(FabricError::Expired);
102        }
103        self.intent = Some(intent);
104        self.state = FabricState::IntentLive;
105        self.grant_live = true;
106        Ok(())
107    }
108
109    /// Records a learned contact descriptor.
110    pub fn note_contact(&mut self, d: &ContactDescriptor) {
111        if d.generation > self.last_contact_generation {
112            self.last_contact_generation = d.generation;
113        }
114    }
115
116    /// Advances the state machine on `event`, returning its effect.
117    pub fn step(&mut self, event: KernelEvent, now_ms: u64) -> KernelEffect {
118        let Some(intent) = self.intent else {
119            return KernelEffect::Deny;
120        };
121        if intent.expired(now_ms) {
122            self.state = FabricState::OfflineQueued;
123            return KernelEffect::QueueOffline;
124        }
125        let disclosure = intent.protection.disclosure;
126        match event {
127            KernelEvent::IntentAdmitted => {
128                if self.state == FabricState::IntentLive {
129                    KernelEffect::None
130                } else {
131                    KernelEffect::Deny
132                }
133            }
134            KernelEvent::Descriptor {
135                stale,
136                expired,
137                direct_locator,
138            } => {
139                if stale || expired {
140                    self.state = FabricState::OfflineQueued;
141                    return KernelEffect::Deny;
142                }
143                if direct_locator && prohibited(disclosure, PathClass::DirectV6) {
144                    return KernelEffect::Exclude {
145                        class: PathClass::DirectV6,
146                    };
147                }
148                self.state = FabricState::ContactResolved;
149                if direct_locator && !prohibited(disclosure, PathClass::DirectV6) {
150                    KernelEffect::Probe {
151                        class: PathClass::DirectV6,
152                    }
153                } else if prohibited(disclosure, PathClass::Relayed) {
154                    self.state = FabricState::OfflineQueued;
155                    KernelEffect::QueueOffline
156                } else {
157                    KernelEffect::Probe {
158                        class: PathClass::Relayed,
159                    }
160                }
161            }
162            KernelEvent::LeaseLive => {
163                self.lease_live = true;
164                self.state = FabricState::LeaseHeld;
165                KernelEffect::None
166            }
167            KernelEvent::LeaseExpired => {
168                self.lease_live = false;
169                self.selected = None;
170                self.state = FabricState::OfflineQueued;
171                KernelEffect::QueueOffline
172            }
173            KernelEvent::PathValidated { class } => {
174                if prohibited(disclosure, class) {
175                    return KernelEffect::Exclude { class };
176                }
177                if class.discloses_peer_ip() {
178                    self.direct_probe_count = self.direct_probe_count.saturating_add(1);
179                }
180                self.selected = Some(class);
181                self.state = FabricState::PathLive;
182                KernelEffect::None
183            }
184            KernelEvent::NetworkGenerationChanged => {
185                self.generation = self.generation.wrapping_add(1);
186                if self.generation == 0 {
187                    self.generation = 1;
188                }
189                self.selected = None;
190                if prohibited(disclosure, PathClass::DirectV6) {
191                    if self.lease_live {
192                        self.state = FabricState::LeaseHeld;
193                        KernelEffect::Probe {
194                            class: PathClass::Relayed,
195                        }
196                    } else if prohibited(disclosure, PathClass::Relayed) {
197                        self.state = FabricState::OfflineQueued;
198                        KernelEffect::QueueOffline
199                    } else {
200                        KernelEffect::Probe {
201                            class: PathClass::Relayed,
202                        }
203                    }
204                } else {
205                    KernelEffect::Probe {
206                        class: PathClass::DirectV6,
207                    }
208                }
209            }
210            KernelEvent::GrantRevoked => {
211                self.grant_live = false;
212                self.state = FabricState::Closed;
213                KernelEffect::Deny
214            }
215            KernelEvent::SessionAuthenticated => {
216                if self.state != FabricState::PathLive || !self.grant_live {
217                    return KernelEffect::Deny;
218                }
219                self.state = FabricState::SessionLive;
220                KernelEffect::AdmitSession
221            }
222            KernelEvent::Deadline => {
223                self.state = FabricState::OfflineQueued;
224                KernelEffect::QueueOffline
225            }
226        }
227    }
228
229    /// `true` when `lease` is within its window at `now_ms`.
230    pub fn lease_still_usable(&self, lease: &RelayLease, now_ms: u64) -> bool {
231        self.lease_live && lease.live(now_ms)
232    }
233}
234
235#[cfg(test)]
236mod tests {
237    use super::*;
238    use crate::net::peer::fabric::intent::{ProtectionPolicy, Purpose};
239    use crate::net::peer::runtime::ResourceBudget;
240
241    fn intent(p: ProtectionPolicy) -> ConnectionIntent {
242        ConnectionIntent::new(
243            [1u8; 32],
244            Purpose::ordinary(),
245            p,
246            ResourceBudget {
247                bytes: 4096,
248                work: 8,
249                io: 8,
250            },
251            0,
252            10_000,
253        )
254    }
255
256    #[test]
257    fn stale_descriptor_denies_without_direct_probe() {
258        let mut k = Kernel::new();
259        k.admit(intent(ProtectionPolicy::RELAY_ONLY), 0).unwrap();
260        k.last_contact_generation = 5;
261        let e = k.step(
262            KernelEvent::Descriptor {
263                stale: true,
264                expired: false,
265                direct_locator: true,
266            },
267            1,
268        );
269        assert_eq!(e, KernelEffect::Deny);
270        assert_eq!(k.direct_probe_count, 0);
271    }
272
273    #[test]
274    fn relay_only_excludes_validated_direct() {
275        let mut k = Kernel::new();
276        k.admit(intent(ProtectionPolicy::RELAY_ONLY), 0).unwrap();
277        k.step(
278            KernelEvent::Descriptor {
279                stale: false,
280                expired: false,
281                direct_locator: false,
282            },
283            1,
284        );
285        k.step(KernelEvent::LeaseLive, 1);
286        let e = k.step(
287            KernelEvent::PathValidated {
288                class: PathClass::DirectV6,
289            },
290            2,
291        );
292        assert_eq!(
293            e,
294            KernelEffect::Exclude {
295                class: PathClass::DirectV6
296            }
297        );
298        assert_eq!(k.direct_probe_count, 0);
299        assert_ne!(k.state, FabricState::PathLive);
300    }
301
302    #[test]
303    fn ordinary_direct_descriptor_probes_direct() {
304        let mut k = Kernel::new();
305        k.admit(intent(ProtectionPolicy::ORDINARY), 0).unwrap();
306        let e = k.step(
307            KernelEvent::Descriptor {
308                stale: false,
309                expired: false,
310                direct_locator: true,
311            },
312            1,
313        );
314        assert_eq!(
315            e,
316            KernelEffect::Probe {
317                class: PathClass::DirectV6
318            }
319        );
320        let switch = k.step(KernelEvent::NetworkGenerationChanged, 2);
321        assert_eq!(
322            switch,
323            KernelEffect::Probe {
324                class: PathClass::DirectV6
325            }
326        );
327    }
328
329    #[test]
330    fn mailbox_descriptor_still_probes_relayed() {
331        let mut k = Kernel::new();
332        k.admit(intent(ProtectionPolicy::ORDINARY), 0).unwrap();
333        let e = k.step(
334            KernelEvent::Descriptor {
335                stale: false,
336                expired: false,
337                direct_locator: false,
338            },
339            1,
340        );
341        assert_eq!(
342            e,
343            KernelEffect::Probe {
344                class: PathClass::Relayed
345            }
346        );
347    }
348}