zudp
Minimal UDP protocol for real-time applications. NACK-based reliability, automatic fragmentation, relay/NAT traversal, RTT-based congestion control, optional end-to-end encryption, and optional LAN discovery.
Quick start
use ;
use Zudp;
// listener — accepts any peer
let mut socket = default.port..await?;
let pkt = socket.recv.await?; // pkt.msg, pkt.from, pkt.stream
socket.send.await?;
// single-peer connection
let mut conn = default.port..await?;
conn.send.await?;
let pkt = conn.recv.await?; // pkt.msg, pkt.from (== peer), pkt.stream
Builder options
default
.port // 0 = OS-assigned
.bind_ip // default: 0.0.0.0
.reliable // NACK retransmission on/off
.mtu // fragmentation threshold in bytes
.keepalive_interval
.relay // wrap every packet in a relay header
.security // enable Noise XX encryption
.pin_remote_key // reject peers with wrong key
.max_peers // LRU-evict oldest peer at cap
.rate_limit // per-IP token-bucket PPS (0.0 = off)
.relay_allowlist // restrict who may use this node as relay
.max_relay_entries // relay routing table cap
. // ZudpSocket<Msg> — multi-peer
. // ZudpConn<Msg> — single-peer
Multiple streams
Each reliable connection supports up to 65 535 independent ordered streams. Streams have separate sequence spaces, so packet loss on one stream never delays delivery on another (no head-of-line blocking).
// server
let pkt = socket.recv.await?;
socket.send_stream.await?; // reply on same stream
// client: send to specific stream
conn.send_stream.await?; // stream 0 — commands
conn.send_stream.await?; // stream 1 — snapshots
let pkt = conn.recv.await?; // pkt.stream tells which
DEFAULT_STREAM = 0. send() / recv() target stream 0 — existing code continues to work unchanged.
Congestion control
Built-in BBR-lite per peer — RTT-based, not loss-based, so it detects queue build-up before drops occur.
- RTT measured from Ping/Pong echo timestamps; EWMA smoothed.
- Pacing rate adjusts: backs off when
srtt > 1.25 × min_rtt, probes up otherwise. - 65 KB burst allowance covers typical game state syncs without any delay.
- NACK retransmits are paced (up to 10 ms inter-send); new sends are never delayed.
// query congestion state on a conn
if let Some = conn.srtt
if let Some = conn.congestion_factor
// same on a multi-peer socket
if let Some = socket.peer_srtt
Observability
ZudpSocket and ZudpConn expose live stats with no lock contention (all atomics):
// Per-peer snapshot — None if the peer is not in the table.
if let Some = socket.peer_stats
// Engine-wide drop counters (monotonically increasing since socket creation).
let e = socket.engine_stats;
println!;
dropped_peer_cap increments each time the peer table is full and an LRU eviction occurs.
dropped_rate_limited, dropped_relay_blocked, dropped_relay_cap are self-explanatory.
Hardening
All limits are enforced on the receive path, require no peer cooperation, and are configurable at build time:
// Per-IP rate limit — token bucket, default 1000 pps / 200 burst.
// Set to 0.0 to disable.
default.rate_limit …
// Peer table cap — evicts least-recently-seen peer when full.
default.max_peers …
// Relay allowlist — empty means open relay (default); non-empty restricts relay use.
default
.relay_allowlist
.max_relay_entries …
// Update relay policy at runtime without rebinding the socket.
socket.set_relay_policy;
Fragment bombs are also capped: frag_total > 1 024 and more than 64 concurrent assemblies per (peer, stream) are rejected at the engine level before any allocation occurs.
End-to-end encryption
Requires features = ["security"]. Uses Noise XX with X25519 DH, ChaCha20-Poly1305 AEAD, and BLAKE2s — the same cryptography as WireGuard. Mutual authentication: both sides verify each other's public key.
use ;
// Generate a keypair once and persist it (e.g. to disk).
let keypair = generate;
// Server — listen with security enabled.
let mut socket = default
.port
.security
.
.await?;
// Client — connect; Noise XX handshake completes before connect() returns.
let mut conn = default
.port
.security
.
.await?;
// Send/recv API is identical — encryption is transparent.
conn.send.await?;
let pkt = conn.recv.await?;
All three Noise handshake messages complete inside connect() — the channel is encrypted and ready before the first send(). Once the channel is established, all frame types are wrapped in Secure except Datagram (unreliable fire-and-forget) and routing/discovery frames (Relay, Probe, Beacon, Handshake). This includes Ping/Pong keepalives (which carry session IDs) and Nack frames (which expose sequence timing) — encrypting them prevents replay-based migration attacks and traffic analysis. NACK retransmits re-encrypt the original plaintext with a fresh nonce; the old ciphertext is never re-sent.
LAN discovery
Requires features = ["discovery"].
use ;
// advertise — responds to probes from scanners on the same LAN
let handle = advertise?;
handle.set_meta; // hot-swap
// scan once — collect all peers that reply within a timeout
let peers = .await?;
// scan continuously — yields each new peer exactly once
let mut stream = .await?;
let peer = stream.next.await?;
// connect to peer.data_addr via Zudp::connect
DiscoveryConfig builder: .discovery_port(u16), .probe_interval(Duration).
AppId is derived from the app name string via a stable FNV-1a hash.
Relay
The relay node is a plain ZudpSocket — no special configuration needed.
The relay is stateful and bidirectional: when a client sends through it, the relay records a routing table entry so server replies are automatically forwarded back to the client.
// client — wrap every packet via relay
let conn = default
.relay
.
.await?;
// relay node — just a listening socket; routing table maintained automatically by the engine
let _relay = default.port..await?;
// (relay doesn't need to call recv() — the engine handles all forwarding internally)
Server replies flow back through the relay to the client without any extra configuration. When the client migrates to a new network, the relay table is updated automatically on the next outbound packet.
Network migration
When the local interface changes (WiFi → mobile, DHCP renew, VPN toggle), ZUDP restores the session automatically:
- Engine detects the socket error and rebinds to a new interface.
- Engine sends keepalive Pings carrying a per-peer session ID to all known peers.
- Each peer recognises the session ID and migrates the client's address in its peer table.
- Traffic resumes — no reconnect, no application-level handling required.
Works for client→server topologies where the server has a public IP. P2P connections where both peers are behind NAT require a relay.
License
MIT