qualia_core_db/net/peer/fabric/
kernel.rs1use 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 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 pub const fn intent(&self) -> Option<ConnectionIntent> {
92 self.intent
93 }
94
95 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 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 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 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}