Skip to main content

open_net/api/network/
lan_ipv4.rs

1//! Owned LAN inventory and the evidence behind its default recommendation.
2
3use std::net::Ipv4Addr;
4use std::time::SystemTime;
5
6/// Interface role reported by platform metadata. This is not proof of reachability.
7#[non_exhaustive]
8#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
9pub enum LanInterfaceKind {
10    Wifi,
11    Ethernet,
12    Bridge,
13    Tunnel,
14    Virtual,
15    Loopback,
16    #[default]
17    Unknown,
18}
19
20/// Whether the auxiliary platform collectors reported a failure.
21#[non_exhaustive]
22#[derive(Clone, Copy, Debug, PartialEq, Eq)]
23pub enum LanIpv4Completeness {
24    /// Collection completed without a reported failure. Individual optional
25    /// facts can still be unknown; this is not an atomic OS-wide inventory.
26    Complete,
27    /// Interface addresses were obtained, but some platform evidence is missing.
28    /// Inspect diagnostics and optional facts; absence is not proof of removal.
29    Partial,
30}
31
32/// Why the default LAN advertisement policy does not recommend a candidate.
33/// Policy exclusions such as VPN/CGNAT do not mean the address is unusable by
34/// an application that understands its own topology.
35#[non_exhaustive]
36#[derive(Clone, Copy, Debug, PartialEq, Eq)]
37pub enum LanIpv4Exclusion {
38    InterfaceDown,
39    InterfaceStateUnknown,
40    PointToPoint,
41    PointToPointStateUnknown,
42    VirtualInterfaceNameHint,
43    PlatformVirtualOrTunnel,
44    LinkInactive,
45    Loopback,
46    LinkLocal,
47    Unspecified,
48    Broadcast,
49    Multicast,
50    ThisNetwork,
51    Reserved,
52    SharedAddressSpace,
53    BenchmarkRange,
54}
55
56/// The strongest interface evidence supporting the selected candidate.
57/// These variants describe a heuristic, not a successful peer connection.
58#[non_exhaustive]
59#[derive(Clone, Copy, Debug, PartialEq, Eq)]
60pub enum LanIpv4RecommendationReason {
61    ActiveLanDefaultRoute,
62    ActiveWifiOrEthernet,
63    ActiveBridge,
64    LanLinkUnknown,
65    MetadataUnknown,
66    BridgeLinkUnknown,
67}
68
69/// One assigned IPv4 address, including candidates excluded by the default policy.
70/// Multiple entries may belong to the same interface or share an IP address.
71#[derive(Clone, Debug, PartialEq, Eq)]
72pub struct LanIpv4Candidate {
73    pub(crate) interface_id: String,
74    pub(crate) interface_name: String,
75    pub(crate) interface_index: Option<u32>,
76    pub(crate) address: Ipv4Addr,
77    pub(crate) netmask: Ipv4Addr,
78    pub(crate) prefix_len: u8,
79    pub(crate) interface_kind: LanInterfaceKind,
80    pub(crate) oper_up: Option<bool>,
81    pub(crate) point_to_point: Option<bool>,
82    pub(crate) link_active: Option<bool>,
83    pub(crate) default_route: Option<bool>,
84    pub(crate) exclusions: Vec<LanIpv4Exclusion>,
85    pub(crate) recommendation: Option<LanIpv4RecommendationReason>,
86}
87
88impl LanIpv4Candidate {
89    /// Platform interface identity (adapter name on Windows, interface name on
90    /// Unix). Stable for sorting this inventory, not a permanent hardware ID.
91    pub fn interface_id(&self) -> &str {
92        &self.interface_id
93    }
94
95    pub fn interface_name(&self) -> &str {
96        &self.interface_name
97    }
98
99    /// Native interface index, when supplied. It can be reused after removal.
100    pub fn interface_index(&self) -> Option<u32> {
101        self.interface_index
102    }
103
104    pub fn address(&self) -> Ipv4Addr {
105        self.address
106    }
107
108    pub fn netmask(&self) -> Ipv4Addr {
109        self.netmask
110    }
111
112    pub fn prefix_len(&self) -> u8 {
113        self.prefix_len
114    }
115
116    pub fn interface_kind(&self) -> LanInterfaceKind {
117        self.interface_kind
118    }
119
120    /// Operational status from address enumeration. On Unix, Up is derived
121    /// from IFF_RUNNING and does not establish physical carrier or peer access.
122    pub fn is_oper_up(&self) -> Option<bool> {
123        self.oper_up
124    }
125
126    pub fn is_point_to_point(&self) -> Option<bool> {
127        self.point_to_point
128    }
129
130    /// Additional native link/media evidence, independently of operational flags.
131    pub fn link_active(&self) -> Option<bool> {
132        self.link_active
133    }
134
135    /// Preferred IPv4 default-interface evidence from the platform collector.
136    /// None means unknown. This is not a destination-specific route lookup:
137    /// VPN split routes and policy routing can select a different actual path.
138    pub fn is_default_route(&self) -> Option<bool> {
139        self.default_route
140    }
141
142    /// All applicable default-policy exclusions, in a deterministic order.
143    /// An empty slice does not guarantee reachability from any particular peer.
144    pub fn default_exclusions(&self) -> &[LanIpv4Exclusion] {
145        &self.exclusions
146    }
147
148    /// Present only for the one recommended entry in this snapshot.
149    pub fn recommendation_reason(&self) -> Option<LanIpv4RecommendationReason> {
150        self.recommendation
151    }
152
153    pub fn is_recommended(&self) -> bool {
154        self.recommendation.is_some()
155    }
156}
157
158/// A fresh, self-contained IPv4 inventory and its default LAN recommendation.
159/// It owns ordinary data, not an engine, subscription, or native handle.
160#[derive(Clone, Debug)]
161pub struct LanIpv4Snapshot {
162    pub(crate) candidates: Vec<LanIpv4Candidate>,
163    pub(crate) completeness: LanIpv4Completeness,
164    pub(crate) diagnostics: Vec<String>,
165    pub(crate) query_started_at: SystemTime,
166    pub(crate) observed_at: SystemTime,
167}
168
169impl LanIpv4Snapshot {
170    /// All IPv4 entries returned by the address enumerator, including excluded
171    /// entries, sorted by interface identity/address. No IP-only deduplication.
172    /// This does not include every OS address state (for example Windows DAD
173    /// tentative addresses), IPv6, or interfaces without an assigned IPv4.
174    pub fn candidates(&self) -> &[LanIpv4Candidate] {
175        &self.candidates
176    }
177
178    /// At most one entry selected using interface/link/route evidence, with all
179    /// three RFC1918 ranges equally ranked. None is an honest lack of a default
180    /// recommendation, not permission to advertise loopback or an arbitrary IP.
181    /// A Partial snapshot can have a recommendation based on remaining facts.
182    pub fn recommended(&self) -> Option<&LanIpv4Candidate> {
183        self.candidates
184            .iter()
185            .find(|candidate| candidate.is_recommended())
186    }
187
188    pub fn completeness(&self) -> LanIpv4Completeness {
189        self.completeness
190    }
191
192    /// Human-readable collection failures. Do not parse these strings as an API.
193    pub fn diagnostics(&self) -> &[String] {
194        &self.diagnostics
195    }
196
197    /// Wall-clock time before enumeration began. Collection spans a window;
198    /// addresses and metadata are not captured in an OS-wide transaction.
199    pub fn query_started_at(&self) -> SystemTime {
200        self.query_started_at
201    }
202
203    /// Wall-clock time when collection finished. Clock adjustments can make
204    /// this earlier than query_started_at; neither value is a validity lease.
205    pub fn observed_at(&self) -> SystemTime {
206        self.observed_at
207    }
208}