mptcp_rs/lib.rs
1//! A sans-I/O userspace Multipath TCP v1 (RFC 8684) and TCP client stack.
2//!
3//! It implements the MPTCP protocol itself in userspace; it is not a helper for creating
4//! kernel MPTCP sockets.
5//!
6//! The library does no I/O of its own. The caller feeds it received IP packets and the
7//! current time, drains the IP packets it wants sent, and sleeps until its next timer.
8//! Time ([`Instant`]) and randomness (a [`rand_core::CryptoRng`]) are injected, and the
9//! crate contains no `unsafe` code.
10//!
11//! # Scope at 0.2.0
12//!
13//! Client role only. Implemented: MP_CAPABLE, DSS and DATA_ACK, MP_JOIN with multiple
14//! subflows over IPv4 and IPv6 (including mixed families), a MinRTT scheduler with
15//! reinjection, opportunistic retransmission and penalization, stale-subflow detection,
16//! fallback to TCP (including the infinite mapping); CUBIC with HyStart++ and pacing, and
17//! SACK-based loss recovery; plain TCP connections.
18//!
19//! Congestion control is chosen per connection with [`ConnectConfig::congestion_control`]:
20//! [`CongestionControlKind::Cubic`] (the default) or [`CongestionControlKind::BbrV3`], BBRv3
21//! (draft-ietf-ccwg-bbr-06, experimental). Every subflow runs the same controller, and the
22//! subflows are not coupled: two subflows that share one bottleneck take about the share of
23//! two TCP flows, with either controller.
24//!
25//! Path management is driven by the application: [`Endpoint::add_subflow`] joins a new path
26//! (optionally with the backup bit), [`Endpoint::set_backup`] sends MP_PRIO,
27//! [`Endpoint::set_local_backup`] changes only the local transmit policy,
28//! [`Endpoint::close_subflow`] retires a subflow gracefully and
29//! [`Endpoint::remove_address`] sends REMOVE_ADDR and resets the subflows on that address.
30//! Received ADD_ADDR (with echo), REMOVE_ADDR and MP_PRIO surface as
31//! [`Event::AddressAnnounced`], [`Event::AddressRemoved`] and [`Event::PeerPriority`], and
32//! MP_TCPRST reasons arrive in [`Event::SubflowDown`]. [`Connection::abort`] sends
33//! MP_FASTCLOSE; MP_FASTCLOSE is also honoured on receive.
34//!
35//! Not implemented yet: the server role, MPTCP checksums, MP_FAIL and RACK-TLP. Known
36//! limitations: an application with no data left to send can still wait for a blackholed
37//! subflow to be declared stale, and backup failover waits for the primary to become
38//! unusable (see the README).
39//!
40//! # Usage
41//!
42//! [`Endpoint::connect_mptcp`] opens an MPTCP connection (falling back to TCP if the peer
43//! does not support it); [`Endpoint::connect`] opens plain TCP. Then drive the endpoint:
44//!
45//! - [`Endpoint::handle_packet`] for each received IP packet;
46//! - [`Endpoint::poll_transmit`] until it returns `None`, sending each packet it writes;
47//! - [`Endpoint::poll_timeout`] for the next deadline, and [`Endpoint::handle_timeout`]
48//! when it passes;
49//! - [`Endpoint::poll_event`] for [`Event`]s such as `Connected`, `SubflowUp` and `Closed`;
50//! - [`Endpoint::connection`] for the [`Connection`], to [`write`](Connection::write),
51//! [`read`](Connection::read) and [`close`](Connection::close);
52//! - [`Endpoint::add_subflow`] to join another local address once connected (see above for
53//! the other path-management calls).
54//!
55//! ```
56//! use mptcp_rs::{ConnectConfig, Endpoint, Instant};
57//! use rand_chacha::ChaCha20Rng;
58//! use rand_core::SeedableRng;
59//!
60//! // Seed from the OS in real use; a fixed seed keeps this example deterministic.
61//! let mut ep = Endpoint::new(ChaCha20Rng::seed_from_u64(1));
62//! let now = Instant::from_nanos(0);
63//! let local = "10.0.9.2".parse().unwrap();
64//! let remote = "10.0.1.2:5201".parse().unwrap();
65//! let _h = ep.connect_mptcp(now, local, remote, ConnectConfig::default()).unwrap();
66//!
67//! let mut buf = [0u8; 1500];
68//! let n = ep.poll_transmit(now, &mut buf).expect("the SYN");
69//! // Send `&buf[..n]` on the network, then feed replies to `ep.handle_packet(now, ..)`.
70//! assert!(n > 0);
71//! ```
72
73#![forbid(unsafe_code)]
74
75mod connection;
76pub mod crypto;
77mod endpoint;
78mod mptcp;
79mod seq;
80pub mod tcp;
81mod time;
82pub mod wire;
83
84pub use connection::{Connection, ReadError, WriteError};
85pub use endpoint::{
86 AddSubflowError, AddressError, ConnectError, ConnectionHandle, Endpoint, Event, MpTcpRst,
87 SubflowError,
88};
89#[doc(hidden)]
90pub use mptcp::DebugStats;
91pub use mptcp::SubflowId;
92pub use seq::SeqNum;
93pub use tcp::{CloseReason, CongestionControlKind, ConnectConfig};
94pub use time::Instant;