netstack3_base/socket/
base.rs

1// Copyright 2020 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! General-purpose socket utilities common to device layer and IP layer
6//! sockets.
7
8use core::convert::Infallible as Never;
9use core::fmt::Debug;
10use core::hash::Hash;
11use core::marker::PhantomData;
12use core::num::NonZeroU16;
13
14use derivative::Derivative;
15use net_types::ip::{GenericOverIp, Ip, IpAddress, IpVersionMarker, Ipv4, Ipv6};
16use net_types::{
17    AddrAndZone, MulticastAddress, ScopeableAddress, SpecifiedAddr, Witness, ZonedAddr,
18};
19use thiserror::Error;
20
21use crate::data_structures::socketmap::{
22    Entry, IterShadows, OccupiedEntry as SocketMapOccupiedEntry, SocketMap, Tagged,
23};
24use crate::device::{
25    DeviceIdentifier, EitherDeviceId, StrongDeviceIdentifier, WeakDeviceIdentifier,
26};
27use crate::error::{ExistsError, NotFoundError, ZonedAddressError};
28use crate::ip::BroadcastIpExt;
29use crate::socket::address::{
30    AddrVecIter, ConnAddr, ConnIpAddr, ListenerAddr, ListenerIpAddr, SocketIpAddr,
31};
32
33/// A dual stack IP extention trait that provides the `OtherVersion` associated
34/// type.
35pub trait DualStackIpExt: Ip {
36    /// The "other" IP version, e.g. [`Ipv4`] for [`Ipv6`] and vice-versa.
37    type OtherVersion: DualStackIpExt<OtherVersion = Self>;
38}
39
40impl DualStackIpExt for Ipv4 {
41    type OtherVersion = Ipv6;
42}
43
44impl DualStackIpExt for Ipv6 {
45    type OtherVersion = Ipv4;
46}
47
48/// A tuple of values for `T` for both `I` and `I::OtherVersion`.
49pub struct DualStackTuple<I: DualStackIpExt, T: GenericOverIp<I> + GenericOverIp<I::OtherVersion>> {
50    this_stack: <T as GenericOverIp<I>>::Type,
51    other_stack: <T as GenericOverIp<I::OtherVersion>>::Type,
52    _marker: IpVersionMarker<I>,
53}
54
55impl<I: DualStackIpExt, T: GenericOverIp<I> + GenericOverIp<I::OtherVersion>> DualStackTuple<I, T> {
56    /// Creates a new tuple with `this_stack` and `other_stack` values.
57    pub fn new(this_stack: T, other_stack: <T as GenericOverIp<I::OtherVersion>>::Type) -> Self
58    where
59        T: GenericOverIp<I, Type = T>,
60    {
61        Self { this_stack, other_stack, _marker: IpVersionMarker::new() }
62    }
63
64    /// Retrieves `(this_stack, other_stack)` from the tuple.
65    pub fn into_inner(
66        self,
67    ) -> (<T as GenericOverIp<I>>::Type, <T as GenericOverIp<I::OtherVersion>>::Type) {
68        let Self { this_stack, other_stack, _marker } = self;
69        (this_stack, other_stack)
70    }
71
72    /// Retrieves `this_stack` from the tuple.
73    pub fn into_this_stack(self) -> <T as GenericOverIp<I>>::Type {
74        self.this_stack
75    }
76
77    /// Borrows `this_stack` from the tuple.
78    pub fn this_stack(&self) -> &<T as GenericOverIp<I>>::Type {
79        &self.this_stack
80    }
81
82    /// Retrieves `other_stack` from the tuple.
83    pub fn into_other_stack(self) -> <T as GenericOverIp<I::OtherVersion>>::Type {
84        self.other_stack
85    }
86
87    /// Borrows `other_stack` from the tuple.
88    pub fn other_stack(&self) -> &<T as GenericOverIp<I::OtherVersion>>::Type {
89        &self.other_stack
90    }
91
92    /// Flips the types, making `this_stack` `other_stack` and vice-versa.
93    pub fn flip(self) -> DualStackTuple<I::OtherVersion, T> {
94        let Self { this_stack, other_stack, _marker } = self;
95        DualStackTuple {
96            this_stack: other_stack,
97            other_stack: this_stack,
98            _marker: IpVersionMarker::new(),
99        }
100    }
101
102    /// Casts to IP version `X`.
103    ///
104    /// Given `DualStackTuple` contains complete information for both IP
105    /// versions, it can be easily cast into an arbitrary `X` IP version.
106    ///
107    /// This can be used to tie together type parameters when dealing with dual
108    /// stack sockets. For example, a `DualStackTuple` defined for `SockI` can
109    /// be cast to any `WireI`.
110    pub fn cast<X>(self) -> DualStackTuple<X, T>
111    where
112        X: DualStackIpExt,
113        T: GenericOverIp<X>
114            + GenericOverIp<X::OtherVersion>
115            + GenericOverIp<Ipv4>
116            + GenericOverIp<Ipv6>,
117    {
118        I::map_ip_in(
119            self,
120            |v4| X::map_ip_out(v4, |t| t, |t| t.flip()),
121            |v6| X::map_ip_out(v6, |t| t.flip(), |t| t),
122        )
123    }
124}
125
126impl<
127        I: DualStackIpExt,
128        NewIp: DualStackIpExt,
129        T: GenericOverIp<NewIp>
130            + GenericOverIp<NewIp::OtherVersion>
131            + GenericOverIp<I>
132            + GenericOverIp<I::OtherVersion>,
133    > GenericOverIp<NewIp> for DualStackTuple<I, T>
134{
135    type Type = DualStackTuple<NewIp, T>;
136}
137
138/// Extension trait for `Ip` providing socket-specific functionality.
139pub trait SocketIpExt: Ip {
140    /// `Self::LOOPBACK_ADDRESS`, but wrapped in the `SocketIpAddr` type.
141    const LOOPBACK_ADDRESS_AS_SOCKET_IP_ADDR: SocketIpAddr<Self::Addr> = unsafe {
142        // SAFETY: The loopback address is a valid SocketIpAddr, as verified
143        // in the `loopback_addr_is_valid_socket_addr` test.
144        SocketIpAddr::new_from_specified_unchecked(Self::LOOPBACK_ADDRESS)
145    };
146}
147
148impl<I: Ip> SocketIpExt for I {}
149
150#[cfg(test)]
151mod socket_ip_ext_test {
152    use super::*;
153    use ip_test_macro::ip_test;
154
155    #[ip_test(I)]
156    fn loopback_addr_is_valid_socket_addr<I: SocketIpExt>() {
157        // `LOOPBACK_ADDRESS_AS_SOCKET_IP_ADDR is defined with the "unchecked"
158        // constructor (which supports const construction). Verify here that the
159        // addr actually satisfies all the requirements (protecting against far
160        // away changes)
161        let _addr = SocketIpAddr::new(I::LOOPBACK_ADDRESS_AS_SOCKET_IP_ADDR.addr())
162            .expect("loopback address should be a valid SocketIpAddr");
163    }
164}
165
166/// State belonging to either IP stack.
167///
168/// Like `[either::Either]`, but with more helpful variant names.
169///
170/// Note that this type is not optimally type-safe, because `T` and `O` are not
171/// bound by `IP` and `IP::OtherVersion`, respectively. In many cases it may be
172/// more appropriate to define a one-off enum parameterized over `I: Ip`.
173#[derive(Debug, PartialEq, Eq)]
174pub enum EitherStack<T, O> {
175    /// In the current stack version.
176    ThisStack(T),
177    /// In the other version of the stack.
178    OtherStack(O),
179}
180
181impl<T, O> Clone for EitherStack<T, O>
182where
183    T: Clone,
184    O: Clone,
185{
186    #[cfg_attr(feature = "instrumented", track_caller)]
187    fn clone(&self) -> Self {
188        match self {
189            Self::ThisStack(t) => Self::ThisStack(t.clone()),
190            Self::OtherStack(t) => Self::OtherStack(t.clone()),
191        }
192    }
193}
194
195/// Control flow type containing either a dual-stack or non-dual-stack context.
196///
197/// This type exists to provide nice names to the result of
198/// [`BoundStateContext::dual_stack_context`], and to allow generic code to
199/// match on when checking whether a socket protocol and IP version support
200/// dual-stack operation. If dual-stack operation is supported, a
201/// [`MaybeDualStack::DualStack`] value will be held, otherwise a `NonDualStack`
202/// value.
203///
204/// Note that the templated types to not have trait bounds; those are provided
205/// by the trait with the `dual_stack_context` function.
206///
207/// In monomorphized code, this type frequently has exactly one template
208/// parameter that is uninstantiable (it contains an instance of
209/// [`core::convert::Infallible`] or some other empty enum, or a reference to
210/// the same)! That lets the compiler optimize it out completely, creating no
211/// actual runtime overhead.
212#[derive(Debug)]
213#[allow(missing_docs)]
214pub enum MaybeDualStack<DS, NDS> {
215    DualStack(DS),
216    NotDualStack(NDS),
217}
218
219// Implement `GenericOverIp` for a `MaybeDualStack` whose `DS` and `NDS` also
220// implement `GenericOverIp`.
221impl<I: DualStackIpExt, DS: GenericOverIp<I>, NDS: GenericOverIp<I>> GenericOverIp<I>
222    for MaybeDualStack<DS, NDS>
223{
224    type Type = MaybeDualStack<<DS as GenericOverIp<I>>::Type, <NDS as GenericOverIp<I>>::Type>;
225}
226
227/// An error encountered while enabling or disabling dual-stack operation.
228#[derive(Copy, Clone, Debug, Eq, GenericOverIp, PartialEq, Error)]
229#[generic_over_ip()]
230pub enum SetDualStackEnabledError {
231    /// A socket can only have dual stack enabled or disabled while unbound.
232    #[error("a socket can only have dual stack enabled or disabled while unbound")]
233    SocketIsBound,
234    /// The socket's protocol is not dual stack capable.
235    #[error(transparent)]
236    NotCapable(#[from] NotDualStackCapableError),
237}
238
239/// An error encountered when attempting to perform dual stack operations on
240/// socket with a non dual stack capable protocol.
241#[derive(Copy, Clone, Debug, Eq, GenericOverIp, PartialEq, Error)]
242#[generic_over_ip()]
243#[error("socket's protocol is not dual-stack capable")]
244pub struct NotDualStackCapableError;
245
246/// Describes which direction(s) of the data path should be shut down.
247#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
248pub struct Shutdown {
249    /// True if the send path is shut down for the owning socket.
250    ///
251    /// If this is true, the socket should not be able to send packets.
252    pub send: bool,
253    /// True if the receive path is shut down for the owning socket.
254    ///
255    /// If this is true, the socket should not be able to receive packets.
256    pub receive: bool,
257}
258
259/// Which direction(s) to shut down for a socket.
260#[derive(Copy, Clone, Debug, Eq, GenericOverIp, PartialEq)]
261#[generic_over_ip()]
262pub enum ShutdownType {
263    /// Prevent sending packets on the socket.
264    Send,
265    /// Prevent receiving packets on the socket.
266    Receive,
267    /// Prevent sending and receiving packets on the socket.
268    SendAndReceive,
269}
270
271impl ShutdownType {
272    /// Returns a tuple of booleans for `(shutdown_send, shutdown_receive)`.
273    pub fn to_send_receive(&self) -> (bool, bool) {
274        match self {
275            Self::Send => (true, false),
276            Self::Receive => (false, true),
277            Self::SendAndReceive => (true, true),
278        }
279    }
280
281    /// Creates a [`ShutdownType`] from a pair of bools for send and receive.
282    pub fn from_send_receive(send: bool, receive: bool) -> Option<Self> {
283        match (send, receive) {
284            (true, false) => Some(Self::Send),
285            (false, true) => Some(Self::Receive),
286            (true, true) => Some(Self::SendAndReceive),
287            (false, false) => None,
288        }
289    }
290}
291
292/// Extensions to IP Address witnesses useful in the context of sockets.
293pub trait SocketIpAddrExt<A: IpAddress>: Witness<A> + ScopeableAddress {
294    /// Determines whether the provided address is underspecified by itself.
295    ///
296    /// Some addresses are ambiguous and so must have a zone identifier in order
297    /// to be used in a socket address. This function returns true for IPv6
298    /// link-local addresses and false for all others.
299    fn must_have_zone(&self) -> bool
300    where
301        Self: Copy,
302    {
303        self.try_into_null_zoned().is_some()
304    }
305
306    /// Converts into a [`AddrAndZone<A, ()>`] if the address requires a zone.
307    ///
308    /// Otherwise returns `None`.
309    fn try_into_null_zoned(self) -> Option<AddrAndZone<Self, ()>> {
310        if self.get().is_loopback() {
311            return None;
312        }
313        AddrAndZone::new(self, ())
314    }
315}
316
317impl<A: IpAddress, W: Witness<A> + ScopeableAddress> SocketIpAddrExt<A> for W {}
318
319/// An extention trait for [`ZonedAddr`].
320pub trait SocketZonedAddrExt<W, A, D> {
321    /// Returns the address and device that should be used for a socket.
322    ///
323    /// Given an address for a socket and an optional device that the socket is
324    /// already bound on, returns the address and device that should be used
325    /// for the socket. If `addr` and `device` require inconsistent devices,
326    /// or if `addr` requires a zone but there is none specified (by `addr` or
327    /// `device`), an error is returned.
328    fn resolve_addr_with_device(
329        self,
330        device: Option<D::Weak>,
331    ) -> Result<(W, Option<EitherDeviceId<D, D::Weak>>), ZonedAddressError>
332    where
333        D: StrongDeviceIdentifier;
334}
335
336impl<W, A, D> SocketZonedAddrExt<W, A, D> for ZonedAddr<W, D>
337where
338    W: ScopeableAddress + AsRef<SpecifiedAddr<A>>,
339    A: IpAddress,
340{
341    fn resolve_addr_with_device(
342        self,
343        device: Option<D::Weak>,
344    ) -> Result<(W, Option<EitherDeviceId<D, D::Weak>>), ZonedAddressError>
345    where
346        D: StrongDeviceIdentifier,
347    {
348        let (addr, zone) = self.into_addr_zone();
349        let device = match (zone, device) {
350            (Some(zone), Some(device)) => {
351                if device != zone {
352                    return Err(ZonedAddressError::DeviceZoneMismatch);
353                }
354                Some(EitherDeviceId::Strong(zone))
355            }
356            (Some(zone), None) => Some(EitherDeviceId::Strong(zone)),
357            (None, Some(device)) => Some(EitherDeviceId::Weak(device)),
358            (None, None) => {
359                if addr.as_ref().must_have_zone() {
360                    return Err(ZonedAddressError::RequiredZoneNotProvided);
361                } else {
362                    None
363                }
364            }
365        };
366        Ok((addr, device))
367    }
368}
369
370/// A helper type to verify if applying socket updates is allowed for a given
371/// current state.
372///
373/// The fields in `SocketDeviceUpdate` define the current state,
374/// [`SocketDeviceUpdate::try_update`] applies the verification logic.
375pub struct SocketDeviceUpdate<'a, A: IpAddress, D: WeakDeviceIdentifier> {
376    /// The current local IP address.
377    pub local_ip: Option<&'a SpecifiedAddr<A>>,
378    /// The current remote IP address.
379    pub remote_ip: Option<&'a SpecifiedAddr<A>>,
380    /// The currently bound device.
381    pub old_device: Option<&'a D>,
382}
383
384impl<'a, A: IpAddress, D: WeakDeviceIdentifier> SocketDeviceUpdate<'a, A, D> {
385    /// Checks if an update from `old_device` to `new_device` is allowed,
386    /// returning an error if not.
387    pub fn check_update<N>(
388        self,
389        new_device: Option<&N>,
390    ) -> Result<(), SocketDeviceUpdateNotAllowedError>
391    where
392        D: PartialEq<N>,
393    {
394        let Self { local_ip, remote_ip, old_device } = self;
395        let must_have_zone = local_ip.is_some_and(|a| a.must_have_zone())
396            || remote_ip.is_some_and(|a| a.must_have_zone());
397
398        if !must_have_zone {
399            return Ok(());
400        }
401
402        let old_device = old_device.unwrap_or_else(|| {
403            panic!("local_ip={:?} or remote_ip={:?} must have zone", local_ip, remote_ip)
404        });
405
406        if new_device.is_some_and(|new_device| old_device == new_device) {
407            Ok(())
408        } else {
409            Err(SocketDeviceUpdateNotAllowedError)
410        }
411    }
412}
413
414/// The device can't be updated on a socket.
415pub struct SocketDeviceUpdateNotAllowedError;
416
417/// Specification for the identifiers in an [`AddrVec`].
418///
419/// This is a convenience trait for bundling together the local and remote
420/// identifiers for a protocol.
421pub trait SocketMapAddrSpec {
422    /// The local identifier portion of a socket address.
423    type LocalIdentifier: Copy + Clone + Debug + Send + Sync + Hash + Eq + Into<NonZeroU16>;
424    /// The remote identifier portion of a socket address.
425    type RemoteIdentifier: Copy + Clone + Debug + Send + Sync + Hash + Eq;
426}
427
428/// Information about the address in a [`ListenerAddr`].
429pub struct ListenerAddrInfo {
430    /// Whether the address has a device bound.
431    pub has_device: bool,
432    /// Whether the listener is on a specified address (as opposed to a blanket
433    /// listener).
434    pub specified_addr: bool,
435}
436
437impl<A: IpAddress, D: DeviceIdentifier, LI> ListenerAddr<ListenerIpAddr<A, LI>, D> {
438    pub(crate) fn info(&self) -> ListenerAddrInfo {
439        let Self { device, ip: ListenerIpAddr { addr, identifier: _ } } = self;
440        ListenerAddrInfo { has_device: device.is_some(), specified_addr: addr.is_some() }
441    }
442}
443
444/// Specifies the types parameters for [`BoundSocketMap`] state as a single bundle.
445pub trait SocketMapStateSpec {
446    /// The tag value of a socket address vector entry.
447    ///
448    /// These values are derived from [`Self::ListenerAddrState`] and
449    /// [`Self::ConnAddrState`].
450    type AddrVecTag: Eq + Copy + Debug + 'static;
451
452    /// Returns a the tag for a listener in the socket map.
453    fn listener_tag(info: ListenerAddrInfo, state: &Self::ListenerAddrState) -> Self::AddrVecTag;
454
455    /// Returns a the tag for a connected socket in the socket map.
456    fn connected_tag(has_device: bool, state: &Self::ConnAddrState) -> Self::AddrVecTag;
457
458    /// An identifier for a listening socket.
459    type ListenerId: Clone + Debug;
460    /// An identifier for a connected socket.
461    type ConnId: Clone + Debug;
462
463    /// The state stored for a listening socket that is used to determine
464    /// whether sockets can share an address.
465    type ListenerSharingState: Clone + Debug;
466
467    /// The state stored for a connected socket that is used to determine
468    /// whether sockets can share an address.
469    type ConnSharingState: Clone + Debug;
470
471    /// The state stored for a listener socket address.
472    type ListenerAddrState: SocketMapAddrStateSpec<Id = Self::ListenerId, SharingState = Self::ListenerSharingState>
473        + Debug;
474
475    /// The state stored for a connected socket address.
476    type ConnAddrState: SocketMapAddrStateSpec<Id = Self::ConnId, SharingState = Self::ConnSharingState>
477        + Debug;
478}
479
480/// Error returned by implementations of [`SocketMapAddrStateSpec`] to indicate
481/// incompatible changes to a socket map.
482#[derive(Copy, Clone, Debug, Eq, PartialEq)]
483pub struct IncompatibleError;
484
485/// An inserter into a [`SocketMap`].
486pub trait Inserter<T> {
487    /// Inserts the provided item and consumes `self`.
488    ///
489    /// Inserts a single item and consumes the inserter (thus preventing
490    /// additional insertions).
491    fn insert(self, item: T);
492}
493
494impl<'a, T, E: Extend<T>> Inserter<T> for &'a mut E {
495    fn insert(self, item: T) {
496        self.extend([item])
497    }
498}
499
500impl<T> Inserter<T> for Never {
501    fn insert(self, _: T) {
502        match self {}
503    }
504}
505
506/// Describes an entry in a [`SocketMap`] for a listener or connection address.
507pub trait SocketMapAddrStateSpec {
508    /// The type of ID that can be present at the address.
509    type Id;
510
511    /// The sharing state for the address.
512    ///
513    /// This can be used to determine whether a socket can be inserted at the
514    /// address. Every socket has its own sharing state associated with it,
515    /// though the sharing state is not necessarily stored in the address
516    /// entry.
517    type SharingState;
518
519    /// The type of inserter returned by [`SocketMapAddrStateSpec::try_get_inserter`].
520    type Inserter<'a>: Inserter<Self::Id> + 'a
521    where
522        Self: 'a,
523        Self::Id: 'a;
524
525    /// Creates a new `Self` holding the provided socket with the given new
526    /// sharing state at the specified address.
527    fn new(new_sharing_state: &Self::SharingState, id: Self::Id) -> Self;
528
529    /// Looks up the ID in self, returning `true` if it is present.
530    fn contains_id(&self, id: &Self::Id) -> bool;
531
532    /// Enables insertion in `self` for a new socket with the provided sharing
533    /// state.
534    ///
535    /// If the new state is incompatible with the existing socket(s),
536    /// implementations of this function should return `Err(IncompatibleError)`.
537    /// If `Ok(x)` is returned, calling `x.insert(y)` will insert `y` into
538    /// `self`.
539    fn try_get_inserter<'a, 'b>(
540        &'b mut self,
541        new_sharing_state: &'a Self::SharingState,
542    ) -> Result<Self::Inserter<'b>, IncompatibleError>;
543
544    /// Returns `Ok` if an entry with the given sharing state could be added
545    /// to `self`.
546    ///
547    /// If this returns `Ok`, `try_get_dest` should succeed.
548    fn could_insert(&self, new_sharing_state: &Self::SharingState)
549        -> Result<(), IncompatibleError>;
550
551    /// Removes the given socket from the existing state.
552    ///
553    /// Implementations should assume that `id` is contained in `self`.
554    fn remove_by_id(&mut self, id: Self::Id) -> RemoveResult;
555}
556
557/// Provides behavior on updating the sharing state of a [`SocketMap`] entry.
558pub trait SocketMapAddrStateUpdateSharingSpec: SocketMapAddrStateSpec {
559    /// Attempts to update the sharing state of the address state with id `id`
560    /// to `new_sharing_state`.
561    fn try_update_sharing(
562        &mut self,
563        id: Self::Id,
564        new_sharing_state: &Self::SharingState,
565    ) -> Result<(), IncompatibleError>;
566}
567
568/// Provides conflict detection for a [`SocketMapStateSpec`].
569pub trait SocketMapConflictPolicy<
570    Addr,
571    SharingState,
572    I: Ip,
573    D: DeviceIdentifier,
574    A: SocketMapAddrSpec,
575>: SocketMapStateSpec
576{
577    /// Checks whether a new socket with the provided state can be inserted at
578    /// the given address in the existing socket map, returning an error
579    /// otherwise.
580    ///
581    /// Implementations of this function should check for any potential
582    /// conflicts that would arise when inserting a socket with state
583    /// `new_sharing_state` into a new or existing entry at `addr` in
584    /// `socketmap`.
585    fn check_insert_conflicts(
586        new_sharing_state: &SharingState,
587        addr: &Addr,
588        socketmap: &SocketMap<AddrVec<I, D, A>, Bound<Self>>,
589    ) -> Result<(), InsertError>;
590}
591
592/// Defines the policy for updating the sharing state of entries in the
593/// [`SocketMap`].
594pub trait SocketMapUpdateSharingPolicy<Addr, SharingState, I: Ip, D: DeviceIdentifier, A>:
595    SocketMapConflictPolicy<Addr, SharingState, I, D, A>
596where
597    A: SocketMapAddrSpec,
598{
599    /// Returns whether the entry `addr` in `socketmap` allows the sharing state
600    /// to transition from `old_sharing` to `new_sharing`.
601    fn allows_sharing_update(
602        socketmap: &SocketMap<AddrVec<I, D, A>, Bound<Self>>,
603        addr: &Addr,
604        old_sharing: &SharingState,
605        new_sharing: &SharingState,
606    ) -> Result<(), UpdateSharingError>;
607}
608
609/// A bound socket state that is either a listener or a connection.
610#[derive(Derivative)]
611#[derivative(Debug(bound = "S::ListenerAddrState: Debug, S::ConnAddrState: Debug"))]
612#[allow(missing_docs)]
613pub enum Bound<S: SocketMapStateSpec + ?Sized> {
614    Listen(S::ListenerAddrState),
615    Conn(S::ConnAddrState),
616}
617
618/// An "address vector" type that can hold any address in a [`SocketMap`].
619///
620/// This is a "vector" in the mathematical sense, in that it denotes an address
621/// in a space. Here, the space is the possible addresses to which a socket
622/// receiving IP packets can be bound.
623///
624/// `AddrVec`s are used as keys for the `SocketMap` type. Since an incoming
625/// packet can match more than one address, for each incoming packet there is a
626/// set of possible `AddrVec` keys whose entries (sockets) in a `SocketMap`
627/// might receive the packet.
628///
629/// This set of keys can be ordered by precedence as described in the
630/// documentation for [`AddrVecIter`]. Calling [`IterShadows::iter_shadows`] on
631/// an instance will produce the sequence of addresses it has precedence over.
632#[derive(Derivative)]
633#[derivative(
634    Debug(bound = "D: Debug"),
635    Clone(bound = "D: Clone"),
636    Eq(bound = "D: Eq"),
637    PartialEq(bound = "D: PartialEq"),
638    Hash(bound = "D: Hash")
639)]
640#[allow(missing_docs)]
641pub enum AddrVec<I: Ip, D, A: SocketMapAddrSpec + ?Sized> {
642    Listen(ListenerAddr<ListenerIpAddr<I::Addr, A::LocalIdentifier>, D>),
643    Conn(ConnAddr<ConnIpAddr<I::Addr, A::LocalIdentifier, A::RemoteIdentifier>, D>),
644}
645
646impl<I: Ip, D: DeviceIdentifier, A: SocketMapAddrSpec, S: SocketMapStateSpec + ?Sized>
647    Tagged<AddrVec<I, D, A>> for Bound<S>
648{
649    type Tag = S::AddrVecTag;
650    fn tag(&self, address: &AddrVec<I, D, A>) -> Self::Tag {
651        match (self, address) {
652            (Bound::Listen(l), AddrVec::Listen(addr)) => S::listener_tag(addr.info(), l),
653            (Bound::Conn(c), AddrVec::Conn(ConnAddr { device, ip: _ })) => {
654                S::connected_tag(device.is_some(), c)
655            }
656            (Bound::Listen(_), AddrVec::Conn(_)) => {
657                unreachable!("found listen state for conn addr")
658            }
659            (Bound::Conn(_), AddrVec::Listen(_)) => {
660                unreachable!("found conn state for listen addr")
661            }
662        }
663    }
664}
665
666impl<I: Ip, D: DeviceIdentifier, A: SocketMapAddrSpec> IterShadows for AddrVec<I, D, A> {
667    type IterShadows = AddrVecIter<I, D, A>;
668
669    fn iter_shadows(&self) -> Self::IterShadows {
670        let (socket_ip_addr, device) = match self.clone() {
671            AddrVec::Conn(ConnAddr { ip, device }) => (ip.into(), device),
672            AddrVec::Listen(ListenerAddr { ip, device }) => (ip.into(), device),
673        };
674        let mut iter = match device {
675            Some(device) => AddrVecIter::with_device(socket_ip_addr, device),
676            None => AddrVecIter::without_device(socket_ip_addr),
677        };
678        // Skip the first element, which is always `*self`.
679        assert_eq!(iter.next().as_ref(), Some(self));
680        iter
681    }
682}
683
684/// How a socket is bound on the system.
685#[derive(Copy, Clone, Debug, Eq, Hash, PartialEq)]
686#[allow(missing_docs)]
687pub enum SocketAddrType {
688    AnyListener,
689    SpecificListener,
690    Connected,
691}
692
693impl<'a, A: IpAddress, LI> From<&'a ListenerIpAddr<A, LI>> for SocketAddrType {
694    fn from(ListenerIpAddr { addr, identifier: _ }: &'a ListenerIpAddr<A, LI>) -> Self {
695        match addr {
696            Some(_) => SocketAddrType::SpecificListener,
697            None => SocketAddrType::AnyListener,
698        }
699    }
700}
701
702impl<'a, A: IpAddress, LI, RI> From<&'a ConnIpAddr<A, LI, RI>> for SocketAddrType {
703    fn from(_: &'a ConnIpAddr<A, LI, RI>) -> Self {
704        SocketAddrType::Connected
705    }
706}
707
708/// The result of attempting to remove a socket from a collection of sockets.
709pub enum RemoveResult {
710    /// The value was removed successfully.
711    Success,
712    /// The value is the last value in the collection so the entire collection
713    /// should be removed.
714    IsLast,
715}
716
717#[derive(Derivative)]
718#[derivative(Clone(bound = "S::ListenerId: Clone, S::ConnId: Clone"), Debug(bound = ""))]
719pub enum SocketId<S: SocketMapStateSpec> {
720    Listener(S::ListenerId),
721    Connection(S::ConnId),
722}
723
724/// A map from socket addresses to sockets.
725///
726/// The types of keys and IDs is determined by the [`SocketMapStateSpec`]
727/// parameter. Each listener and connected socket stores additional state.
728/// Listener and connected sockets are keyed independently, but share the same
729/// address vector space. Conflicts are detected on attempted insertion of new
730/// sockets.
731///
732/// Listener addresses map to listener-address-specific state, and likewise
733/// with connected addresses. Depending on protocol (determined by the
734/// `SocketMapStateSpec` protocol), these address states can hold one or more
735/// socket identifiers (e.g. UDP sockets with `SO_REUSEPORT` set can share an
736/// address).
737#[derive(Derivative)]
738#[derivative(Default(bound = ""))]
739pub struct BoundSocketMap<I: Ip, D: DeviceIdentifier, A: SocketMapAddrSpec, S: SocketMapStateSpec> {
740    addr_to_state: SocketMap<AddrVec<I, D, A>, Bound<S>>,
741}
742
743impl<I: Ip, D: DeviceIdentifier, A: SocketMapAddrSpec, S: SocketMapStateSpec>
744    BoundSocketMap<I, D, A, S>
745{
746    /// Returns the number of entries in the map.
747    pub fn len(&self) -> usize {
748        self.addr_to_state.len()
749    }
750}
751
752/// Uninstantiable tag type for denoting listening sockets.
753pub enum Listener {}
754/// Uninstantiable tag type for denoting connected sockets.
755pub enum Connection {}
756
757/// View struct over one type of sockets in a [`BoundSocketMap`].
758pub struct Sockets<AddrToStateMap, SocketType>(AddrToStateMap, PhantomData<SocketType>);
759
760impl<
761        'a,
762        I: Ip,
763        D: DeviceIdentifier,
764        SocketType: ConvertSocketMapState<I, D, A, S>,
765        A: SocketMapAddrSpec,
766        S: SocketMapStateSpec,
767    > Sockets<&'a SocketMap<AddrVec<I, D, A>, Bound<S>>, SocketType>
768where
769    S: SocketMapConflictPolicy<SocketType::Addr, SocketType::SharingState, I, D, A>,
770{
771    /// Returns the state at an address, if there is any.
772    pub fn get_by_addr(self, addr: &SocketType::Addr) -> Option<&'a SocketType::AddrState> {
773        let Self(addr_to_state, _marker) = self;
774        addr_to_state.get(&SocketType::to_addr_vec(addr)).map(|state| {
775            SocketType::from_bound_ref(state)
776                .unwrap_or_else(|| unreachable!("found {:?} for address {:?}", state, addr))
777        })
778    }
779
780    /// Returns `Ok(())` if a socket could be inserted, otherwise an error.
781    ///
782    /// Goes through a dry run of inserting a socket at the given address and
783    /// with the given sharing state, returning `Ok(())` if the insertion would
784    /// succeed, otherwise the error that would be returned.
785    pub fn could_insert(
786        self,
787        addr: &SocketType::Addr,
788        sharing: &SocketType::SharingState,
789    ) -> Result<(), InsertError> {
790        let Self(addr_to_state, _) = self;
791        match self.get_by_addr(addr) {
792            Some(state) => {
793                state.could_insert(sharing).map_err(|IncompatibleError| InsertError::Exists)
794            }
795            None => S::check_insert_conflicts(&sharing, &addr, &addr_to_state),
796        }
797    }
798}
799
800/// A borrowed state entry in a [`SocketMap`].
801#[derive(Derivative)]
802#[derivative(Debug(bound = ""))]
803pub struct SocketStateEntry<
804    'a,
805    I: Ip,
806    D: DeviceIdentifier,
807    A: SocketMapAddrSpec,
808    S: SocketMapStateSpec,
809    SocketType,
810> {
811    id: SocketId<S>,
812    addr_entry: SocketMapOccupiedEntry<'a, AddrVec<I, D, A>, Bound<S>>,
813    _marker: PhantomData<SocketType>,
814}
815
816impl<
817        'a,
818        I: Ip,
819        D: DeviceIdentifier,
820        SocketType: ConvertSocketMapState<I, D, A, S>,
821        A: SocketMapAddrSpec,
822        S: SocketMapStateSpec
823            + SocketMapConflictPolicy<SocketType::Addr, SocketType::SharingState, I, D, A>,
824    > Sockets<&'a mut SocketMap<AddrVec<I, D, A>, Bound<S>>, SocketType>
825where
826    SocketType::SharingState: Clone,
827    SocketType::Id: Clone,
828{
829    /// Attempts to insert a new entry into the [`SocketMap`] backing this
830    /// `Sockets`.
831    pub fn try_insert(
832        self,
833        socket_addr: SocketType::Addr,
834        tag_state: SocketType::SharingState,
835        id: SocketType::Id,
836    ) -> Result<SocketStateEntry<'a, I, D, A, S, SocketType>, (InsertError, SocketType::SharingState)>
837    {
838        self.try_insert_with(socket_addr, tag_state, |_addr, _sharing| (id, ()))
839            .map(|(entry, ())| entry)
840    }
841
842    /// Like [`Sockets::try_insert`] but calls `make_id` to create a socket ID
843    /// before inserting into the map.
844    ///
845    /// `make_id` returns type `R` that is returned to the caller on success.
846    pub fn try_insert_with<R>(
847        self,
848        socket_addr: SocketType::Addr,
849        tag_state: SocketType::SharingState,
850        make_id: impl FnOnce(SocketType::Addr, SocketType::SharingState) -> (SocketType::Id, R),
851    ) -> Result<
852        (SocketStateEntry<'a, I, D, A, S, SocketType>, R),
853        (InsertError, SocketType::SharingState),
854    > {
855        let Self(addr_to_state, _) = self;
856        match S::check_insert_conflicts(&tag_state, &socket_addr, &addr_to_state) {
857            Err(e) => return Err((e, tag_state)),
858            Ok(()) => (),
859        };
860
861        let addr = SocketType::to_addr_vec(&socket_addr);
862
863        match addr_to_state.entry(addr) {
864            Entry::Occupied(mut o) => {
865                let (id, ret) = o.map_mut(|bound| {
866                    let bound = match SocketType::from_bound_mut(bound) {
867                        Some(bound) => bound,
868                        None => unreachable!("found {:?} for address {:?}", bound, socket_addr),
869                    };
870                    match <SocketType::AddrState as SocketMapAddrStateSpec>::try_get_inserter(
871                        bound, &tag_state,
872                    ) {
873                        Ok(v) => {
874                            let (id, ret) = make_id(socket_addr, tag_state);
875                            v.insert(id.clone());
876                            Ok((SocketType::to_socket_id(id), ret))
877                        }
878                        Err(IncompatibleError) => Err((InsertError::Exists, tag_state)),
879                    }
880                })?;
881                Ok((SocketStateEntry { id, addr_entry: o, _marker: Default::default() }, ret))
882            }
883            Entry::Vacant(v) => {
884                let (id, ret) = make_id(socket_addr, tag_state.clone());
885                let addr_entry = v.insert(SocketType::to_bound(SocketType::AddrState::new(
886                    &tag_state,
887                    id.clone(),
888                )));
889                let id = SocketType::to_socket_id(id);
890                Ok((SocketStateEntry { id, addr_entry, _marker: Default::default() }, ret))
891            }
892        }
893    }
894
895    /// Returns a borrowed entry at `id` and `addr`.
896    pub fn entry(
897        self,
898        id: &SocketType::Id,
899        addr: &SocketType::Addr,
900    ) -> Option<SocketStateEntry<'a, I, D, A, S, SocketType>> {
901        let Self(addr_to_state, _) = self;
902        let addr_entry = match addr_to_state.entry(SocketType::to_addr_vec(addr)) {
903            Entry::Vacant(_) => return None,
904            Entry::Occupied(o) => o,
905        };
906        let state = SocketType::from_bound_ref(addr_entry.get())?;
907
908        state.contains_id(id).then_some(SocketStateEntry {
909            id: SocketType::to_socket_id(id.clone()),
910            addr_entry,
911            _marker: PhantomData::default(),
912        })
913    }
914
915    /// Removes the entry with `id` and `addr`.
916    pub fn remove(self, id: &SocketType::Id, addr: &SocketType::Addr) -> Result<(), NotFoundError> {
917        self.entry(id, addr)
918            .map(|entry| {
919                entry.remove();
920            })
921            .ok_or(NotFoundError)
922    }
923}
924
925/// The error returned when updating the sharing state for a [`SocketMap`] entry
926/// fails.
927#[derive(Debug)]
928pub struct UpdateSharingError;
929
930impl<
931        'a,
932        I: Ip,
933        D: DeviceIdentifier,
934        SocketType: ConvertSocketMapState<I, D, A, S>,
935        A: SocketMapAddrSpec,
936        S: SocketMapStateSpec,
937    > SocketStateEntry<'a, I, D, A, S, SocketType>
938where
939    SocketType::Id: Clone,
940{
941    /// Returns this entry's address.
942    pub fn get_addr(&self) -> &SocketType::Addr {
943        let Self { id: _, addr_entry, _marker } = self;
944        SocketType::from_addr_vec_ref(addr_entry.key())
945    }
946
947    /// Returns this entry's identifier.
948    pub fn id(&self) -> &SocketType::Id {
949        let Self { id, addr_entry: _, _marker } = self;
950        SocketType::from_socket_id_ref(id)
951    }
952
953    /// Attempts to update the address for this entry.
954    pub fn try_update_addr(self, new_addr: SocketType::Addr) -> Result<Self, (ExistsError, Self)> {
955        let Self { id, addr_entry, _marker } = self;
956
957        let new_addrvec = SocketType::to_addr_vec(&new_addr);
958        let old_addr = addr_entry.key().clone();
959        let (addr_state, addr_to_state) = addr_entry.remove_from_map();
960        let addr_to_state = match addr_to_state.entry(new_addrvec) {
961            Entry::Occupied(o) => o.into_map(),
962            Entry::Vacant(v) => {
963                if v.descendant_counts().len() != 0 {
964                    v.into_map()
965                } else {
966                    let new_addr_entry = v.insert(addr_state);
967                    return Ok(SocketStateEntry { id, addr_entry: new_addr_entry, _marker });
968                }
969            }
970        };
971        let to_restore = addr_state;
972        // Restore the old state before returning an error.
973        let addr_entry = match addr_to_state.entry(old_addr) {
974            Entry::Occupied(_) => unreachable!("just-removed-from entry is occupied"),
975            Entry::Vacant(v) => v.insert(to_restore),
976        };
977        return Err((ExistsError, SocketStateEntry { id, addr_entry, _marker }));
978    }
979
980    /// Removes this entry from the map.
981    pub fn remove(self) {
982        let Self { id, mut addr_entry, _marker } = self;
983        let addr = addr_entry.key().clone();
984        match addr_entry.map_mut(|value| {
985            let value = match SocketType::from_bound_mut(value) {
986                Some(value) => value,
987                None => unreachable!("found {:?} for address {:?}", value, addr),
988            };
989            value.remove_by_id(SocketType::from_socket_id_ref(&id).clone())
990        }) {
991            RemoveResult::Success => (),
992            RemoveResult::IsLast => {
993                let _: Bound<S> = addr_entry.remove();
994            }
995        }
996    }
997
998    /// Attempts to update the sharing state for this entry.
999    pub fn try_update_sharing(
1000        &mut self,
1001        old_sharing_state: &SocketType::SharingState,
1002        new_sharing_state: SocketType::SharingState,
1003    ) -> Result<(), UpdateSharingError>
1004    where
1005        SocketType::AddrState: SocketMapAddrStateUpdateSharingSpec,
1006        S: SocketMapUpdateSharingPolicy<SocketType::Addr, SocketType::SharingState, I, D, A>,
1007    {
1008        let Self { id, addr_entry, _marker } = self;
1009        let addr = SocketType::from_addr_vec_ref(addr_entry.key());
1010
1011        S::allows_sharing_update(
1012            addr_entry.get_map(),
1013            addr,
1014            old_sharing_state,
1015            &new_sharing_state,
1016        )?;
1017
1018        addr_entry
1019            .map_mut(|value| {
1020                let value = match SocketType::from_bound_mut(value) {
1021                    Some(value) => value,
1022                    // We shouldn't ever be storing listener state in a bound
1023                    // address, or bound state in a listener address. Doing so means
1024                    // we've got a serious bug.
1025                    None => unreachable!("found invalid state {:?}", value),
1026                };
1027
1028                value.try_update_sharing(
1029                    SocketType::from_socket_id_ref(id).clone(),
1030                    &new_sharing_state,
1031                )
1032            })
1033            .map_err(|IncompatibleError| UpdateSharingError)
1034    }
1035}
1036
1037impl<I: Ip, D: DeviceIdentifier, A: SocketMapAddrSpec, S> BoundSocketMap<I, D, A, S>
1038where
1039    AddrVec<I, D, A>: IterShadows,
1040    S: SocketMapStateSpec,
1041{
1042    /// Returns an iterator over the listeners on the socket map.
1043    pub fn listeners(&self) -> Sockets<&SocketMap<AddrVec<I, D, A>, Bound<S>>, Listener>
1044    where
1045        S: SocketMapConflictPolicy<
1046            ListenerAddr<ListenerIpAddr<I::Addr, A::LocalIdentifier>, D>,
1047            <S as SocketMapStateSpec>::ListenerSharingState,
1048            I,
1049            D,
1050            A,
1051        >,
1052        S::ListenerAddrState:
1053            SocketMapAddrStateSpec<Id = S::ListenerId, SharingState = S::ListenerSharingState>,
1054    {
1055        let Self { addr_to_state } = self;
1056        Sockets(addr_to_state, Default::default())
1057    }
1058
1059    /// Returns a mutable iterator over the listeners on the socket map.
1060    pub fn listeners_mut(&mut self) -> Sockets<&mut SocketMap<AddrVec<I, D, A>, Bound<S>>, Listener>
1061    where
1062        S: SocketMapConflictPolicy<
1063            ListenerAddr<ListenerIpAddr<I::Addr, A::LocalIdentifier>, D>,
1064            <S as SocketMapStateSpec>::ListenerSharingState,
1065            I,
1066            D,
1067            A,
1068        >,
1069        S::ListenerAddrState:
1070            SocketMapAddrStateSpec<Id = S::ListenerId, SharingState = S::ListenerSharingState>,
1071    {
1072        let Self { addr_to_state } = self;
1073        Sockets(addr_to_state, Default::default())
1074    }
1075
1076    /// Returns an iterator over the connections on the socket map.
1077    pub fn conns(&self) -> Sockets<&SocketMap<AddrVec<I, D, A>, Bound<S>>, Connection>
1078    where
1079        S: SocketMapConflictPolicy<
1080            ConnAddr<ConnIpAddr<I::Addr, A::LocalIdentifier, A::RemoteIdentifier>, D>,
1081            <S as SocketMapStateSpec>::ConnSharingState,
1082            I,
1083            D,
1084            A,
1085        >,
1086        S::ConnAddrState:
1087            SocketMapAddrStateSpec<Id = S::ConnId, SharingState = S::ConnSharingState>,
1088    {
1089        let Self { addr_to_state } = self;
1090        Sockets(addr_to_state, Default::default())
1091    }
1092
1093    /// Returns a mutable iterator over the connections on the socket map.
1094    pub fn conns_mut(&mut self) -> Sockets<&mut SocketMap<AddrVec<I, D, A>, Bound<S>>, Connection>
1095    where
1096        S: SocketMapConflictPolicy<
1097            ConnAddr<ConnIpAddr<I::Addr, A::LocalIdentifier, A::RemoteIdentifier>, D>,
1098            <S as SocketMapStateSpec>::ConnSharingState,
1099            I,
1100            D,
1101            A,
1102        >,
1103        S::ConnAddrState:
1104            SocketMapAddrStateSpec<Id = S::ConnId, SharingState = S::ConnSharingState>,
1105    {
1106        let Self { addr_to_state } = self;
1107        Sockets(addr_to_state, Default::default())
1108    }
1109
1110    #[cfg(test)]
1111    pub(crate) fn iter_addrs(&self) -> impl Iterator<Item = &AddrVec<I, D, A>> {
1112        let Self { addr_to_state } = self;
1113        addr_to_state.iter().map(|(a, _v): (_, &Bound<S>)| a)
1114    }
1115
1116    /// Gets the number of shadower entries for `addr`.
1117    pub fn get_shadower_counts(&self, addr: &AddrVec<I, D, A>) -> usize {
1118        let Self { addr_to_state } = self;
1119        addr_to_state.descendant_counts(&addr).map(|(_sharing, size)| size.get()).sum()
1120    }
1121}
1122
1123/// The type returned by [`BoundSocketMap::iter_receivers`].
1124pub enum FoundSockets<A, It> {
1125    /// A single recipient was found for the address.
1126    Single(A),
1127    /// Indicates the looked-up address was multicast, and holds an iterator of
1128    /// the found receivers.
1129    Multicast(It),
1130}
1131
1132/// A borrowed entry in a [`BoundSocketMap`].
1133#[allow(missing_docs)]
1134#[derive(Debug)]
1135pub enum AddrEntry<'a, I: Ip, D, A: SocketMapAddrSpec, S: SocketMapStateSpec> {
1136    Listen(&'a S::ListenerAddrState, ListenerAddr<ListenerIpAddr<I::Addr, A::LocalIdentifier>, D>),
1137    Conn(
1138        &'a S::ConnAddrState,
1139        ConnAddr<ConnIpAddr<I::Addr, A::LocalIdentifier, A::RemoteIdentifier>, D>,
1140    ),
1141}
1142
1143impl<I, D, A, S> BoundSocketMap<I, D, A, S>
1144where
1145    I: BroadcastIpExt<Addr: MulticastAddress>,
1146    D: DeviceIdentifier,
1147    A: SocketMapAddrSpec,
1148    S: SocketMapStateSpec
1149        + SocketMapConflictPolicy<
1150            ListenerAddr<ListenerIpAddr<I::Addr, A::LocalIdentifier>, D>,
1151            <S as SocketMapStateSpec>::ListenerSharingState,
1152            I,
1153            D,
1154            A,
1155        > + SocketMapConflictPolicy<
1156            ConnAddr<ConnIpAddr<I::Addr, A::LocalIdentifier, A::RemoteIdentifier>, D>,
1157            <S as SocketMapStateSpec>::ConnSharingState,
1158            I,
1159            D,
1160            A,
1161        >,
1162{
1163    /// Finds the socket(s) that should receive an incoming packet.
1164    ///
1165    /// Uses the provided addresses and receiving device to look up sockets that
1166    /// should receive a matching incoming packet. Returns `None` if no sockets
1167    /// were found, or the results of the lookup.
1168    pub fn iter_receivers(
1169        &self,
1170        (src_ip, src_port): (Option<SocketIpAddr<I::Addr>>, Option<A::RemoteIdentifier>),
1171        (dst_ip, dst_port): (SocketIpAddr<I::Addr>, A::LocalIdentifier),
1172        device: D,
1173        broadcast: Option<I::BroadcastMarker>,
1174    ) -> Option<
1175        FoundSockets<
1176            AddrEntry<'_, I, D, A, S>,
1177            impl Iterator<Item = AddrEntry<'_, I, D, A, S>> + '_,
1178        >,
1179    > {
1180        let mut matching_entries = AddrVecIter::with_device(
1181            match (src_ip, src_port) {
1182                (Some(specified_src_ip), Some(src_port)) => {
1183                    ConnIpAddr { local: (dst_ip, dst_port), remote: (specified_src_ip, src_port) }
1184                        .into()
1185                }
1186                _ => ListenerIpAddr { addr: Some(dst_ip), identifier: dst_port }.into(),
1187            },
1188            device,
1189        )
1190        .filter_map(move |addr: AddrVec<I, D, A>| match addr {
1191            AddrVec::Listen(l) => {
1192                self.listeners().get_by_addr(&l).map(|state| AddrEntry::Listen(state, l))
1193            }
1194            AddrVec::Conn(c) => self.conns().get_by_addr(&c).map(|state| AddrEntry::Conn(state, c)),
1195        });
1196
1197        if broadcast.is_some() || dst_ip.addr().is_multicast() {
1198            Some(FoundSockets::Multicast(matching_entries))
1199        } else {
1200            let single_entry: Option<_> = matching_entries.next();
1201            single_entry.map(FoundSockets::Single)
1202        }
1203    }
1204}
1205
1206/// Errors observed by [`SocketMapConflictPolicy`].
1207#[derive(Debug, Eq, PartialEq)]
1208pub enum InsertError {
1209    /// A shadow address exists for the entry.
1210    ShadowAddrExists,
1211    /// Entry already exists.
1212    Exists,
1213    /// A shadower exists for the entry.
1214    ShadowerExists,
1215    /// An indirect conflict was detected.
1216    IndirectConflict,
1217}
1218
1219/// Helper trait for converting between [`AddrVec`] and [`Bound`] and their
1220/// variants.
1221pub trait ConvertSocketMapState<I: Ip, D, A: SocketMapAddrSpec, S: SocketMapStateSpec> {
1222    type Id;
1223    type SharingState;
1224    type Addr: Debug;
1225    type AddrState: SocketMapAddrStateSpec<Id = Self::Id, SharingState = Self::SharingState>;
1226
1227    fn to_addr_vec(addr: &Self::Addr) -> AddrVec<I, D, A>;
1228    fn from_addr_vec_ref(addr: &AddrVec<I, D, A>) -> &Self::Addr;
1229    fn from_bound_ref(bound: &Bound<S>) -> Option<&Self::AddrState>;
1230    fn from_bound_mut(bound: &mut Bound<S>) -> Option<&mut Self::AddrState>;
1231    fn to_bound(state: Self::AddrState) -> Bound<S>;
1232    fn to_socket_id(id: Self::Id) -> SocketId<S>;
1233    fn from_socket_id_ref(id: &SocketId<S>) -> &Self::Id;
1234}
1235
1236impl<I: Ip, D: DeviceIdentifier, A: SocketMapAddrSpec, S: SocketMapStateSpec>
1237    ConvertSocketMapState<I, D, A, S> for Listener
1238{
1239    type Id = S::ListenerId;
1240    type SharingState = S::ListenerSharingState;
1241    type Addr = ListenerAddr<ListenerIpAddr<I::Addr, A::LocalIdentifier>, D>;
1242    type AddrState = S::ListenerAddrState;
1243    fn to_addr_vec(addr: &Self::Addr) -> AddrVec<I, D, A> {
1244        AddrVec::Listen(addr.clone())
1245    }
1246
1247    fn from_addr_vec_ref(addr: &AddrVec<I, D, A>) -> &Self::Addr {
1248        match addr {
1249            AddrVec::Listen(l) => l,
1250            AddrVec::Conn(c) => unreachable!("conn addr for listener: {c:?}"),
1251        }
1252    }
1253
1254    fn from_bound_ref(bound: &Bound<S>) -> Option<&S::ListenerAddrState> {
1255        match bound {
1256            Bound::Listen(l) => Some(l),
1257            Bound::Conn(_c) => None,
1258        }
1259    }
1260
1261    fn from_bound_mut(bound: &mut Bound<S>) -> Option<&mut S::ListenerAddrState> {
1262        match bound {
1263            Bound::Listen(l) => Some(l),
1264            Bound::Conn(_c) => None,
1265        }
1266    }
1267
1268    fn to_bound(state: S::ListenerAddrState) -> Bound<S> {
1269        Bound::Listen(state)
1270    }
1271    fn from_socket_id_ref(id: &SocketId<S>) -> &Self::Id {
1272        match id {
1273            SocketId::Listener(id) => id,
1274            SocketId::Connection(_) => unreachable!("connection ID for listener"),
1275        }
1276    }
1277    fn to_socket_id(id: Self::Id) -> SocketId<S> {
1278        SocketId::Listener(id)
1279    }
1280}
1281
1282impl<I: Ip, D: DeviceIdentifier, A: SocketMapAddrSpec, S: SocketMapStateSpec>
1283    ConvertSocketMapState<I, D, A, S> for Connection
1284{
1285    type Id = S::ConnId;
1286    type SharingState = S::ConnSharingState;
1287    type Addr = ConnAddr<ConnIpAddr<I::Addr, A::LocalIdentifier, A::RemoteIdentifier>, D>;
1288    type AddrState = S::ConnAddrState;
1289    fn to_addr_vec(addr: &Self::Addr) -> AddrVec<I, D, A> {
1290        AddrVec::Conn(addr.clone())
1291    }
1292
1293    fn from_addr_vec_ref(addr: &AddrVec<I, D, A>) -> &Self::Addr {
1294        match addr {
1295            AddrVec::Conn(c) => c,
1296            AddrVec::Listen(l) => unreachable!("listener addr for conn: {l:?}"),
1297        }
1298    }
1299
1300    fn from_bound_ref(bound: &Bound<S>) -> Option<&S::ConnAddrState> {
1301        match bound {
1302            Bound::Listen(_l) => None,
1303            Bound::Conn(c) => Some(c),
1304        }
1305    }
1306
1307    fn from_bound_mut(bound: &mut Bound<S>) -> Option<&mut S::ConnAddrState> {
1308        match bound {
1309            Bound::Listen(_l) => None,
1310            Bound::Conn(c) => Some(c),
1311        }
1312    }
1313
1314    fn to_bound(state: S::ConnAddrState) -> Bound<S> {
1315        Bound::Conn(state)
1316    }
1317
1318    fn from_socket_id_ref(id: &SocketId<S>) -> &Self::Id {
1319        match id {
1320            SocketId::Connection(id) => id,
1321            SocketId::Listener(_) => unreachable!("listener ID for connection"),
1322        }
1323    }
1324    fn to_socket_id(id: Self::Id) -> SocketId<S> {
1325        SocketId::Connection(id)
1326    }
1327}
1328
1329#[cfg(test)]
1330mod tests {
1331    use alloc::collections::HashSet;
1332    use alloc::vec;
1333    use alloc::vec::Vec;
1334
1335    use assert_matches::assert_matches;
1336    use net_declare::{net_ip_v4, net_ip_v6};
1337    use net_types::ip::{Ipv4Addr, Ipv6, Ipv6Addr};
1338    use test_case::test_case;
1339
1340    use crate::device::testutil::{FakeDeviceId, FakeWeakDeviceId};
1341    use crate::testutil::set_logger_for_test;
1342
1343    use super::*;
1344
1345    #[test_case(net_ip_v4!("8.8.8.8"))]
1346    #[test_case(net_ip_v4!("127.0.0.1"))]
1347    #[test_case(net_ip_v4!("127.0.8.9"))]
1348    #[test_case(net_ip_v4!("224.1.2.3"))]
1349    fn must_never_have_zone_ipv4(addr: Ipv4Addr) {
1350        // No IPv4 addresses are allowed to have a zone.
1351        let addr = SpecifiedAddr::new(addr).unwrap();
1352        assert_eq!(addr.must_have_zone(), false);
1353    }
1354
1355    #[test_case(net_ip_v6!("1::2:3"), false)]
1356    #[test_case(net_ip_v6!("::1"), false; "localhost")]
1357    #[test_case(net_ip_v6!("1::"), false)]
1358    #[test_case(net_ip_v6!("ff03:1:2:3::1"), false)]
1359    #[test_case(net_ip_v6!("ff02:1:2:3::1"), true)]
1360    #[test_case(Ipv6::ALL_NODES_LINK_LOCAL_MULTICAST_ADDRESS.get(), true)]
1361    #[test_case(net_ip_v6!("fe80::1"), true)]
1362    fn must_have_zone_ipv6(addr: Ipv6Addr, must_have: bool) {
1363        // Only link-local unicast and multicast addresses are allowed to have
1364        // zones.
1365        let addr = SpecifiedAddr::new(addr).unwrap();
1366        assert_eq!(addr.must_have_zone(), must_have);
1367    }
1368
1369    #[test]
1370    fn try_into_null_zoned_ipv6() {
1371        assert_eq!(Ipv6::LOOPBACK_ADDRESS.try_into_null_zoned(), None);
1372        let zoned = Ipv6::ALL_NODES_LINK_LOCAL_MULTICAST_ADDRESS.into_specified();
1373        const ZONE: u32 = 5;
1374        assert_eq!(
1375            zoned.try_into_null_zoned().map(|a| a.map_zone(|()| ZONE)),
1376            Some(AddrAndZone::new(zoned, ZONE).unwrap())
1377        );
1378    }
1379
1380    enum FakeSpec {}
1381
1382    #[derive(Copy, Clone, Eq, PartialEq, Debug, Hash)]
1383    struct Listener(usize);
1384
1385    #[derive(PartialEq, Eq, Debug)]
1386    struct Multiple<T>(char, Vec<T>);
1387
1388    impl<T> Multiple<T> {
1389        fn tag(&self) -> char {
1390            let Multiple(c, _) = self;
1391            *c
1392        }
1393    }
1394
1395    #[derive(Copy, Clone, Eq, PartialEq, Debug, Hash)]
1396    struct Conn(usize);
1397
1398    enum FakeAddrSpec {}
1399
1400    impl SocketMapAddrSpec for FakeAddrSpec {
1401        type LocalIdentifier = NonZeroU16;
1402        type RemoteIdentifier = ();
1403    }
1404
1405    impl SocketMapStateSpec for FakeSpec {
1406        type AddrVecTag = char;
1407
1408        type ListenerId = Listener;
1409        type ConnId = Conn;
1410
1411        type ListenerSharingState = char;
1412        type ConnSharingState = char;
1413
1414        type ListenerAddrState = Multiple<Listener>;
1415        type ConnAddrState = Multiple<Conn>;
1416
1417        fn listener_tag(_: ListenerAddrInfo, state: &Self::ListenerAddrState) -> Self::AddrVecTag {
1418            state.tag()
1419        }
1420
1421        fn connected_tag(_has_device: bool, state: &Self::ConnAddrState) -> Self::AddrVecTag {
1422            state.tag()
1423        }
1424    }
1425
1426    type FakeBoundSocketMap =
1427        BoundSocketMap<Ipv4, FakeWeakDeviceId<FakeDeviceId>, FakeAddrSpec, FakeSpec>;
1428
1429    /// Generator for unique socket IDs that don't have any state.
1430    ///
1431    /// Calling [`FakeSocketIdGen::next`] returns a unique ID.
1432    #[derive(Default)]
1433    struct FakeSocketIdGen {
1434        next_id: usize,
1435    }
1436
1437    impl FakeSocketIdGen {
1438        fn next(&mut self) -> usize {
1439            let next_next_id = self.next_id + 1;
1440            core::mem::replace(&mut self.next_id, next_next_id)
1441        }
1442    }
1443
1444    impl<I: Eq> SocketMapAddrStateSpec for Multiple<I> {
1445        type Id = I;
1446        type SharingState = char;
1447        type Inserter<'a>
1448            = &'a mut Vec<I>
1449        where
1450            I: 'a;
1451
1452        fn new(new_sharing_state: &char, id: I) -> Self {
1453            Self(*new_sharing_state, vec![id])
1454        }
1455
1456        fn contains_id(&self, id: &Self::Id) -> bool {
1457            self.1.contains(id)
1458        }
1459
1460        fn try_get_inserter<'a, 'b>(
1461            &'b mut self,
1462            new_state: &'a char,
1463        ) -> Result<Self::Inserter<'b>, IncompatibleError> {
1464            let Self(c, v) = self;
1465            (new_state == c).then_some(v).ok_or(IncompatibleError)
1466        }
1467
1468        fn could_insert(
1469            &self,
1470            new_sharing_state: &Self::SharingState,
1471        ) -> Result<(), IncompatibleError> {
1472            let Self(c, _) = self;
1473            (new_sharing_state == c).then_some(()).ok_or(IncompatibleError)
1474        }
1475
1476        fn remove_by_id(&mut self, id: I) -> RemoveResult {
1477            let Self(_, v) = self;
1478            let index = v.iter().position(|i| i == &id).expect("did not find id");
1479            let _: I = v.swap_remove(index);
1480            if v.is_empty() {
1481                RemoveResult::IsLast
1482            } else {
1483                RemoveResult::Success
1484            }
1485        }
1486    }
1487
1488    impl<A: Into<AddrVec<Ipv4, FakeWeakDeviceId<FakeDeviceId>, FakeAddrSpec>> + Clone>
1489        SocketMapConflictPolicy<A, char, Ipv4, FakeWeakDeviceId<FakeDeviceId>, FakeAddrSpec>
1490        for FakeSpec
1491    {
1492        fn check_insert_conflicts(
1493            new_state: &char,
1494            addr: &A,
1495            socketmap: &SocketMap<
1496                AddrVec<Ipv4, FakeWeakDeviceId<FakeDeviceId>, FakeAddrSpec>,
1497                Bound<FakeSpec>,
1498            >,
1499        ) -> Result<(), InsertError> {
1500            let dest = addr.clone().into();
1501            if dest.iter_shadows().any(|a| socketmap.get(&a).is_some()) {
1502                return Err(InsertError::ShadowAddrExists);
1503            }
1504            match socketmap.get(&dest) {
1505                Some(Bound::Listen(Multiple(c, _))) | Some(Bound::Conn(Multiple(c, _))) => {
1506                    // Require that all sockets inserted in a `Multiple` entry
1507                    // have the same sharing state.
1508                    if c != new_state {
1509                        return Err(InsertError::Exists);
1510                    }
1511                }
1512                None => (),
1513            }
1514            if socketmap.descendant_counts(&dest).len() != 0 {
1515                Err(InsertError::ShadowerExists)
1516            } else {
1517                Ok(())
1518            }
1519        }
1520    }
1521
1522    impl<I: Eq> SocketMapAddrStateUpdateSharingSpec for Multiple<I> {
1523        fn try_update_sharing(
1524            &mut self,
1525            id: Self::Id,
1526            new_sharing_state: &Self::SharingState,
1527        ) -> Result<(), IncompatibleError> {
1528            let Self(sharing, v) = self;
1529            if new_sharing_state == sharing {
1530                return Ok(());
1531            }
1532
1533            // Preserve the invariant that all sockets inserted in a `Multiple`
1534            // entry have the same sharing state. That means we can't change
1535            // the sharing state of all the sockets at the address unless there
1536            // is exactly one!
1537            if v.len() != 1 {
1538                return Err(IncompatibleError);
1539            }
1540            assert!(v.contains(&id));
1541            *sharing = *new_sharing_state;
1542            Ok(())
1543        }
1544    }
1545
1546    impl<A: Into<AddrVec<Ipv4, FakeWeakDeviceId<FakeDeviceId>, FakeAddrSpec>> + Clone>
1547        SocketMapUpdateSharingPolicy<A, char, Ipv4, FakeWeakDeviceId<FakeDeviceId>, FakeAddrSpec>
1548        for FakeSpec
1549    {
1550        fn allows_sharing_update(
1551            _socketmap: &SocketMap<
1552                AddrVec<Ipv4, FakeWeakDeviceId<FakeDeviceId>, FakeAddrSpec>,
1553                Bound<Self>,
1554            >,
1555            _addr: &A,
1556            _old_sharing: &char,
1557            _new_sharing_state: &char,
1558        ) -> Result<(), UpdateSharingError> {
1559            Ok(())
1560        }
1561    }
1562
1563    const LISTENER_ADDR: ListenerAddr<
1564        ListenerIpAddr<Ipv4Addr, NonZeroU16>,
1565        FakeWeakDeviceId<FakeDeviceId>,
1566    > = ListenerAddr {
1567        ip: ListenerIpAddr {
1568            addr: Some(unsafe { SocketIpAddr::new_unchecked(net_ip_v4!("1.2.3.4")) }),
1569            identifier: NonZeroU16::new(1).unwrap(),
1570        },
1571        device: None,
1572    };
1573
1574    const CONN_ADDR: ConnAddr<
1575        ConnIpAddr<Ipv4Addr, NonZeroU16, ()>,
1576        FakeWeakDeviceId<FakeDeviceId>,
1577    > = ConnAddr {
1578        ip: ConnIpAddr {
1579            local: (
1580                unsafe { SocketIpAddr::new_unchecked(net_ip_v4!("5.6.7.8")) },
1581                NonZeroU16::new(1).unwrap(),
1582            ),
1583            remote: unsafe { (SocketIpAddr::new_unchecked(net_ip_v4!("8.7.6.5")), ()) },
1584        },
1585        device: None,
1586    };
1587
1588    #[test]
1589    fn bound_insert_get_remove_listener() {
1590        set_logger_for_test();
1591        let mut bound = FakeBoundSocketMap::default();
1592        let mut fake_id_gen = FakeSocketIdGen::default();
1593
1594        let addr = LISTENER_ADDR;
1595
1596        let id = {
1597            let entry =
1598                bound.listeners_mut().try_insert(addr, 'v', Listener(fake_id_gen.next())).unwrap();
1599            assert_eq!(entry.get_addr(), &addr);
1600            entry.id().clone()
1601        };
1602
1603        assert_eq!(bound.listeners().get_by_addr(&addr), Some(&Multiple('v', vec![id])));
1604
1605        assert_eq!(bound.listeners_mut().remove(&id, &addr), Ok(()));
1606        assert_eq!(bound.listeners().get_by_addr(&addr), None);
1607    }
1608
1609    #[test]
1610    fn bound_insert_get_remove_conn() {
1611        set_logger_for_test();
1612        let mut bound = FakeBoundSocketMap::default();
1613        let mut fake_id_gen = FakeSocketIdGen::default();
1614
1615        let addr = CONN_ADDR;
1616
1617        let id = {
1618            let entry = bound.conns_mut().try_insert(addr, 'v', Conn(fake_id_gen.next())).unwrap();
1619            assert_eq!(entry.get_addr(), &addr);
1620            entry.id().clone()
1621        };
1622
1623        assert_eq!(bound.conns().get_by_addr(&addr), Some(&Multiple('v', vec![id])));
1624
1625        assert_eq!(bound.conns_mut().remove(&id, &addr), Ok(()));
1626        assert_eq!(bound.conns().get_by_addr(&addr), None);
1627    }
1628
1629    #[test]
1630    fn bound_iter_addrs() {
1631        set_logger_for_test();
1632        let mut bound = FakeBoundSocketMap::default();
1633        let mut fake_id_gen = FakeSocketIdGen::default();
1634
1635        let listener_addrs = [
1636            (Some(net_ip_v4!("1.1.1.1")), 1),
1637            (Some(net_ip_v4!("2.2.2.2")), 2),
1638            (Some(net_ip_v4!("1.1.1.1")), 3),
1639            (None, 4),
1640        ]
1641        .map(|(ip, identifier)| ListenerAddr {
1642            device: None,
1643            ip: ListenerIpAddr {
1644                addr: ip.map(|x| SocketIpAddr::new(x).unwrap()),
1645                identifier: NonZeroU16::new(identifier).unwrap(),
1646            },
1647        });
1648        let conn_addrs = [
1649            (net_ip_v4!("3.3.3.3"), 3, net_ip_v4!("4.4.4.4")),
1650            (net_ip_v4!("4.4.4.4"), 3, net_ip_v4!("3.3.3.3")),
1651        ]
1652        .map(|(local_ip, local_identifier, remote_ip)| ConnAddr {
1653            ip: ConnIpAddr {
1654                local: (
1655                    SocketIpAddr::new(local_ip).unwrap(),
1656                    NonZeroU16::new(local_identifier).unwrap(),
1657                ),
1658                remote: (SocketIpAddr::new(remote_ip).unwrap(), ()),
1659            },
1660            device: None,
1661        });
1662
1663        for addr in listener_addrs.iter().cloned() {
1664            let _entry =
1665                bound.listeners_mut().try_insert(addr, 'a', Listener(fake_id_gen.next())).unwrap();
1666        }
1667        for addr in conn_addrs.iter().cloned() {
1668            let _entry = bound.conns_mut().try_insert(addr, 'a', Conn(fake_id_gen.next())).unwrap();
1669        }
1670        let expected_addrs = listener_addrs
1671            .into_iter()
1672            .map(Into::into)
1673            .chain(conn_addrs.into_iter().map(Into::into))
1674            .collect::<HashSet<_>>();
1675
1676        assert_eq!(expected_addrs, bound.iter_addrs().cloned().collect());
1677    }
1678
1679    #[test]
1680    fn try_insert_with_callback_not_called_on_error() {
1681        // TODO(https://fxbug.dev/42076891): remove this test along with
1682        // try_insert_with.
1683        set_logger_for_test();
1684        let mut bound = FakeBoundSocketMap::default();
1685        let addr = LISTENER_ADDR;
1686
1687        // Insert a listener so that future calls can conflict.
1688        let _: &Listener = bound.listeners_mut().try_insert(addr, 'a', Listener(0)).unwrap().id();
1689
1690        // All of the below try_insert_with calls should fail, but more
1691        // importantly, they should not call the `make_id` callback (because it
1692        // is only called once success is certain).
1693        fn is_never_called<A, B, T>(_: A, _: B) -> (T, ()) {
1694            panic!("should never be called");
1695        }
1696
1697        assert_matches!(
1698            bound.listeners_mut().try_insert_with(addr, 'b', is_never_called),
1699            Err((InsertError::Exists, _))
1700        );
1701        assert_matches!(
1702            bound.listeners_mut().try_insert_with(
1703                ListenerAddr { device: Some(FakeWeakDeviceId(FakeDeviceId)), ..addr },
1704                'b',
1705                is_never_called
1706            ),
1707            Err((InsertError::ShadowAddrExists, _))
1708        );
1709        assert_matches!(
1710            bound.conns_mut().try_insert_with(
1711                ConnAddr {
1712                    device: None,
1713                    ip: ConnIpAddr {
1714                        local: (addr.ip.addr.unwrap(), addr.ip.identifier),
1715                        remote: (SocketIpAddr::new(net_ip_v4!("1.1.1.1")).unwrap(), ()),
1716                    },
1717                },
1718                'b',
1719                is_never_called,
1720            ),
1721            Err((InsertError::ShadowAddrExists, _))
1722        );
1723    }
1724
1725    #[test]
1726    fn insert_listener_conflict_with_listener() {
1727        set_logger_for_test();
1728        let mut bound = FakeBoundSocketMap::default();
1729        let mut fake_id_gen = FakeSocketIdGen::default();
1730        let addr = LISTENER_ADDR;
1731
1732        let _: &Listener =
1733            bound.listeners_mut().try_insert(addr, 'a', Listener(fake_id_gen.next())).unwrap().id();
1734        assert_matches!(
1735            bound.listeners_mut().try_insert(addr, 'b', Listener(fake_id_gen.next())),
1736            Err((InsertError::Exists, 'b'))
1737        );
1738    }
1739
1740    #[test]
1741    fn insert_listener_conflict_with_shadower() {
1742        set_logger_for_test();
1743        let mut bound = FakeBoundSocketMap::default();
1744        let mut fake_id_gen = FakeSocketIdGen::default();
1745        let addr = LISTENER_ADDR;
1746        let shadows_addr = {
1747            assert_eq!(addr.device, None);
1748            ListenerAddr { device: Some(FakeWeakDeviceId(FakeDeviceId)), ..addr }
1749        };
1750
1751        let _: &Listener =
1752            bound.listeners_mut().try_insert(addr, 'a', Listener(fake_id_gen.next())).unwrap().id();
1753        assert_matches!(
1754            bound.listeners_mut().try_insert(shadows_addr, 'b', Listener(fake_id_gen.next())),
1755            Err((InsertError::ShadowAddrExists, 'b'))
1756        );
1757    }
1758
1759    #[test]
1760    fn insert_conn_conflict_with_listener() {
1761        set_logger_for_test();
1762        let mut bound = FakeBoundSocketMap::default();
1763        let mut fake_id_gen = FakeSocketIdGen::default();
1764        let addr = LISTENER_ADDR;
1765        let shadows_addr = ConnAddr {
1766            device: None,
1767            ip: ConnIpAddr {
1768                local: (addr.ip.addr.unwrap(), addr.ip.identifier),
1769                remote: (SocketIpAddr::new(net_ip_v4!("1.1.1.1")).unwrap(), ()),
1770            },
1771        };
1772
1773        let _: &Listener =
1774            bound.listeners_mut().try_insert(addr, 'a', Listener(fake_id_gen.next())).unwrap().id();
1775        assert_matches!(
1776            bound.conns_mut().try_insert(shadows_addr, 'b', Conn(fake_id_gen.next())),
1777            Err((InsertError::ShadowAddrExists, 'b'))
1778        );
1779    }
1780
1781    #[test]
1782    fn insert_and_remove_listener() {
1783        set_logger_for_test();
1784        let mut bound = FakeBoundSocketMap::default();
1785        let mut fake_id_gen = FakeSocketIdGen::default();
1786        let addr = LISTENER_ADDR;
1787
1788        let a = bound
1789            .listeners_mut()
1790            .try_insert(addr, 'x', Listener(fake_id_gen.next()))
1791            .unwrap()
1792            .id()
1793            .clone();
1794        let b = bound
1795            .listeners_mut()
1796            .try_insert(addr, 'x', Listener(fake_id_gen.next()))
1797            .unwrap()
1798            .id()
1799            .clone();
1800        assert_ne!(a, b);
1801
1802        assert_eq!(bound.listeners_mut().remove(&a, &addr), Ok(()));
1803        assert_eq!(bound.listeners().get_by_addr(&addr), Some(&Multiple('x', vec![b])));
1804    }
1805
1806    #[test]
1807    fn insert_and_remove_conn() {
1808        set_logger_for_test();
1809        let mut bound = FakeBoundSocketMap::default();
1810        let mut fake_id_gen = FakeSocketIdGen::default();
1811        let addr = CONN_ADDR;
1812
1813        let a =
1814            bound.conns_mut().try_insert(addr, 'x', Conn(fake_id_gen.next())).unwrap().id().clone();
1815        let b =
1816            bound.conns_mut().try_insert(addr, 'x', Conn(fake_id_gen.next())).unwrap().id().clone();
1817        assert_ne!(a, b);
1818
1819        assert_eq!(bound.conns_mut().remove(&a, &addr), Ok(()));
1820        assert_eq!(bound.conns().get_by_addr(&addr), Some(&Multiple('x', vec![b])));
1821    }
1822
1823    #[test]
1824    fn update_listener_to_shadowed_addr_fails() {
1825        let mut bound = FakeBoundSocketMap::default();
1826        let mut fake_id_gen = FakeSocketIdGen::default();
1827
1828        let first_addr = LISTENER_ADDR;
1829        let second_addr = ListenerAddr {
1830            ip: ListenerIpAddr {
1831                addr: Some(SocketIpAddr::new(net_ip_v4!("1.1.1.1")).unwrap()),
1832                ..LISTENER_ADDR.ip
1833            },
1834            ..LISTENER_ADDR
1835        };
1836        let both_shadow = ListenerAddr {
1837            ip: ListenerIpAddr { addr: None, identifier: first_addr.ip.identifier },
1838            device: None,
1839        };
1840
1841        let first = bound
1842            .listeners_mut()
1843            .try_insert(first_addr, 'a', Listener(fake_id_gen.next()))
1844            .unwrap()
1845            .id()
1846            .clone();
1847        let second = bound
1848            .listeners_mut()
1849            .try_insert(second_addr, 'b', Listener(fake_id_gen.next()))
1850            .unwrap()
1851            .id()
1852            .clone();
1853
1854        // Moving from (1, "aaa") to (1, None) should fail since it is shadowed
1855        // by (1, "yyy"), and vise versa.
1856        let (ExistsError, entry) = bound
1857            .listeners_mut()
1858            .entry(&second, &second_addr)
1859            .unwrap()
1860            .try_update_addr(both_shadow)
1861            .expect_err("update should fail");
1862
1863        // The entry should correspond to `second`.
1864        assert_eq!(entry.id(), &second);
1865        drop(entry);
1866
1867        let (ExistsError, entry) = bound
1868            .listeners_mut()
1869            .entry(&first, &first_addr)
1870            .unwrap()
1871            .try_update_addr(both_shadow)
1872            .expect_err("update should fail");
1873        assert_eq!(entry.get_addr(), &first_addr);
1874    }
1875
1876    #[test]
1877    fn nonexistent_conn_entry() {
1878        let mut map = FakeBoundSocketMap::default();
1879        let mut fake_id_gen = FakeSocketIdGen::default();
1880        let addr = CONN_ADDR;
1881        let conn_id = map
1882            .conns_mut()
1883            .try_insert(addr.clone(), 'a', Conn(fake_id_gen.next()))
1884            .expect("failed to insert")
1885            .id()
1886            .clone();
1887        assert_matches!(map.conns_mut().remove(&conn_id, &addr), Ok(()));
1888
1889        assert!(map.conns_mut().entry(&conn_id, &addr).is_none());
1890    }
1891
1892    #[test]
1893    fn update_conn_sharing() {
1894        let mut map = FakeBoundSocketMap::default();
1895        let mut fake_id_gen = FakeSocketIdGen::default();
1896        let addr = CONN_ADDR;
1897        let mut entry = map
1898            .conns_mut()
1899            .try_insert(addr.clone(), 'a', Conn(fake_id_gen.next()))
1900            .expect("failed to insert");
1901
1902        entry.try_update_sharing(&'a', 'd').expect("worked");
1903        // Updating sharing is only allowed if there are no other occupants at
1904        // the address.
1905        let mut second_conn = map
1906            .conns_mut()
1907            .try_insert(addr.clone(), 'd', Conn(fake_id_gen.next()))
1908            .expect("can insert");
1909        assert_matches!(second_conn.try_update_sharing(&'d', 'e'), Err(UpdateSharingError));
1910    }
1911}