Expand description
A sans-I/O userspace Multipath TCP v1 (RFC 8684) and TCP client stack.
It implements the MPTCP protocol itself in userspace; it is not a helper for creating kernel MPTCP sockets.
The library does no I/O of its own. The caller feeds it received IP packets and the
current time, drains the IP packets it wants sent, and sleeps until its next timer.
Time (Instant) and randomness (a rand_core::CryptoRng) are injected, and the
crate contains no unsafe code.
§Scope at 0.2.0
Client role only. Implemented: MP_CAPABLE, DSS and DATA_ACK, MP_JOIN with multiple subflows over IPv4 and IPv6 (including mixed families), a MinRTT scheduler with reinjection, opportunistic retransmission and penalization, stale-subflow detection, fallback to TCP (including the infinite mapping); CUBIC with HyStart++ and pacing, and SACK-based loss recovery; plain TCP connections.
Congestion control is chosen per connection with ConnectConfig::congestion_control:
CongestionControlKind::Cubic (the default) or CongestionControlKind::BbrV3, BBRv3
(draft-ietf-ccwg-bbr-06, experimental). Every subflow runs the same controller, and the
subflows are not coupled: two subflows that share one bottleneck take about the share of
two TCP flows, with either controller.
Path management is driven by the application: Endpoint::add_subflow joins a new path
(optionally with the backup bit), Endpoint::set_backup sends MP_PRIO,
Endpoint::set_local_backup changes only the local transmit policy,
Endpoint::close_subflow retires a subflow gracefully and
Endpoint::remove_address sends REMOVE_ADDR and resets the subflows on that address.
Received ADD_ADDR (with echo), REMOVE_ADDR and MP_PRIO surface as
Event::AddressAnnounced, Event::AddressRemoved and Event::PeerPriority, and
MP_TCPRST reasons arrive in Event::SubflowDown. Connection::abort sends
MP_FASTCLOSE; MP_FASTCLOSE is also honoured on receive.
Not implemented yet: the server role, MPTCP checksums, MP_FAIL and RACK-TLP. Known limitations: an application with no data left to send can still wait for a blackholed subflow to be declared stale, and backup failover waits for the primary to become unusable (see the README).
§Usage
Endpoint::connect_mptcp opens an MPTCP connection (falling back to TCP if the peer
does not support it); Endpoint::connect opens plain TCP. Then drive the endpoint:
Endpoint::handle_packetfor each received IP packet;Endpoint::poll_transmituntil it returnsNone, sending each packet it writes;Endpoint::poll_timeoutfor the next deadline, andEndpoint::handle_timeoutwhen it passes;Endpoint::poll_eventforEvents such asConnected,SubflowUpandClosed;Endpoint::connectionfor theConnection, towrite,readandclose;Endpoint::add_subflowto join another local address once connected (see above for the other path-management calls).
use mptcp_rs::{ConnectConfig, Endpoint, Instant};
use rand_chacha::ChaCha20Rng;
use rand_core::SeedableRng;
// Seed from the OS in real use; a fixed seed keeps this example deterministic.
let mut ep = Endpoint::new(ChaCha20Rng::seed_from_u64(1));
let now = Instant::from_nanos(0);
let local = "10.0.9.2".parse().unwrap();
let remote = "10.0.1.2:5201".parse().unwrap();
let _h = ep.connect_mptcp(now, local, remote, ConnectConfig::default()).unwrap();
let mut buf = [0u8; 1500];
let n = ep.poll_transmit(now, &mut buf).expect("the SYN");
// Send `&buf[..n]` on the network, then feed replies to `ep.handle_packet(now, ..)`.
assert!(n > 0);Re-exports§
pub use tcp::CloseReason;pub use tcp::CongestionControlKind;pub use tcp::ConnectConfig;
Modules§
- crypto
- Crypto helpers: MPTCP key token/IDSN (RFC 8684 §3.1), MP_JOIN HMAC (§3.2) and the RFC 6528 initial sequence number generator.
- tcp
- Plain TCP engine: the pure
Tcbstate machine and the hooks it drives (spec §3). - wire
- Wire formats: TCP option walker and MPTCP option codec.
Structs§
- Connection
- Connection
Handle - Opaque, never reused within one
Endpoint. - Endpoint
- Instant
- Monotonic time in nanoseconds, always supplied by the caller.
- MpTcp
Rst - The MP_TCPRST option of a peer’s RST (RFC 8684 §3.6).
- SeqNum
- TCP sequence number with RFC 9293 §3.4 modular comparison.
- Subflow
Id - Identifies a subflow within its connection: allocated in increasing order and never
reused. The initial subflow is
SubflowId(0).
Enums§
- AddSubflow
Error - Address
Error - Why
remove_addressfailed. - Connect
Error - Event
- Read
Error - Subflow
Error - Why a call on one subflow failed.
- Write
Error writefailed because the connection is closed (byclose,abort, a reset or a timeout).