netstack3_core/
transport.rs

Help
1// Copyright 2018 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//! The transport layer.
6//!
7//! # Listeners and connections
8//!
9//! Some transport layer protocols (notably TCP and UDP) follow a common pattern
10//! with respect to registering listeners and connections. There are some
11//! subtleties here that are worth pointing out.
12//!
13//! ## Connections
14//!
15//! A connection has simpler semantics than a listener. It is bound to a single
16//! local address and port and a single remote address and port. By virtue of
17//! being bound to a local address, it is also bound to a local interface. This
18//! means that, regardless of the entries in the forwarding table, all traffic
19//! on that connection will always egress over the same interface. [^1] This
20//! also means that, if the interface's address changes, any connections bound
21//! to it are severed.
22//!
23//! ## Listeners
24//!
25//! A listener, on the other hand, can be bound to any number of local addresses
26//! (although it is still always bound to a particular port). From the
27//! perspective of this crate, there are two ways of registering a listener:
28//! - By specifying one or more local addresses, the listener will be bound to
29//!   each of those local addresses.
30//! - By specifying zero local addresses, the listener will be bound to all
31//!   addresses. These are referred to in our documentation as "wildcard
32//!   listeners".
33//!
34//! The algorithm for figuring out what listener to deliver a packet to is as
35//! follows: If there is any listener bound to the specific local address and
36//! port addressed in the packet, deliver the packet to that listener.
37//! Otherwise, if there is a wildcard listener bound the port addressed in the
38//! packet, deliver the packet to that listener. This implies that if a listener
39//! is removed which was bound to a particular local address, it can "uncover" a
40//! wildcard listener bound to the same port, allowing traffic which would
41//! previously have been delivered to the normal listener to now be delivered to
42//! the wildcard listener.
43//!
44//! If desired, clients of this crate can implement a different mechanism for
45//! registering listeners on all local addresses - enumerate every local
46//! address, and then specify all of the local addresses when registering the
47//! listener. This approach will not support shadowing, as a different listener
48//! binding to the same port will explicitly conflict with the existing
49//! listener, and will thus be rejected. In other words, from the perspective of
50//! this crate's API, such listeners will appear like normal listeners that just
51//! happen to bind all of the addresses, rather than appearing like wildcard
52//! listeners.
53//!
54//! [^1]: It is an open design question as to whether incoming traffic on the
55//!       connection will be accepted from a different interface. This is part
56//!       of the "weak host model" vs "strong host model" discussion.
57
58mod integration;
59
60use derivative::Derivative;
61use net_types::ip::{Ip, Ipv4, Ipv6};
62use netstack3_base::{CoreTxMetadataContext, HandleableTimer, TimerHandler};
63use netstack3_datagram as datagram;
64use netstack3_device::WeakDeviceId;
65use netstack3_icmp_echo::{IcmpSocketTxMetadata, IcmpSockets};
66use netstack3_tcp::{
67    self as tcp, TcpCountersWithSocket, TcpCountersWithoutSocket, TcpState, TcpTimerId,
68};
69use netstack3_udp::{UdpCounters, UdpSocketTxMetadata, UdpState, UdpStateBuilder};
70
71use crate::{BindingsContext, BindingsTypes, CoreCtx, IpExt};
72
73/// A builder for transport layer state.
74#[derive(Default, Clone)]
75pub struct TransportStateBuilder {
76    udp: UdpStateBuilder,
77}
78
79impl TransportStateBuilder {
80    /// Get the builder for the UDP state.
81    pub fn udp_builder(&mut self) -> &mut UdpStateBuilder {
82        &mut self.udp
83    }
84
85    pub(crate) fn build_with_ctx<BC: BindingsContext>(
86        self,
87        bindings_ctx: &mut BC,
88    ) -> TransportLayerState<BC> {
89        let now = bindings_ctx.now();
90        let mut rng = bindings_ctx.rng();
91        TransportLayerState {
92            udpv4: self.udp.clone().build(),
93            udpv6: self.udp.build(),
94            tcpv4: TcpState::new(now, &mut rng),
95            tcpv6: TcpState::new(now, &mut rng),
96            icmp_echo_v4: Default::default(),
97            icmp_echo_v6: Default::default(),
98        }
99    }
100}
101
102/// The state associated with the transport layer.
103pub struct TransportLayerState<BT: BindingsTypes> {
104    udpv4: UdpState<Ipv4, WeakDeviceId<BT>, BT>,
105    udpv6: UdpState<Ipv6, WeakDeviceId<BT>, BT>,
106    tcpv4: TcpState<Ipv4, WeakDeviceId<BT>, BT>,
107    tcpv6: TcpState<Ipv6, WeakDeviceId<BT>, BT>,
108    icmp_echo_v4: IcmpSockets<Ipv4, WeakDeviceId<BT>, BT>,
109    icmp_echo_v6: IcmpSockets<Ipv6, WeakDeviceId<BT>, BT>,
110}
111
112impl<BT: BindingsTypes> TransportLayerState<BT> {
113    fn tcp_state<I: tcp::DualStackIpExt>(&self) -> &TcpState<I, WeakDeviceId<BT>, BT> {
114        I::map_ip((), |()| &self.tcpv4, |()| &self.tcpv6)
115    }
116
117    fn udp_state<I: datagram::IpExt>(&self) -> &UdpState<I, WeakDeviceId<BT>, BT> {
118        I::map_ip((), |()| &self.udpv4, |()| &self.udpv6)
119    }
120
121    pub(crate) fn icmp_echo_state<I: datagram::IpExt>(
122        &self,
123    ) -> &IcmpSockets<I, WeakDeviceId<BT>, BT> {
124        I::map_ip((), |()| &self.icmp_echo_v4, |()| &self.icmp_echo_v6)
125    }
126
127    pub(crate) fn udp_counters<I: Ip>(&self) -> &UdpCounters<I> {
128        I::map_ip((), |()| &self.udpv4.counters, |()| &self.udpv6.counters)
129    }
130
131    pub(crate) fn tcp_counters_with_socket<I: Ip>(&self) -> &TcpCountersWithSocket<I> {
132        I::map_ip((), |()| &self.tcpv4.counters_with_socket, |()| &self.tcpv6.counters_with_socket)
133    }
134
135    pub(crate) fn tcp_counters_without_socket<I: Ip>(&self) -> &TcpCountersWithoutSocket<I> {
136        I::map_ip(
137            (),
138            |()| &self.tcpv4.counters_without_socket,
139            |()| &self.tcpv6.counters_without_socket,
140        )
141    }
142}
143
144/// The identifier for timer events in the transport layer.
145#[derive(Derivative)]
146#[derivative(
147    Clone(bound = ""),
148    Eq(bound = ""),
149    PartialEq(bound = ""),
150    Hash(bound = ""),
151    Debug(bound = "")
152)]
153pub(crate) enum TransportLayerTimerId<BT: BindingsTypes> {
154    Tcp(TcpTimerId<WeakDeviceId<BT>, BT>),
155}
156
157impl<CC, BT> HandleableTimer<CC, BT> for TransportLayerTimerId<BT>
158where
159    BT: BindingsTypes,
160    CC: TimerHandler<BT, TcpTimerId<WeakDeviceId<BT>, BT>>,
161{
162    fn handle(self, core_ctx: &mut CC, bindings_ctx: &mut BT, timer: BT::UniqueTimerId) {
163        match self {
164            TransportLayerTimerId::Tcp(id) => core_ctx.handle_timer(bindings_ctx, id, timer),
165        }
166    }
167}
168
169impl<BT: BindingsTypes> From<TcpTimerId<WeakDeviceId<BT>, BT>> for TransportLayerTimerId<BT> {
170    fn from(id: TcpTimerId<WeakDeviceId<BT>, BT>) -> Self {
171        TransportLayerTimerId::Tcp(id)
172    }
173}
174
175/// The frame metadata type for frames traversing the stack.
176#[derive(Derivative)]
177#[derivative(Debug = "transparent", Debug(bound = ""), Default(bound = ""))]
178#[cfg_attr(any(test, feature = "testutils"), derivative(PartialEq(bound = "")))]
179pub struct TxMetadata<BT: BindingsTypes>(TxMetadataInner<BT>);
180
181/// The internal metadata type.
182///
183/// This is split from [`TxMetadata`] so the outer type is opaque to bindings.
184#[derive(Derivative)]
185#[derivative(Debug(bound = ""), Default(bound = ""))]
186#[cfg_attr(any(test, feature = "testutils"), derivative(PartialEq(bound = "")))]
187enum TxMetadataInner<BT: BindingsTypes> {
188    #[derivative(Default)]
189    None,
190    #[derivative(Debug = "transparent")]
191    Udpv4(UdpSocketTxMetadata<Ipv4, WeakDeviceId<BT>, BT>),
192    #[derivative(Debug = "transparent")]
193    Udpv6(UdpSocketTxMetadata<Ipv6, WeakDeviceId<BT>, BT>),
194    #[derivative(Debug = "transparent")]
195    Icmpv4(IcmpSocketTxMetadata<Ipv4, WeakDeviceId<BT>, BT>),
196    #[derivative(Debug = "transparent")]
197    Icmpv6(IcmpSocketTxMetadata<Ipv6, WeakDeviceId<BT>, BT>),
198}
199
200impl<I: IpExt, L, BT: BindingsTypes>
201    CoreTxMetadataContext<UdpSocketTxMetadata<I, WeakDeviceId<BT>, BT>, BT> for CoreCtx<'_, BT, L>
202{
203    fn convert_tx_meta(
204        &self,
205        tx_meta: UdpSocketTxMetadata<I, WeakDeviceId<BT>, BT>,
206    ) -> TxMetadata<BT> {
207        TxMetadata(I::map_ip_in(tx_meta, TxMetadataInner::Udpv4, TxMetadataInner::Udpv6))
208    }
209}
210
211impl<I: IpExt, L, BT: BindingsTypes>
212    CoreTxMetadataContext<IcmpSocketTxMetadata<I, WeakDeviceId<BT>, BT>, BT>
213    for CoreCtx<'_, BT, L>
214{
215    fn convert_tx_meta(
216        &self,
217        tx_meta: IcmpSocketTxMetadata<I, WeakDeviceId<BT>, BT>,
218    ) -> TxMetadata<BT> {
219        TxMetadata(I::map_ip_in(tx_meta, TxMetadataInner::Icmpv4, TxMetadataInner::Icmpv6))
220    }
221}
netstack3_core/transport.rs

netstack3_core/
transport.rs
