Skip to main content

qualia_core_db/net/qdnf/route/
constraints.rs

1//! E08.3/E08.4 — hard filters before ranking. Unknown energy is not zero.
2
3use crate::net::qdnf::errors::QdnfError;
4
5use super::select::PathMetrics;
6use super::validate::ValidatedEdge;
7
8/// Hard path constraints. Feasibility never trades for a cheaper advertisement.
9#[repr(C)]
10#[derive(Clone, Copy, Debug, PartialEq, Eq)]
11pub struct PathConstraint {
12    /// Bitmask of permitted realm ids 0..63. Zero means none permitted → Denied.
13    pub permitted_realms: u64,
14    /// 0=P0 .. 3=P3. Path/edge profile below this is Denied.
15    pub min_profile: u8,
16    /// Path/edge cost cap. `u16::MAX` means unlimited.
17    pub max_cost: u16,
18    /// Additive latency cap in milliseconds. `0` means no deadline.
19    pub deadline_ms: u32,
20    pub require_loop_free: bool,
21    /// Energy cap in microjoules. `0` means no energy bound is required.
22    pub max_energy_uj: u32,
23}
24
25impl PathConstraint {
26    pub const UNRESTRICTED: Self = Self {
27        permitted_realms: u64::MAX,
28        min_profile: 0,
29        max_cost: u16::MAX,
30        deadline_ms: 0,
31        require_loop_free: true,
32        max_energy_uj: 0,
33    };
34}
35
36/// Hard filter for a single admitted edge. Runs before any ranking.
37pub fn edge_feasible(edge: &ValidatedEdge, c: &PathConstraint) -> Result<(), QdnfError> {
38    if edge.withdrawn {
39        return Err(QdnfError::Revoked);
40    }
41    if c.permitted_realms == 0 {
42        return Err(QdnfError::Denied);
43    }
44    if edge.realm_bit >= 64 {
45        return Err(QdnfError::Range);
46    }
47    let bit = 1u64 << edge.realm_bit;
48    if c.permitted_realms & bit == 0 {
49        return Err(QdnfError::Denied);
50    }
51    if edge.profile < c.min_profile {
52        return Err(QdnfError::Denied);
53    }
54    if c.max_cost != u16::MAX && edge.cost > c.max_cost {
55        return Err(QdnfError::Denied);
56    }
57    if c.deadline_ms != 0 && edge.latency_ms > c.deadline_ms {
58        return Err(QdnfError::Denied);
59    }
60    if c.max_energy_uj != 0 {
61        if !edge.energy_known {
62            return Err(QdnfError::Incomplete);
63        }
64        if edge.energy_uj > c.max_energy_uj {
65            return Err(QdnfError::Denied);
66        }
67    }
68    Ok(())
69}
70
71/// Path-level deadline/budget check. Latency here is an additive bound, not p95.
72pub fn path_feasible(metrics: &PathMetrics, c: &PathConstraint) -> Result<(), QdnfError> {
73    if c.permitted_realms == 0 {
74        return Err(QdnfError::Denied);
75    }
76    if c.max_cost != u16::MAX && metrics.cost > c.max_cost {
77        return Err(QdnfError::Denied);
78    }
79    if c.deadline_ms != 0 && metrics.latency_ms > c.deadline_ms {
80        return Err(QdnfError::Denied);
81    }
82    if c.max_energy_uj != 0 {
83        if !metrics.energy_known {
84            return Err(QdnfError::Incomplete);
85        }
86        if metrics.energy_uj > c.max_energy_uj {
87            return Err(QdnfError::Denied);
88        }
89    }
90    Ok(())
91}
92
93#[cfg(test)]
94mod tests {
95    use super::*;
96    use crate::net::qdnf::route::index::AdjacencyIndex;
97    use crate::net::qdnf::route::plan::plan_routes;
98    use crate::net::qdnf::route::select::CandidatePath;
99    use crate::net::qdnf::route::validate::{insert, TopologyRecord, PROFILE_P0};
100    use crate::net::qdnf::types::StrongDigest;
101
102    fn rec(
103        origin: u8,
104        from: u8,
105        to: u8,
106        seq: u32,
107        cost: u16,
108        realm: u8,
109        profile: u8,
110    ) -> TopologyRecord {
111        TopologyRecord {
112            origin,
113            origin_digest: {
114                let mut d = StrongDigest::ZERO;
115                d.0[0] = origin;
116                d.0[47] = 1;
117                d
118            },
119            scope: 1,
120            from,
121            to,
122            sequence: seq,
123            expiry_unix: 100,
124            withdrawn: false,
125            bidirectional: true,
126            cost,
127            latency_ms: 1,
128            energy_uj: 1,
129            energy_known: true,
130            realm_bit: realm,
131            profile,
132            failure_domain: from,
133            digest: StrongDigest::ZERO,
134        }
135    }
136
137    fn edge_from(r: TopologyRecord) -> ValidatedEdge {
138        ValidatedEdge {
139            origin: r.origin,
140            from: r.from,
141            to: r.to,
142            sequence: r.sequence,
143            expiry_unix: r.expiry_unix,
144            withdrawn: r.withdrawn,
145            bidirectional: r.bidirectional,
146            cost: r.cost,
147            latency_ms: r.latency_ms,
148            energy_uj: r.energy_uj,
149            energy_known: r.energy_known,
150            realm_bit: r.realm_bit,
151            profile: r.profile,
152            failure_domain: r.failure_domain,
153            scope: r.scope,
154        }
155    }
156
157    #[test]
158    fn route_c_cheapest_forbidden_realm_not_selected() {
159        let mut index = AdjacencyIndex::new(1);
160        insert(&rec(1, 1, 2, 1, 1, 1, PROFILE_P0), 1, 1, None, &mut index).unwrap();
161        insert(&rec(1, 1, 3, 2, 50, 0, PROFILE_P0), 1, 1, None, &mut index).unwrap();
162        insert(&rec(3, 3, 2, 1, 50, 0, PROFILE_P0), 1, 1, None, &mut index).unwrap();
163        let c = PathConstraint {
164            permitted_realms: 1u64 << 0,
165            min_profile: PROFILE_P0,
166            max_cost: u16::MAX,
167            deadline_ms: 0,
168            require_loop_free: true,
169            max_energy_uj: 0,
170        };
171        let mut out = [CandidatePath::EMPTY; 3];
172        let n = plan_routes(&index, 1, 2, &c, 1, &mut out).unwrap();
173        assert_eq!(n, 1);
174        assert_eq!(out[0].first_hop, 3);
175        assert_eq!(out[0].metrics.cost, 100);
176    }
177
178    #[test]
179    fn route_c_cheapest_forbidden_profile_not_selected() {
180        let mut index = AdjacencyIndex::new(1);
181        insert(&rec(1, 1, 2, 1, 1, 0, 0), 1, 1, None, &mut index).unwrap();
182        insert(&rec(1, 1, 3, 2, 9, 0, 2), 1, 1, None, &mut index).unwrap();
183        insert(&rec(3, 3, 2, 1, 9, 0, 2), 1, 1, None, &mut index).unwrap();
184        let c = PathConstraint {
185            permitted_realms: u64::MAX,
186            min_profile: 2,
187            max_cost: u16::MAX,
188            deadline_ms: 0,
189            require_loop_free: true,
190            max_energy_uj: 0,
191        };
192        let mut out = [CandidatePath::EMPTY; 3];
193        let n = plan_routes(&index, 1, 2, &c, 1, &mut out).unwrap();
194        assert_eq!(n, 1);
195        assert_eq!(out[0].first_hop, 3);
196        assert!(edge_feasible(&edge_from(rec(1, 1, 2, 1, 1, 0, 0)), &c).is_err());
197    }
198
199    #[test]
200    fn unknown_energy_with_required_bound_is_infeasible() {
201        let mut e = edge_from(rec(1, 1, 2, 1, 1, 0, 0));
202        e.energy_known = false;
203        e.energy_uj = 0;
204        let c = PathConstraint {
205            permitted_realms: u64::MAX,
206            min_profile: 0,
207            max_cost: u16::MAX,
208            deadline_ms: 0,
209            require_loop_free: true,
210            max_energy_uj: 10,
211        };
212        assert_eq!(edge_feasible(&e, &c), Err(QdnfError::Incomplete));
213        e.energy_known = true;
214        e.energy_uj = 0;
215        assert!(edge_feasible(&e, &c).is_ok());
216    }
217
218    #[test]
219    fn malicious_zero_cost_still_fails_if_realm_forbidden() {
220        let mut index = AdjacencyIndex::new(1);
221        insert(&rec(1, 1, 2, 1, 0, 5, PROFILE_P0), 1, 1, None, &mut index).unwrap();
222        insert(&rec(1, 1, 3, 2, 40, 0, PROFILE_P0), 1, 1, None, &mut index).unwrap();
223        insert(&rec(3, 3, 2, 1, 40, 0, PROFILE_P0), 1, 1, None, &mut index).unwrap();
224        let c = PathConstraint {
225            permitted_realms: 1u64 << 0,
226            min_profile: PROFILE_P0,
227            max_cost: u16::MAX,
228            deadline_ms: 0,
229            require_loop_free: true,
230            max_energy_uj: 0,
231        };
232        let cheap = edge_from(rec(1, 1, 2, 1, 0, 5, PROFILE_P0));
233        assert_eq!(edge_feasible(&cheap, &c), Err(QdnfError::Denied));
234        let mut out = [CandidatePath::EMPTY; 3];
235        let n = plan_routes(&index, 1, 2, &c, 1, &mut out).unwrap();
236        assert_eq!(n, 1);
237        assert_eq!(out[0].first_hop, 3);
238        assert_ne!(out[0].metrics.cost, 0);
239    }
240
241    #[test]
242    fn zero_permitted_realms_is_denied() {
243        let e = edge_from(rec(1, 1, 2, 1, 1, 0, 0));
244        let mut c = PathConstraint::UNRESTRICTED;
245        c.permitted_realms = 0;
246        assert_eq!(edge_feasible(&e, &c), Err(QdnfError::Denied));
247    }
248}