Skip to main content

qualia_core_db/net/peer/fabric/
contact.rs

1//! Private contact descriptor. Discovery, not traversal, and not concealment.
2
3use super::intent::PeerId;
4
5#[repr(u8)]
6#[derive(Debug, Clone, Copy, PartialEq, Eq)]
7pub enum LocatorKind {
8    /// Relationship-scoped mailbox. No access-network IP.
9    Mailbox = 1,
10    /// Approved relay hint. Not a peer IP.
11    RelayHint = 2,
12    /// Direct locator. Only usable when disclosure permits probing.
13    Direct = 3,
14}
15
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub struct ContactDescriptor {
18    pub contact_key: PeerId,
19    pub generation: u32,
20    pub expiry_unix: u32,
21    pub network_generation: u32,
22    pub kind: LocatorKind,
23    pub locator: [u8; 16],
24}
25
26impl ContactDescriptor {
27    /// `ContactDescriptor::mailbox`.
28    pub const fn mailbox(contact_key: PeerId, generation: u32, expiry_unix: u32) -> Self {
29        Self {
30            contact_key,
31            generation,
32            expiry_unix,
33            network_generation: 1,
34            kind: LocatorKind::Mailbox,
35            locator: [0u8; 16],
36        }
37    }
38
39    /// `true` when `expired`.
40    pub const fn is_expired(&self, now_unix: u32) -> bool {
41        now_unix >= self.expiry_unix
42    }
43
44    /// A valid signature on an older generation is stale, not current.
45    pub const fn is_stale(&self, last_known_generation: u32) -> bool {
46        last_known_generation != 0 && self.generation < last_known_generation
47    }
48
49    /// `true` when direct-locator.
50    pub const fn is_direct_locator(&self) -> bool {
51        matches!(self.kind, LocatorKind::Direct)
52    }
53}
54
55#[cfg(test)]
56mod tests {
57    use super::*;
58
59    #[test]
60    fn older_generation_is_stale() {
61        let d = ContactDescriptor::mailbox([7u8; 32], 3, 2_000_000_000);
62        assert!(d.is_stale(5));
63        assert!(!d.is_stale(3));
64        assert!(!d.is_stale(0));
65        assert!(d.is_expired(2_000_000_000));
66        assert!(!d.is_expired(1_700_000_000));
67    }
68}