Skip to main content

open_net/api/net_status/
ip_stack.rs

1use std::fmt;
2
3/// The IP-stack capability currently available to the host.
4///
5/// This reflects which IP protocol versions the host has usable addresses /
6/// routes for, as reported by the underlying [`netwatch`] interface state
7/// (`have_v4` / `have_v6`). The semantics are identical across platforms: it
8/// describes local stack availability, not per-protocol Internet reachability.
9///
10/// [`netwatch`]: https://crates.io/crates/netwatch
11#[derive(Clone, Copy, Debug, PartialEq, Eq)]
12pub enum IpStack {
13    /// Neither IPv4 nor IPv6 is available.
14    None,
15    /// Only IPv4 is available.
16    V4Only,
17    /// Only IPv6 is available.
18    V6Only,
19    /// Both IPv4 and IPv6 are available.
20    DualStack,
21}
22
23impl IpStack {
24    /// Fold the two protocol-availability flags into a single [`IpStack`].
25    pub(crate) const fn from_flags(have_v4: bool, have_v6: bool) -> Self {
26        match (have_v4, have_v6) {
27            (true, true) => IpStack::DualStack,
28            (true, false) => IpStack::V4Only,
29            (false, true) => IpStack::V6Only,
30            (false, false) => IpStack::None,
31        }
32    }
33
34    /// The variant name as a static string (e.g. `"DualStack"`).
35    ///
36    /// Used both by the [`fmt::Display`] implementation and as a stable,
37    /// human-readable label when forwarding the value to logging.
38    pub const fn name(&self) -> &'static str {
39        match self {
40            IpStack::None => "None",
41            IpStack::V4Only => "V4Only",
42            IpStack::V6Only => "V6Only",
43            IpStack::DualStack => "DualStack",
44        }
45    }
46
47    /// Whether IPv4 is available (true for [`IpStack::V4Only`] and
48    /// [`IpStack::DualStack`]).
49    pub const fn has_ipv4(&self) -> bool {
50        matches!(self, IpStack::V4Only | IpStack::DualStack)
51    }
52
53    /// Whether IPv6 is available (true for [`IpStack::V6Only`] and
54    /// [`IpStack::DualStack`]).
55    pub const fn has_ipv6(&self) -> bool {
56        matches!(self, IpStack::V6Only | IpStack::DualStack)
57    }
58
59    /// Whether both IPv4 and IPv6 are available.
60    pub const fn is_dual_stack(&self) -> bool {
61        matches!(self, IpStack::DualStack)
62    }
63}
64
65impl fmt::Display for IpStack {
66    /// Renders the variant name, so `to_string()` yields e.g. `"DualStack"`
67    /// rather than a structural form.
68    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
69        f.write_str(self.name())
70    }
71}
72
73#[cfg(test)]
74mod tests {
75    use super::IpStack;
76
77    type TestResult = Result<(), Box<dyn std::error::Error + Send + Sync>>;
78
79    fn check(condition: bool, message: &str) -> TestResult {
80        if condition {
81            Ok(())
82        } else {
83            Err(std::io::Error::other(message).into())
84        }
85    }
86
87    #[test]
88    fn from_flags_covers_all_combinations() -> TestResult {
89        for (v4, v6, expected) in [
90            (false, false, IpStack::None),
91            (true, false, IpStack::V4Only),
92            (false, true, IpStack::V6Only),
93            (true, true, IpStack::DualStack),
94        ] {
95            check(
96                IpStack::from_flags(v4, v6) == expected,
97                "incorrect IP flags mapping",
98            )?;
99        }
100        Ok(())
101    }
102
103    #[test]
104    fn has_ipv4_is_true_only_for_v4_and_dual() -> TestResult {
105        check(
106            !IpStack::None.has_ipv4()
107                && IpStack::V4Only.has_ipv4()
108                && !IpStack::V6Only.has_ipv4()
109                && IpStack::DualStack.has_ipv4(),
110            "IPv4 availability differs from the stack variant",
111        )
112    }
113
114    #[test]
115    fn has_ipv6_is_true_only_for_v6_and_dual() -> TestResult {
116        check(
117            !IpStack::None.has_ipv6()
118                && !IpStack::V4Only.has_ipv6()
119                && IpStack::V6Only.has_ipv6()
120                && IpStack::DualStack.has_ipv6(),
121            "IPv6 availability differs from the stack variant",
122        )
123    }
124
125    #[test]
126    fn is_dual_stack_is_true_only_for_dual() -> TestResult {
127        check(
128            !IpStack::None.is_dual_stack()
129                && !IpStack::V4Only.is_dual_stack()
130                && !IpStack::V6Only.is_dual_stack()
131                && IpStack::DualStack.is_dual_stack(),
132            "dual-stack query differs from the stack variant",
133        )
134    }
135
136    #[test]
137    fn name_and_display_agree() -> TestResult {
138        for variant in [
139            IpStack::None,
140            IpStack::V4Only,
141            IpStack::V6Only,
142            IpStack::DualStack,
143        ] {
144            check(
145                variant.name() == variant.to_string(),
146                "IP stack name and Display disagree",
147            )?;
148        }
149        check(
150            IpStack::DualStack.name() == "DualStack",
151            "dual-stack label changed",
152        )
153    }
154
155    #[test]
156    fn names_are_stable_for_every_variant() -> TestResult {
157        for (variant, expected) in [
158            (IpStack::None, "None"),
159            (IpStack::V4Only, "V4Only"),
160            (IpStack::V6Only, "V6Only"),
161            (IpStack::DualStack, "DualStack"),
162        ] {
163            check(variant.name() == expected, "IP stack label changed")?;
164        }
165        Ok(())
166    }
167}