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
194        // Preserve an explicit IPv6 scope ID from scoped bind addresses so
195        // link-local senders keep their interface identity through socket setup.
196        if let SocketAddr::V6(bind_addr_v6) = bind_addr
197            && bind_addr_v6.scope_id() != 0
198        {
199            self.outgoing_interface = Some(OutgoingInterface::Ipv6Index(bind_addr_v6.scope_id()));
200        }
201
202        self
203    }
204
205    /// Sets the multicast TTL (IPv4) or hop limit (IPv6).
206    pub fn with_ttl(mut self, ttl: u32) -> Self {
207        self.ttl = ttl;
208        self
209    }
210
211    /// Enables or disables multicast loopback.
212    pub fn with_loopback(mut self, loopback: bool) -> Self {
213        self.loopback = loopback;
214        self
215    }
216
217    /// Returns the multicast scope for the configured IPv6 group, if applicable.
218    pub fn ipv6_scope(&self) -> Option<Ipv6MulticastScope> {
219        match self.group {
220            IpAddr::V6(group) => ipv6_multicast_scope(group),
221            IpAddr::V4(_) => None,
222        }
223    }
224}
225
226fn same_family_ip(left: IpAddr, right: IpAddr) -> bool {
227    matches!(
228        (left, right),
229        (IpAddr::V4(_), IpAddr::V4(_)) | (IpAddr::V6(_), IpAddr::V6(_))
230    )
231}
232
233/// Returns `true` if the group is in `ff3x::/32`.
234pub fn is_ipv6_ssm_group(group: Ipv6Addr) -> bool {
235    group.is_multicast() && (group.octets()[1] & 0xf0) == 0x30
236}
237
238pub(crate) fn ipv6_multicast_scope(group: Ipv6Addr) -> Option<Ipv6MulticastScope> {
239    if !group.is_multicast() {
240        return None;
241    }
242
243    let scope = group.octets()[1] & 0x0f;
244    Some(match scope {
245        0x1 => Ipv6MulticastScope::InterfaceLocal,
246        0x2 => Ipv6MulticastScope::LinkLocal,
247        0x3 => Ipv6MulticastScope::RealmLocal,
248        0x4 => Ipv6MulticastScope::AdminLocal,
249        0x5 => Ipv6MulticastScope::SiteLocal,
250        0x8 => Ipv6MulticastScope::OrganizationLocal,
251        0xe => Ipv6MulticastScope::Global,
252        other => Ipv6MulticastScope::Other(other),
253    })
254}
255
256pub(crate) fn ipv6_destination_scope_id(group: Ipv6Addr, interface_index: u32) -> u32 {
257    match ipv6_multicast_scope(group) {
258        Some(Ipv6MulticastScope::InterfaceLocal | Ipv6MulticastScope::LinkLocal) => interface_index,
259        _ => 0,
260    }
261}
262
263#[cfg(test)]
264mod tests {
265    use super::*;
266    use std::net::{SocketAddrV4, SocketAddrV6};
267
268    #[test]
269    fn valid_ipv4_multicast_config_passes_validation() {
270        let cfg = PublicationConfig::new(Ipv4Addr::new(239, 1, 2, 3), 5000)
271            .with_source_port(5001)
272            .with_source_addr(Ipv4Addr::new(192, 168, 10, 5))
273            .with_ttl(8)
274            .with_loopback(false);
275
276        assert!(cfg.validate().is_ok());
277    }
278
279    #[test]
280    fn valid_ipv6_multicast_config_passes_validation() {
281        let cfg = PublicationConfig::new("ff31::8000:1234".parse::<Ipv6Addr>().unwrap(), 5000)
282            .with_source_addr("::1".parse::<Ipv6Addr>().unwrap())
283            .with_outgoing_interface("::1".parse::<Ipv6Addr>().unwrap())
284            .with_ttl(4);
285
286        assert!(cfg.validate().is_ok());
287        assert!(cfg.is_ipv6());
288    }
289
290    #[test]
291    fn port_zero_fails_validation() {
292        let cfg = PublicationConfig::new(Ipv4Addr::new(239, 1, 2, 3), 0);
293
294        let result = cfg.validate();
295
296        assert!(matches!(result, Err(MctxError::InvalidDestinationPort)));
297    }
298
299    #[test]
300    fn non_multicast_group_fails_validation() {
301        let cfg = PublicationConfig::new(Ipv4Addr::new(192, 168, 1, 10), 5000);
302
303        let result = cfg.validate();
304
305        assert!(matches!(result, Err(MctxError::InvalidMulticastGroup)));
306    }
307
308    #[test]
309    fn family_mismatched_source_fails_validation() {
310        let cfg = PublicationConfig::new(Ipv4Addr::new(239, 1, 2, 3), 5000)
311            .with_source_addr("::1".parse::<Ipv6Addr>().unwrap());
312
313        let result = cfg.validate();
314
315        assert!(matches!(
316            result,
317            Err(MctxError::SourceAddressFamilyMismatch)
318        ));
319    }
320
321    #[test]
322    fn family_mismatched_interface_fails_validation() {
323        let cfg = PublicationConfig::new("ff31::8000:1234".parse::<Ipv6Addr>().unwrap(), 5000)
324            .with_interface(Ipv4Addr::new(192, 168, 1, 10));
325
326        let result = cfg.validate();
327
328        assert!(matches!(
329            result,
330            Err(MctxError::OutgoingInterfaceFamilyMismatch)
331        ));
332    }
333
334    #[test]
335    fn unspecified_source_addr_fails_validation() {
336        let cfg = PublicationConfig::new(Ipv4Addr::new(239, 1, 2, 3), 5000)
337            .with_source_addr(Ipv4Addr::UNSPECIFIED);
338
339        let result = cfg.validate();
340
341        assert!(matches!(result, Err(MctxError::InvalidSourceAddress)));
342    }
343
344    #[test]
345    fn zero_ipv6_interface_index_fails_validation() {
346        let cfg = PublicationConfig::new("ff31::8000:1234".parse::<Ipv6Addr>().unwrap(), 5000)
347            .with_ipv6_interface_index(0);
348
349        let result = cfg.validate();
350
351        assert!(matches!(result, Err(MctxError::InvalidIpv6InterfaceIndex)));
352    }
353
354    #[test]
355    fn bind_addr_builder_sets_source_fields_for_ipv4() {
356        let bind_addr = SocketAddrV4::new(Ipv4Addr::new(10, 1, 2, 3), 5001);
357        let cfg =
358            PublicationConfig::new(Ipv4Addr::new(239, 1, 2, 3), 5000).with_bind_addr(bind_addr);
359
360        assert_eq!(
361            cfg.source_addr,
362            Some(IpAddr::V4(Ipv4Addr::new(10, 1, 2, 3)))
363        );
364        assert_eq!(cfg.source_port, Some(5001));
365    }
366
367    #[test]
368    fn bind_addr_builder_sets_source_fields_for_ipv6() {
369        let bind_addr = SocketAddrV6::new("fd00::10".parse().unwrap(), 5001, 0, 0);
370        let cfg = PublicationConfig::new("ff3e::8000:1234".parse::<Ipv6Addr>().unwrap(), 5000)
371            .with_bind_addr(bind_addr);
372
373        assert_eq!(
374            cfg.source_addr,
375            Some(IpAddr::V6("fd00::10".parse::<Ipv6Addr>().unwrap()))
376        );
377        assert_eq!(cfg.source_port, Some(5001));
378    }
379
380    #[test]
381    fn bind_addr_builder_preserves_ipv6_scope_as_interface_index() {
382        let bind_addr = SocketAddrV6::new("fe80::1234".parse().unwrap(), 5001, 0, 7);
383        let cfg = PublicationConfig::new("ff32::8000:1234".parse::<Ipv6Addr>().unwrap(), 5000)
384            .with_bind_addr(bind_addr);
385
386        assert_eq!(
387            cfg.outgoing_interface,
388            Some(OutgoingInterface::Ipv6Index(7))
389        );
390    }
391
392    #[test]
393    fn ipv6_ssm_detection_only_matches_ff3x_groups() {
394        assert!(is_ipv6_ssm_group("ff31::8000:1234".parse().unwrap()));
395        assert!(is_ipv6_ssm_group("ff3e::8000:1234".parse().unwrap()));
396        assert!(!is_ipv6_ssm_group("ff12::1234".parse().unwrap()));
397    }
398
399    #[test]
400    fn link_local_ipv6_group_keeps_interface_index_in_destination_scope() {
401        let group = "ff32::8000:1234".parse::<Ipv6Addr>().unwrap();
402
403        assert_eq!(ipv6_destination_scope_id(group, 7), 7);
404    }
405
406    #[test]
407    fn wider_scope_ipv6_group_clears_destination_scope() {
408        let group = "ff3e::8000:1234".parse::<Ipv6Addr>().unwrap();
409
410        assert_eq!(ipv6_destination_scope_id(group, 7), 0);
411    }
412}
mctx_core/config.rs

mctx_core/
config.rs
