mctx_core/
config.rs

1use crate::error::MctxError;
2use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
3
4/// The address family used by one publication.
5#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
6pub enum PublicationAddressFamily {
7    Ipv4,
8    Ipv6,
9}
10
11/// Explicit outgoing multicast interface selection.
12#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
13pub enum OutgoingInterface {
14    /// Select the IPv4 multicast egress interface by local IPv4 address.
15    Ipv4Addr(Ipv4Addr),
16    /// Select the IPv6 multicast egress interface by local IPv6 address.
17    ///
18    /// On the IPv6 send path this also provides the exact local address to bind
19    /// when no explicit source address was configured.
20    Ipv6Addr(Ipv6Addr),
21    /// Select the IPv6 multicast egress interface by interface index.
22    Ipv6Index(u32),
23}
24
25impl From<Ipv4Addr> for OutgoingInterface {
26    fn from(value: Ipv4Addr) -> Self {
27        Self::Ipv4Addr(value)
28    }
29}
30
31impl From<Ipv6Addr> for OutgoingInterface {
32    fn from(value: Ipv6Addr) -> Self {
33        Self::Ipv6Addr(value)
34    }
35}
36
37/// The multicast scope encoded in an IPv6 group address.
38#[derive(Debug, Clone, Copy, PartialEq, Eq)]
39pub enum Ipv6MulticastScope {
40    InterfaceLocal,
41    LinkLocal,
42    RealmLocal,
43    AdminLocal,
44    SiteLocal,
45    OrganizationLocal,
46    Global,
47    Other(u8),
48}
49
50/// Configuration for one multicast publication socket.
51#[derive(Debug, Clone, PartialEq, Eq, Hash)]
52pub struct PublicationConfig {
53    /// The destination multicast group.
54    pub group: IpAddr,
55    /// The destination UDP port.
56    pub dst_port: u16,
57    /// The explicit multicast egress interface, if set.
58    pub outgoing_interface: Option<OutgoingInterface>,
59    /// The source UDP port to bind before sending, if explicitly set.
60    pub source_port: Option<u16>,
61    /// The source IP address to bind before sending, if explicitly set.
62    pub source_addr: Option<IpAddr>,
63    /// The multicast TTL (IPv4) or hop limit (IPv6) for transmitted packets.
64    pub ttl: u32,
65    /// Whether outbound multicast packets should be looped back to the local host.
66    pub loopback: bool,
67}
68
69impl PublicationConfig {
70    /// Creates a basic multicast publication configuration.
71    pub fn new(group: impl Into<IpAddr>, port: u16) -> Self {
72        Self {
73            group: group.into(),
74            dst_port: port,
75            outgoing_interface: None,
76            source_port: None,
77            source_addr: None,
78            ttl: 1,
79            loopback: true,
80        }
81    }
82
83    /// Returns the address family for this publication.
84    pub fn family(&self) -> PublicationAddressFamily {
85        match self.group {
86            IpAddr::V4(_) => PublicationAddressFamily::Ipv4,
87            IpAddr::V6(_) => PublicationAddressFamily::Ipv6,
88        }
89    }
90
91    /// Returns `true` when the publication targets an IPv4 group.
92    pub fn is_ipv4(&self) -> bool {
93        matches!(self.family(), PublicationAddressFamily::Ipv4)
94    }
95
96    /// Returns `true` when the publication targets an IPv6 group.
97    pub fn is_ipv6(&self) -> bool {
98        matches!(self.family(), PublicationAddressFamily::Ipv6)
99    }
100
101    /// Validates the configuration and returns an error if it is not usable.
102    pub fn validate(&self) -> Result<(), MctxError> {
103        if self.dst_port == 0 {
104            return Err(MctxError::InvalidDestinationPort);
105        }
106
107        if !self.group.is_multicast() {
108            return Err(MctxError::InvalidMulticastGroup);
109        }
110
111        if matches!(self.source_port, Some(0)) {
112            return Err(MctxError::InvalidSourcePort);
113        }
114
115        if let Some(source_addr) = self.source_addr {
116            if source_addr.is_multicast() || source_addr.is_unspecified() {
117                return Err(MctxError::InvalidSourceAddress);
118            }
119
120            if !same_family_ip(self.group, source_addr) {
121                return Err(MctxError::SourceAddressFamilyMismatch);
122            }
123        }
124
125        if let Some(interface) = self.outgoing_interface {
126            match (self.family(), interface) {
127                (PublicationAddressFamily::Ipv4, OutgoingInterface::Ipv4Addr(interface)) => {
128                    if interface.is_multicast() || interface.is_unspecified() {
129                        return Err(MctxError::InvalidInterfaceAddress);
130                    }
131                }
132                (PublicationAddressFamily::Ipv4, OutgoingInterface::Ipv6Addr(_))
133                | (PublicationAddressFamily::Ipv4, OutgoingInterface::Ipv6Index(_)) => {
134                    return Err(MctxError::OutgoingInterfaceFamilyMismatch);
135                }
136                (PublicationAddressFamily::Ipv6, OutgoingInterface::Ipv4Addr(_)) => {
137                    return Err(MctxError::OutgoingInterfaceFamilyMismatch);
138                }
139                (PublicationAddressFamily::Ipv6, OutgoingInterface::Ipv6Addr(interface)) => {
140                    if interface.is_multicast() || interface.is_unspecified() {
141                        return Err(MctxError::InvalidInterfaceAddress);
142                    }
143                }
144                (PublicationAddressFamily::Ipv6, OutgoingInterface::Ipv6Index(index)) => {
145                    if index == 0 {
146                        return Err(MctxError::InvalidIpv6InterfaceIndex);
147                    }
148                }
149            }
150        }
151
152        Ok(())
153    }
154
155    /// Sets the multicast egress interface.
156    pub fn with_outgoing_interface(
157        mut self,
158        outgoing_interface: impl Into<OutgoingInterface>,
159    ) -> Self {
160        self.outgoing_interface = Some(outgoing_interface.into());
161        self
162    }
163
164    /// Sets the multicast egress interface using the existing IPv4-oriented
165    /// convenience builder.
166    pub fn with_interface(self, interface: Ipv4Addr) -> Self {
167        self.with_outgoing_interface(interface)
168    }
169
170    /// Sets the IPv6 multicast egress interface by interface index.
171    pub fn with_ipv6_interface_index(mut self, interface_index: u32) -> Self {
172        self.outgoing_interface = Some(OutgoingInterface::Ipv6Index(interface_index));
173        self
174    }
175
176    /// Sets the source UDP port.
177    pub fn with_source_port(mut self, source_port: u16) -> Self {
178        self.source_port = Some(source_port);
179        self
180    }
181
182    /// Sets the exact local source address to bind before sending.
183    pub fn with_source_addr(mut self, source_addr: impl Into<IpAddr>) -> Self {
184        self.source_addr = Some(source_addr.into());
185        self
186    }
187
188    /// Sets the exact local address and UDP port to bind before sending.
189    pub fn with_bind_addr(mut self, bind_addr: impl Into<SocketAddr>) -> Self {
190        let bind_addr = bind_addr.into();
191        self.source_addr = Some(bind_addr.ip());
192        self.source_port = Some(bind_addr.port());
193        self
194    }
195
196    /// Sets the multicast TTL (IPv4) or hop limit (IPv6).
197    pub fn with_ttl(mut self, ttl: u32) -> Self {
198        self.ttl = ttl;
199        self
200    }
201
202    /// Enables or disables multicast loopback.
203    pub fn with_loopback(mut self, loopback: bool) -> Self {
204        self.loopback = loopback;
205        self
206    }
207
208    /// Returns the multicast scope for the configured IPv6 group, if applicable.
209    pub fn ipv6_scope(&self) -> Option<Ipv6MulticastScope> {
210        match self.group {
211            IpAddr::V6(group) => ipv6_multicast_scope(group),
212            IpAddr::V4(_) => None,
213        }
214    }
215}
216
217fn same_family_ip(left: IpAddr, right: IpAddr) -> bool {
218    matches!(
219        (left, right),
220        (IpAddr::V4(_), IpAddr::V4(_)) | (IpAddr::V6(_), IpAddr::V6(_))
221    )
222}
223
224/// Returns `true` if the group is in `ff3x::/32`.
225pub fn is_ipv6_ssm_group(group: Ipv6Addr) -> bool {
226    group.is_multicast() && (group.octets()[1] & 0xf0) == 0x30
227}
228
229pub(crate) fn ipv6_multicast_scope(group: Ipv6Addr) -> Option<Ipv6MulticastScope> {
230    if !group.is_multicast() {
231        return None;
232    }
233
234    let scope = group.octets()[1] & 0x0f;
235    Some(match scope {
236        0x1 => Ipv6MulticastScope::InterfaceLocal,
237        0x2 => Ipv6MulticastScope::LinkLocal,
238        0x3 => Ipv6MulticastScope::RealmLocal,
239        0x4 => Ipv6MulticastScope::AdminLocal,
240        0x5 => Ipv6MulticastScope::SiteLocal,
241        0x8 => Ipv6MulticastScope::OrganizationLocal,
242        0xe => Ipv6MulticastScope::Global,
243        other => Ipv6MulticastScope::Other(other),
244    })
245}
246
247pub(crate) fn ipv6_destination_scope_id(group: Ipv6Addr, interface_index: u32) -> u32 {
248    match ipv6_multicast_scope(group) {
249        Some(Ipv6MulticastScope::InterfaceLocal | Ipv6MulticastScope::LinkLocal) => interface_index,
250        _ => 0,
251    }
252}
253
254#[cfg(test)]
255mod tests {
256    use super::*;
257    use std::net::{SocketAddrV4, SocketAddrV6};
258
259    #[test]
260    fn valid_ipv4_multicast_config_passes_validation() {
261        let cfg = PublicationConfig::new(Ipv4Addr::new(239, 1, 2, 3), 5000)
262            .with_source_port(5001)
263            .with_source_addr(Ipv4Addr::new(192, 168, 10, 5))
264            .with_ttl(8)
265            .with_loopback(false);
266
267        assert!(cfg.validate().is_ok());
268    }
269
270    #[test]
271    fn valid_ipv6_multicast_config_passes_validation() {
272        let cfg = PublicationConfig::new("ff31::8000:1234".parse::<Ipv6Addr>().unwrap(), 5000)
273            .with_source_addr("::1".parse::<Ipv6Addr>().unwrap())
274            .with_outgoing_interface("::1".parse::<Ipv6Addr>().unwrap())
275            .with_ttl(4);
276
277        assert!(cfg.validate().is_ok());
278        assert!(cfg.is_ipv6());
279    }
280
281    #[test]
282    fn port_zero_fails_validation() {
283        let cfg = PublicationConfig::new(Ipv4Addr::new(239, 1, 2, 3), 0);
284
285        let result = cfg.validate();
286
287        assert!(matches!(result, Err(MctxError::InvalidDestinationPort)));
288    }
289
290    #[test]
291    fn non_multicast_group_fails_validation() {
292        let cfg = PublicationConfig::new(Ipv4Addr::new(192, 168, 1, 10), 5000);
293
294        let result = cfg.validate();
295
296        assert!(matches!(result, Err(MctxError::InvalidMulticastGroup)));
297    }
298
299    #[test]
300    fn family_mismatched_source_fails_validation() {
301        let cfg = PublicationConfig::new(Ipv4Addr::new(239, 1, 2, 3), 5000)
302            .with_source_addr("::1".parse::<Ipv6Addr>().unwrap());
303
304        let result = cfg.validate();
305
306        assert!(matches!(
307            result,
308            Err(MctxError::SourceAddressFamilyMismatch)
309        ));
310    }
311
312    #[test]
313    fn family_mismatched_interface_fails_validation() {
314        let cfg = PublicationConfig::new("ff31::8000:1234".parse::<Ipv6Addr>().unwrap(), 5000)
315            .with_interface(Ipv4Addr::new(192, 168, 1, 10));
316
317        let result = cfg.validate();
318
319        assert!(matches!(
320            result,
321            Err(MctxError::OutgoingInterfaceFamilyMismatch)
322        ));
323    }
324
325    #[test]
326    fn unspecified_source_addr_fails_validation() {
327        let cfg = PublicationConfig::new(Ipv4Addr::new(239, 1, 2, 3), 5000)
328            .with_source_addr(Ipv4Addr::UNSPECIFIED);
329
330        let result = cfg.validate();
331
332        assert!(matches!(result, Err(MctxError::InvalidSourceAddress)));
333    }
334
335    #[test]
336    fn zero_ipv6_interface_index_fails_validation() {
337        let cfg = PublicationConfig::new("ff31::8000:1234".parse::<Ipv6Addr>().unwrap(), 5000)
338            .with_ipv6_interface_index(0);
339
340        let result = cfg.validate();
341
342        assert!(matches!(result, Err(MctxError::InvalidIpv6InterfaceIndex)));
343    }
344
345    #[test]
346    fn bind_addr_builder_sets_source_fields_for_ipv4() {
347        let bind_addr = SocketAddrV4::new(Ipv4Addr::new(10, 1, 2, 3), 5001);
348        let cfg =
349            PublicationConfig::new(Ipv4Addr::new(239, 1, 2, 3), 5000).with_bind_addr(bind_addr);
350
351        assert_eq!(
352            cfg.source_addr,
353            Some(IpAddr::V4(Ipv4Addr::new(10, 1, 2, 3)))
354        );
355        assert_eq!(cfg.source_port, Some(5001));
356    }
357
358    #[test]
359    fn bind_addr_builder_sets_source_fields_for_ipv6() {
360        let bind_addr = SocketAddrV6::new("fd00::10".parse().unwrap(), 5001, 0, 0);
361        let cfg = PublicationConfig::new("ff3e::8000:1234".parse::<Ipv6Addr>().unwrap(), 5000)
362            .with_bind_addr(bind_addr);
363
364        assert_eq!(
365            cfg.source_addr,
366            Some(IpAddr::V6("fd00::10".parse::<Ipv6Addr>().unwrap()))
367        );
368        assert_eq!(cfg.source_port, Some(5001));
369    }
370
371    #[test]
372    fn ipv6_ssm_detection_only_matches_ff3x_groups() {
373        assert!(is_ipv6_ssm_group("ff31::8000:1234".parse().unwrap()));
374        assert!(is_ipv6_ssm_group("ff3e::8000:1234".parse().unwrap()));
375        assert!(!is_ipv6_ssm_group("ff12::1234".parse().unwrap()));
376    }
377
378    #[test]
379    fn link_local_ipv6_group_keeps_interface_index_in_destination_scope() {
380        let group = "ff32::8000:1234".parse::<Ipv6Addr>().unwrap();
381
382        assert_eq!(ipv6_destination_scope_id(group, 7), 7);
383    }
384
385    #[test]
386    fn wider_scope_ipv6_group_clears_destination_scope() {
387        let group = "ff3e::8000:1234".parse::<Ipv6Addr>().unwrap();
388
389        assert_eq!(ipv6_destination_scope_id(group, 7), 0);
390    }
391}
mctx_core/config.rs

mctx_core/
config.rs
