Expand description
§ZUDP — Zero UDP
A minimal, low-overhead UDP protocol with optional reliability, fragmentation, keepalives, end-to-end encryption, and relayed sessions with hole punching.
§Quick start
use zudp::wincode::{SchemaRead, SchemaWrite};
use zudp::Zudp;
#[derive(SchemaWrite, SchemaRead)]
#[wincode(crate = "zudp::wincode")]
enum Msg { Ping, Pong, Data(Vec<u8>) }
#[tokio::main]
async fn main() -> anyhow::Result<()> {
// Multi-peer socket — type on the terminal call
let mut socket = Zudp::default().port(5000).listen::<Msg>().await?;
let pkt = socket.recv().await?; // pkt.msg, pkt.from, pkt.stream
// Single-peer connection
let mut conn = Zudp::default().port(0).connect::<Msg>("1.2.3.4:5000".parse()?).await?;
conn.send(Msg::Ping).await?;
let pkt = conn.recv().await?; // pkt.msg, pkt.from (== peer), pkt.stream
Ok(())
}§Peers, direct and relayed
Peers are named by PeerAddr. A direct peer is its UDP address — every method that
takes a peer accepts a SocketAddr through impl Into<PeerAddr>. With the security
feature, a client connected to a relay node (a socket built with Zudp::relay_node,
relay feature) reaches other clients of that relay by static public key with
ZudpSocket::connect_via; the session is end-to-end encrypted, the relay only forwards
ciphertext, and hole punching moves it onto a direct path when NAT allows. Such a peer
is a PeerAddr::Relayed handle that stays the same whichever path its traffic takes.
Structs§
- Config
- Protocol configuration, built via
Zudp. - Engine
Stats - Engine-wide drop counters. Returned by
ZudpSocket::engine_stats. - Packet
- A message received from a ZUDP socket, together with its origin and stream.
- Peer
Events - A subscription to
PeerEvents. - Peer
Stats - Per-peer statistics snapshot. Returned by
ZudpSocket::peer_stats. - RawBytes
- Raw byte passthrough codec. Encodes by copying the
Bytesto aVec; decodes by copying the slice into a newBytes. Use this when you want to own the framing yourself and have zudp treat the payload as opaque. - Zudp
- Entry point for constructing a ZUDP socket.
- Zudp
Conn - A ZUDP socket bound to a single remote peer.
- Zudp
Sender - A clonable send handle for a
ZudpSocket. - Zudp
Socket - A ZUDP socket that sends and receives messages from any remote peer.
Enums§
- Disconnect
Reason - Why a
PeerEvent::Disconnectedwas emitted. - Error
- Path
- The network path a session’s traffic currently takes. See
PeerEvent::PathChanged. - Peer
Addr - Handle for one remote peer.
- Peer
Event - Something happened to a remote peer.
Constants§
- DEFAULT_
STREAM - Stream ID for the default reliable channel. Pass to
send_stream/recv_streamor usesend/recvwhich implicitly target this stream. - WIRE_
VERSION - Version of the session wire protocol, carried in every handshake message.