mod cc;
mod codec;
#[cfg(feature = "discovery")]
mod discovery;
mod engine;
mod error;
mod frag;
mod frame;
mod mtu;
mod peer;
mod rate;
#[cfg(feature = "security")]
mod security;
mod socket;
pub const DEFAULT_STREAM: u16 = 0;
pub use codec::{Decode, Encode};
#[cfg(feature = "discovery")]
pub use discovery::{
AdvertiseHandle, AppId, DISCOVERY_PORT, DiscoveredPeer, Discovery, DiscoveryConfig, ScanStream,
};
pub use error::Error;
#[cfg(feature = "security")]
pub use security::Keypair;
#[derive(Debug, Clone)]
pub struct RawBytes(pub Bytes);
impl Encode for RawBytes {
fn encode_to_bytes(&self) -> Result<Vec<u8>, Error> {
Ok(self.0.to_vec())
}
}
impl Decode for RawBytes {
fn decode_from_bytes(bytes: &[u8]) -> Result<Self, Error> {
Ok(RawBytes(Bytes::copy_from_slice(bytes)))
}
}
#[derive(Clone)]
pub struct ZudpSender {
inner: Arc<Inner>,
}
impl ZudpSender {
pub async fn send_stream<M: Encode>(
&self,
msg: M,
peer: SocketAddr,
stream_id: u16,
) -> Result<(), Error> {
self.inner.send_msg(&msg, peer, true, stream_id).await
}
}
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct PeerStats {
pub srtt: Option<Duration>,
pub congestion_factor: Option<f64>,
pub pacing_rate_bps: u64,
pub rx_bytes: u64,
pub tx_bytes: u64,
pub retransmit_count: u64,
}
#[derive(Debug, Clone, Default)]
#[non_exhaustive]
pub struct EngineStats {
pub dropped_rate_limited: u64,
pub dropped_peer_cap: u64,
pub dropped_relay_blocked: u64,
pub dropped_relay_cap: u64,
}
#[derive(Debug)]
pub struct Packet<M> {
pub msg: M,
pub from: std::net::SocketAddr,
pub stream: u16,
}
#[cfg(feature = "rkyv")]
pub use ::rkyv;
#[cfg(feature = "bitcode")]
pub use ::bitcode;
#[cfg(feature = "serde")]
pub use ::serde;
#[cfg(feature = "serde")]
pub use ::postcard;
use std::{
marker::PhantomData,
net::{IpAddr, Ipv4Addr, SocketAddr},
sync::{
Arc,
atomic::{AtomicU64, AtomicU32, Ordering},
},
time::Duration,
};
use bytes::Bytes;
use dashmap::DashMap;
use parking_lot::RwLock;
use tokio::sync::mpsc;
use engine::EngineInner;
use frag::fragment;
use frame::Frame;
use peer::PeerState;
use socket::RawSocket;
#[derive(Clone)]
pub struct Config {
pub(crate) port: u16,
pub(crate) bind_ip: IpAddr,
pub(crate) reliable: bool,
pub(crate) keepalive_interval: Duration,
pub(crate) sent_prune_age: Duration,
pub(crate) mtu: usize,
pub(crate) relay_addr: Option<SocketAddr>,
#[cfg(feature = "security")]
pub(crate) security: Option<security::Keypair>,
#[cfg(feature = "security")]
pub(crate) remote_key: Option<[u8; 32]>,
pub(crate) max_peers: usize,
pub(crate) max_pps_per_ip: f64,
pub(crate) relay_allowlist: Vec<IpAddr>,
pub(crate) max_relay_entries: usize,
}
impl Default for Config {
fn default() -> Self {
Self {
port: 0,
bind_ip: IpAddr::V4(Ipv4Addr::UNSPECIFIED),
reliable: true,
keepalive_interval: Duration::from_secs(5),
sent_prune_age: Duration::from_secs(10),
mtu: 1400,
relay_addr: None,
#[cfg(feature = "security")]
security: None,
#[cfg(feature = "security")]
remote_key: None,
max_peers: 1_024,
max_pps_per_ip: 1_000.0,
relay_allowlist: vec![],
max_relay_entries: 256,
}
}
}
#[derive(Clone, Default)]
pub struct Zudp {
config: Config,
}
impl Zudp {
#[must_use]
pub fn port(mut self, port: u16) -> Self {
self.config.port = port;
self
}
#[must_use]
pub fn bind_ip(mut self, ip: IpAddr) -> Self {
self.config.bind_ip = ip;
self
}
#[must_use]
pub fn reliable(mut self, enabled: bool) -> Self {
self.config.reliable = enabled;
self
}
#[must_use]
pub fn keepalive_interval(mut self, interval: Duration) -> Self {
self.config.keepalive_interval = interval;
self
}
#[must_use]
pub fn mtu(mut self, bytes: usize) -> Self {
self.config.mtu = bytes;
self
}
#[must_use]
pub fn relay(mut self, relay_addr: SocketAddr) -> Self {
self.config.relay_addr = Some(relay_addr);
self
}
#[cfg(feature = "security")]
#[must_use]
pub fn security(mut self, keypair: Keypair) -> Self {
self.config.security = Some(keypair);
self
}
#[cfg(feature = "security")]
#[must_use]
pub fn pin_remote_key(mut self, key: [u8; 32]) -> Self {
self.config.remote_key = Some(key);
self
}
#[must_use]
pub fn max_peers(mut self, n: usize) -> Self {
self.config.max_peers = n;
self
}
#[must_use]
pub fn rate_limit(mut self, max_pps: f64) -> Self {
self.config.max_pps_per_ip = max_pps;
self
}
#[must_use]
pub fn relay_allowlist(mut self, ips: Vec<IpAddr>) -> Self {
self.config.relay_allowlist = ips;
self
}
#[must_use]
pub fn max_relay_entries(mut self, n: usize) -> Self {
self.config.max_relay_entries = n;
self
}
pub async fn listen<M>(self) -> Result<ZudpSocket<M>, Error> {
ZudpSocket::new(self.config).await
}
pub async fn connect<M>(self, peer: SocketAddr) -> Result<ZudpConn<M>, Error> {
let socket = ZudpSocket::new(self.config).await?;
let peer_state = socket.inner.get_or_create_peer(peer);
let peer_addr = peer_state.addr_arc();
#[cfg(feature = "security")]
if socket.inner.config.security.is_some() {
socket.inner.initiate_handshake(peer).await?;
}
{
let inner = socket.inner.engine.clone();
let initial_mtu = socket.inner.config.mtu;
tokio::spawn(async move {
let discovered = tokio::time::timeout(
Duration::from_secs(5),
mtu::probe(&inner, peer, initial_mtu),
)
.await
.unwrap_or(initial_mtu);
if let Some(p) = inner.peers.get(&peer) {
p.set_effective_mtu(discovered);
}
tracing::info!(target: "zudp::mtu", peer = %peer, mtu = discovered, "path MTU discovered");
});
}
Ok(ZudpConn { socket, peer: peer_addr })
}
}
struct Inner {
engine: Arc<EngineInner>,
config: Arc<Config>,
next_msg_id: AtomicU32,
_shutdown: tokio::sync::oneshot::Sender<()>,
}
impl Inner {
async fn new(
config: Config,
) -> Result<(Arc<Self>, mpsc::Receiver<(Bytes, SocketAddr, u16)>), Error> {
let addr = SocketAddr::new(config.bind_ip, config.port);
let socket = RawSocket::bind(addr).await?;
let config = Arc::new(config);
let engine = Arc::new(EngineInner {
socket: RwLock::new(socket),
peers: DashMap::new(),
sessions: DashMap::new(),
config: config.clone(),
#[cfg(feature = "security")]
keypair: config.security.clone(),
shutdown_reason: parking_lot::Mutex::new(None),
dropped_rate_limited: AtomicU64::new(0),
dropped_peer_cap: AtomicU64::new(0),
dropped_relay_blocked: AtomicU64::new(0),
dropped_relay_cap: AtomicU64::new(0),
relay_policy: RwLock::new(engine::RelayPolicy {
allowlist: config.relay_allowlist.clone(),
max_entries: config.max_relay_entries,
}),
});
let (shutdown_tx, shutdown_rx) = tokio::sync::oneshot::channel::<()>();
let rx = engine::spawn(engine.clone(), shutdown_rx);
let inner = Arc::new(Self {
engine,
config,
next_msg_id: AtomicU32::new(0),
_shutdown: shutdown_tx,
});
Ok((inner, rx))
}
#[cfg(feature = "security")]
async fn initiate_handshake(&self, peer_addr: SocketAddr) -> Result<(), Error> {
use security::build_initiator;
let kp = self
.config
.security
.as_ref()
.expect("called only when security is Some");
let mut hs = build_initiator(kp)?;
let mut buf = vec![0u8; 1024];
let n = hs.write_message(&[], &mut buf)?;
buf.truncate(n);
let wire = Frame::Handshake {
payload: Bytes::from(buf),
}
.encode();
let peer = self.get_or_create_peer(peer_addr);
let notified = peer.channel_ready.notified();
self.engine.get_socket().send_to(&wire, peer_addr).await?;
*peer.handshake.lock() = Some(hs);
if peer.channel.get().is_none() {
notified.await;
}
Ok(())
}
fn alloc_msg_id(&self) -> u32 {
self.next_msg_id.fetch_add(1, Ordering::Relaxed)
}
fn get_or_create_peer(&self, addr: SocketAddr) -> Arc<PeerState> {
self.engine.get_or_create_peer(addr)
}
async fn send_msg<M: Encode>(
&self,
msg: &M,
dest: SocketAddr,
reliable: bool,
stream_id: u16,
) -> Result<(), Error> {
let payload = Bytes::from(msg.encode_to_bytes()?);
let actual_dest = self.config.relay_addr.unwrap_or(dest);
let wrap_relay = self.config.relay_addr.is_some();
let reliable = reliable && self.config.reliable;
let peer = self.get_or_create_peer(dest);
let mtu = peer.effective_mtu_or(self.config.mtu);
if payload.len() <= mtu {
self.send_single(payload, peer, actual_dest, wrap_relay, reliable, stream_id)
.await
} else {
self.send_fragmented(payload, peer, actual_dest, wrap_relay, stream_id, mtu)
.await
}
}
async fn send_single(
&self,
payload: Bytes,
peer: Arc<PeerState>,
actual_dest: SocketAddr,
wrap_relay: bool,
reliable: bool,
stream_id: u16,
) -> Result<(), Error> {
if reliable {
let seq = peer.alloc_seq(stream_id);
let plain_frame = Frame::Stream {
seq,
stream_id,
payload,
}
.encode();
let inner_wire = maybe_encrypt(&peer, &plain_frame)?;
let wire = if wrap_relay {
Frame::Relay {
dest: peer.addr(),
inner: inner_wire,
}
.encode()
} else {
inner_wire
};
peer.cc.lock().consume(wire.len());
self.engine.get_socket().send_to(&wire, actual_dest).await?;
peer.record_sent(stream_id, seq, plain_frame);
} else if wrap_relay {
let frame = Frame::Datagram(payload).encode();
let wire = Frame::Relay {
dest: peer.addr(),
inner: frame,
}
.encode();
self.engine.get_socket().send_to(&wire, actual_dest).await?;
} else {
let type_tag = [frame::TYPE_DATAGRAM];
self.engine
.get_socket()
.send_to_vectored(
&[
std::io::IoSlice::new(&payload),
std::io::IoSlice::new(&type_tag),
],
actual_dest,
)
.await?;
}
Ok(())
}
async fn send_fragmented(
&self,
payload: Bytes,
peer: Arc<PeerState>,
actual_dest: SocketAddr,
wrap_relay: bool,
stream_id: u16,
mtu: usize,
) -> Result<(), Error> {
let chunks = fragment(&payload, mtu)?;
let msg_id = self.alloc_msg_id();
let frag_total = u16::try_from(chunks.len()).map_err(|_| Error::MessageTooLarge {
got: chunks.len(),
max: frag::MAX_FRAGMENTS,
})?;
for (frag_idx, chunk) in (0u16..).zip(chunks) {
let seq = peer.alloc_seq(stream_id);
let plain_frame = Frame::Fragment {
msg_id,
frag_idx,
frag_total,
seq,
stream_id,
payload: chunk,
}
.encode();
let inner_wire = maybe_encrypt(&peer, &plain_frame)?;
let wire = if wrap_relay {
Frame::Relay {
dest: peer.addr(),
inner: inner_wire,
}
.encode()
} else {
inner_wire
};
peer.cc.lock().consume(wire.len());
self.engine.get_socket().send_to(&wire, actual_dest).await?;
peer.record_sent(stream_id, seq, plain_frame);
}
Ok(())
}
}
#[allow(clippy::unnecessary_wraps)]
fn maybe_encrypt(peer: &PeerState, plain: &Bytes) -> Result<Bytes, Error> {
#[cfg(feature = "security")]
if let Some(channel) = peer.channel.get() {
let (nonce, ct) = channel.encrypt(plain)?;
return Ok(Frame::Secure {
nonce,
ciphertext: Bytes::from(ct),
}
.encode());
}
let _ = peer;
Ok(plain.clone())
}
pub struct ZudpSocket<M> {
inner: Arc<Inner>,
rx: mpsc::Receiver<(Bytes, SocketAddr, u16)>,
_phantom: PhantomData<fn() -> M>,
}
impl<M> ZudpSocket<M> {
async fn new(config: Config) -> Result<Self, Error> {
let (inner, rx) = Inner::new(config).await?;
Ok(Self {
inner,
rx,
_phantom: PhantomData,
})
}
#[must_use = "the address is returned, not printed"]
pub fn local_addr(&self) -> Result<SocketAddr, Error> {
self.inner.engine.get_socket().local_addr()
}
#[must_use]
pub fn peer_srtt(&self, peer: SocketAddr) -> Option<Duration> {
self.inner.engine.peers.get(&peer)?.cc.lock().srtt()
}
#[must_use]
pub fn peer_congestion_factor(&self, peer: SocketAddr) -> Option<f64> {
self.inner.engine.peers.get(&peer)?.cc.lock().congestion_factor()
}
#[must_use]
pub fn peer_stats(&self, peer: SocketAddr) -> Option<PeerStats> {
let p = self.inner.engine.peers.get(&peer)?.value().clone();
let (srtt, congestion_factor, pacing_rate_bps) = {
let cc = p.cc.lock();
#[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
let rate = cc.pacing_rate() as u64;
(cc.srtt(), cc.congestion_factor(), rate)
};
Some(PeerStats {
srtt,
congestion_factor,
pacing_rate_bps,
rx_bytes: p.rx_bytes.load(Ordering::Relaxed),
tx_bytes: p.tx_bytes.load(Ordering::Relaxed),
retransmit_count: p.retransmit_count.load(Ordering::Relaxed),
})
}
#[must_use]
pub fn engine_stats(&self) -> EngineStats {
let e = &self.inner.engine;
EngineStats {
dropped_rate_limited: e.dropped_rate_limited.load(Ordering::Relaxed),
dropped_peer_cap: e.dropped_peer_cap.load(Ordering::Relaxed),
dropped_relay_blocked: e.dropped_relay_blocked.load(Ordering::Relaxed),
dropped_relay_cap: e.dropped_relay_cap.load(Ordering::Relaxed),
}
}
#[must_use]
pub fn sender(&self) -> ZudpSender {
ZudpSender { inner: self.inner.clone() }
}
#[cfg(feature = "security")]
#[must_use]
pub fn peer_remote_static_key(&self, peer: SocketAddr) -> Option<[u8; 32]> {
self.inner
.engine
.peers
.get(&peer)
.and_then(|p| p.remote_static_key().copied())
}
pub fn set_relay_policy(&self, allowlist: Vec<IpAddr>, max_entries: usize) {
let mut p = self.inner.engine.relay_policy.write();
p.allowlist = allowlist;
p.max_entries = max_entries;
}
pub async fn send(&self, msg: M, peer: SocketAddr) -> Result<(), Error>
where
M: Encode,
{
self.inner.send_msg(&msg, peer, true, DEFAULT_STREAM).await
}
pub async fn send_stream(&self, msg: M, peer: SocketAddr, stream_id: u16) -> Result<(), Error>
where
M: Encode,
{
self.inner.send_msg(&msg, peer, true, stream_id).await
}
pub async fn send_unreliable(&self, msg: M, peer: SocketAddr) -> Result<(), Error>
where
M: Encode,
{
self.inner.send_msg(&msg, peer, false, DEFAULT_STREAM).await
}
pub async fn recv(&mut self) -> Result<Packet<M>, Error>
where
M: Decode,
{
loop {
let Some((bytes, from, stream)) = self.rx.recv().await else {
let reason = self
.inner
.engine
.shutdown_reason
.lock()
.clone()
.unwrap_or_else(|| "channel closed".into());
return Err(Error::EngineStopped { reason });
};
match M::decode_from_bytes(&bytes) {
Ok(msg) => return Ok(Packet { msg, from, stream }),
Err(e) => {
tracing::warn!(target: "zudp", peer = %from, "decode failed: {e}");
}
}
}
}
}
pub struct ZudpConn<M> {
socket: ZudpSocket<M>,
peer: Arc<RwLock<SocketAddr>>,
}
impl<M> ZudpConn<M> {
#[must_use]
pub fn peer(&self) -> SocketAddr {
*self.peer.read()
}
#[must_use = "the address is returned, not printed"]
pub fn local_addr(&self) -> Result<SocketAddr, Error> {
self.socket.local_addr()
}
#[must_use]
pub fn effective_mtu(&self) -> Option<usize> {
self.socket
.inner
.engine
.peers
.get(&self.peer())
.map(|p| p.effective_mtu_or(0))
.filter(|&v| v != 0)
}
#[must_use]
pub fn srtt(&self) -> Option<Duration> {
self.socket.peer_srtt(self.peer())
}
#[must_use]
pub fn congestion_factor(&self) -> Option<f64> {
self.socket.peer_congestion_factor(self.peer())
}
#[must_use]
pub fn peer_stats(&self) -> Option<PeerStats> {
self.socket.peer_stats(self.peer())
}
#[must_use]
pub fn engine_stats(&self) -> EngineStats {
self.socket.engine_stats()
}
pub async fn send(&self, msg: M) -> Result<(), Error>
where
M: Encode,
{
self.socket.send(msg, self.peer()).await
}
pub async fn send_stream(&self, msg: M, stream_id: u16) -> Result<(), Error>
where
M: Encode,
{
self.socket.send_stream(msg, self.peer(), stream_id).await
}
pub async fn send_unreliable(&self, msg: M) -> Result<(), Error>
where
M: Encode,
{
self.socket.send_unreliable(msg, self.peer()).await
}
pub async fn recv(&mut self) -> Result<Packet<M>, Error>
where
M: Decode,
{
loop {
let pkt = self.socket.recv().await?;
let current = *self.peer.read();
if pkt.from == current {
return Ok(pkt);
}
tracing::debug!(
target: "zudp",
unexpected = %pkt.from,
expected = %current,
"dropping message from unexpected peer"
);
}
}
}