netstack3_core/
transport.rs

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::{
70    UdpCountersWithSocket, UdpCountersWithoutSocket, UdpSocketTxMetadata, UdpState,
71};
72
73use crate::{BindingsContext, BindingsTypes, CoreCtx, IpExt};
74
75/// A builder for transport layer state.
76#[derive(Default, Clone)]
77pub struct TransportStateBuilder;
78
79impl TransportStateBuilder {
80    pub(crate) fn build_with_ctx<BC: BindingsContext>(
81        self,
82        bindings_ctx: &mut BC,
83    ) -> TransportLayerState<BC> {
84        let now = bindings_ctx.now();
85        let mut rng = bindings_ctx.rng();
86        TransportLayerState {
87            udpv4: Default::default(),
88            udpv6: Default::default(),
89            tcpv4: TcpState::new(now, &mut rng),
90            tcpv6: TcpState::new(now, &mut rng),
91            icmp_echo_v4: Default::default(),
92            icmp_echo_v6: Default::default(),
93        }
94    }
95}
96
97/// The state associated with the transport layer.
98pub struct TransportLayerState<BT: BindingsTypes> {
99    udpv4: UdpState<Ipv4, WeakDeviceId<BT>, BT>,
100    udpv6: UdpState<Ipv6, WeakDeviceId<BT>, BT>,
101    tcpv4: TcpState<Ipv4, WeakDeviceId<BT>, BT>,
102    tcpv6: TcpState<Ipv6, WeakDeviceId<BT>, BT>,
103    icmp_echo_v4: IcmpSockets<Ipv4, WeakDeviceId<BT>, BT>,
104    icmp_echo_v6: IcmpSockets<Ipv6, WeakDeviceId<BT>, BT>,
105}
106
107impl<BT: BindingsTypes> TransportLayerState<BT> {
108    fn tcp_state<I: tcp::DualStackIpExt>(&self) -> &TcpState<I, WeakDeviceId<BT>, BT> {
109        I::map_ip((), |()| &self.tcpv4, |()| &self.tcpv6)
110    }
111
112    fn udp_state<I: datagram::IpExt>(&self) -> &UdpState<I, WeakDeviceId<BT>, BT> {
113        I::map_ip((), |()| &self.udpv4, |()| &self.udpv6)
114    }
115
116    pub(crate) fn icmp_echo_state<I: datagram::IpExt>(
117        &self,
118    ) -> &IcmpSockets<I, WeakDeviceId<BT>, BT> {
119        I::map_ip((), |()| &self.icmp_echo_v4, |()| &self.icmp_echo_v6)
120    }
121
122    pub(crate) fn udp_counters_with_socket<I: Ip>(&self) -> &UdpCountersWithSocket<I> {
123        I::map_ip((), |()| &self.udpv4.counters_with_socket, |()| &self.udpv6.counters_with_socket)
124    }
125
126    pub(crate) fn udp_counters_without_socket<I: Ip>(&self) -> &UdpCountersWithoutSocket<I> {
127        I::map_ip(
128            (),
129            |()| &self.udpv4.counters_without_socket,
130            |()| &self.udpv6.counters_without_socket,
131        )
132    }
133
134    pub(crate) fn tcp_counters_with_socket<I: Ip>(&self) -> &TcpCountersWithSocket<I> {
135        I::map_ip((), |()| &self.tcpv4.counters_with_socket, |()| &self.tcpv6.counters_with_socket)
136    }
137
138    pub(crate) fn tcp_counters_without_socket<I: Ip>(&self) -> &TcpCountersWithoutSocket<I> {
139        I::map_ip(
140            (),
141            |()| &self.tcpv4.counters_without_socket,
142            |()| &self.tcpv6.counters_without_socket,
143        )
144    }
145}
146
147/// The identifier for timer events in the transport layer.
148#[derive(Derivative)]
149#[derivative(
150    Clone(bound = ""),
151    Eq(bound = ""),
152    PartialEq(bound = ""),
153    Hash(bound = ""),
154    Debug(bound = "")
155)]
156pub(crate) enum TransportLayerTimerId<BT: BindingsTypes> {
157    Tcp(TcpTimerId<WeakDeviceId<BT>, BT>),
158}
159
160impl<CC, BT> HandleableTimer<CC, BT> for TransportLayerTimerId<BT>
161where
162    BT: BindingsTypes,
163    CC: TimerHandler<BT, TcpTimerId<WeakDeviceId<BT>, BT>>,
164{
165    fn handle(self, core_ctx: &mut CC, bindings_ctx: &mut BT, timer: BT::UniqueTimerId) {
166        match self {
167            TransportLayerTimerId::Tcp(id) => core_ctx.handle_timer(bindings_ctx, id, timer),
168        }
169    }
170}
171
172impl<BT: BindingsTypes> From<TcpTimerId<WeakDeviceId<BT>, BT>> for TransportLayerTimerId<BT> {
173    fn from(id: TcpTimerId<WeakDeviceId<BT>, BT>) -> Self {
174        TransportLayerTimerId::Tcp(id)
175    }
176}
177
178/// The frame metadata type for frames traversing the stack.
179#[derive(Derivative)]
180#[derivative(Debug = "transparent", Debug(bound = ""), Default(bound = ""))]
181#[cfg_attr(any(test, feature = "testutils"), derivative(PartialEq(bound = "")))]
182pub struct TxMetadata<BT: BindingsTypes>(TxMetadataInner<BT>);
183
184/// The internal metadata type.
185///
186/// This is split from [`TxMetadata`] so the outer type is opaque to bindings.
187#[derive(Derivative)]
188#[derivative(Debug(bound = ""), Default(bound = ""))]
189#[cfg_attr(any(test, feature = "testutils"), derivative(PartialEq(bound = "")))]
190enum TxMetadataInner<BT: BindingsTypes> {
191    #[derivative(Default)]
192    None,
193    #[derivative(Debug = "transparent")]
194    Udpv4(UdpSocketTxMetadata<Ipv4, WeakDeviceId<BT>, BT>),
195    #[derivative(Debug = "transparent")]
196    Udpv6(UdpSocketTxMetadata<Ipv6, WeakDeviceId<BT>, BT>),
197    #[derivative(Debug = "transparent")]
198    Icmpv4(IcmpSocketTxMetadata<Ipv4, WeakDeviceId<BT>, BT>),
199    #[derivative(Debug = "transparent")]
200    Icmpv6(IcmpSocketTxMetadata<Ipv6, WeakDeviceId<BT>, BT>),
201}
202
203impl<I: IpExt, L, BT: BindingsTypes>
204    CoreTxMetadataContext<UdpSocketTxMetadata<I, WeakDeviceId<BT>, BT>, BT> for CoreCtx<'_, BT, L>
205{
206    fn convert_tx_meta(
207        &self,
208        tx_meta: UdpSocketTxMetadata<I, WeakDeviceId<BT>, BT>,
209    ) -> TxMetadata<BT> {
210        TxMetadata(I::map_ip_in(tx_meta, TxMetadataInner::Udpv4, TxMetadataInner::Udpv6))
211    }
212}
213
214impl<I: IpExt, L, BT: BindingsTypes>
215    CoreTxMetadataContext<IcmpSocketTxMetadata<I, WeakDeviceId<BT>, BT>, BT>
216    for CoreCtx<'_, BT, L>
217{
218    fn convert_tx_meta(
219        &self,
220        tx_meta: IcmpSocketTxMetadata<I, WeakDeviceId<BT>, BT>,
221    ) -> TxMetadata<BT> {
222        TxMetadata(I::map_ip_in(tx_meta, TxMetadataInner::Icmpv4, TxMetadataInner::Icmpv6))
223    }
224}
netstack3_core/transport.rs

netstack3_core/
transport.rs
