prns-core 0.3.4

Pure Reticulum engine and wire contract for Personal Reticulum
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

mod fixed;
mod growable;

pub use fixed::FixedDiscoveryValidationCache;
pub use growable::{
    GrowableInterfaceDiscoveryStorage, HeapDiscoveredConnectionTable, HeapDiscoveredEndpointSet,
    HeapDiscoveryCatalogTable, HeapDiscoveryValidationCache, RNS_VALIDATION_CACHE_CAPACITY,
};

use crate::interfaces::InterfaceId;
use crate::storage::TablePushError;

use super::{
    ActiveDiscoveredInterface, DiscoveredConnectionEndpointId, DiscoveredInterfaceId,
    DiscoveryRecord, StampValue,
};

/// Lemire-index bucket count that keeps a fixed validation cache at or below 2/3 load.
pub const fn discovery_validation_index_buckets(entries: usize) -> usize {
    crate::lemire_index::buckets_for_two_thirds_load(entries)
}

/// The memoization residence behind discovery stamp validation. Implementations may use
/// growable host storage, fixed inline storage, external memory, or zero capacity; cache misses
/// change only validation work, never acceptance semantics.
pub trait DiscoveryValidationCache: Default {
    fn valid(&self, payload_hash: &[u8; 32]) -> Option<(&[u8], StampValue)>;
    fn insufficient(&self, payload_hash: &[u8; 32]) -> Option<StampValue>;
    fn remember_valid(
        &mut self,
        payload_hash: [u8; 32],
        packed_advertisement: &[u8],
        stamp_value: StampValue,
    );
    fn remember_insufficient(&mut self, payload_hash: [u8; 32], stamp_value: StampValue);
}

pub trait DiscoveryCatalogTable: Default {
    type Records<'a>: Iterator<Item = &'a DiscoveryRecord>
    where
        Self: 'a;

    fn len(&self) -> usize;

    fn is_empty(&self) -> bool {
        self.len() == 0
    }

    fn get(&self, id: DiscoveredInterfaceId) -> Option<&DiscoveryRecord>;
    fn get_mut(&mut self, id: DiscoveredInterfaceId) -> Option<&mut DiscoveryRecord>;
    fn try_insert(
        &mut self,
        id: DiscoveredInterfaceId,
        record: DiscoveryRecord,
    ) -> Result<Option<DiscoveryRecord>, TablePushError>;
    fn remove(&mut self, id: DiscoveredInterfaceId) -> Option<DiscoveryRecord>;
    fn records(&self) -> Self::Records<'_>;
}

pub trait DiscoveredConnectionTable: Default {
    type Connections<'a>: Iterator<Item = &'a ActiveDiscoveredInterface>
    where
        Self: 'a;

    fn len(&self) -> usize;

    fn is_empty(&self) -> bool {
        self.len() == 0
    }

    fn get_mut(&mut self, interface: InterfaceId) -> Option<&mut ActiveDiscoveredInterface>;
    fn contains_interface(&self, interface: InterfaceId) -> bool;
    fn contains_endpoint(&self, endpoint: DiscoveredConnectionEndpointId) -> bool;
    fn try_insert(
        &mut self,
        interface: ActiveDiscoveredInterface,
    ) -> Result<Option<ActiveDiscoveredInterface>, TablePushError>;
    fn remove(&mut self, interface: InterfaceId) -> Option<ActiveDiscoveredInterface>;
    fn connections(&self) -> Self::Connections<'_>;
}

pub trait DiscoveredEndpointSet: Default {
    type Endpoints<'a>: Iterator<Item = DiscoveredConnectionEndpointId>
    where
        Self: 'a;

    fn try_insert(
        &mut self,
        endpoint: DiscoveredConnectionEndpointId,
    ) -> Result<bool, TablePushError>;
    fn endpoints(&self) -> Self::Endpoints<'_>;
}

pub trait InterfaceDiscoveryStorage {
    type ValidationCache: DiscoveryValidationCache;
    type Catalog: DiscoveryCatalogTable;
    type Connections: DiscoveredConnectionTable;
    type ReservedEndpoints: DiscoveredEndpointSet;
}