Expand description
§ZettaTransport
ZettaTransport is an experimental, encrypted, multiplexed transport protocol over UDP. It provides reliable ordered streams, unreliable datagrams, Tokio asynchronous I/O, congestion control, flow control, path validation, and path-MTU discovery.
Experimental software: this crate implements a custom protocol, not QUIC. It has not received an independent security audit and is not intended for production or mission-critical deployments. Prefer a standards-based QUIC implementation when interoperability or production assurance is required.
§Start here
Most applications use these types:
ZtEndpointowns a UDP socket and creates connections.ZtConnectionHandleopens/accepts streams and sends datagrams.ZtStreamis a reliable ordered byte stream implementingtokio::io::AsyncReadandtokio::io::AsyncWrite.ZtConfigcontrols timeouts, limits, MTU discovery, security, and congestion control.ZtErrorexposes typed transport failures.
Add the crate and the Tokio runtime to your project:
[dependencies]
zetta-transport = "0.1.26"
tokio = { version = "1", features = ["full"] }
bytes = "1"§Echo server
The endpoint is reference-counted. Each accepted connection owns its incoming stream queue, and every accepted stream can be processed in its own task.
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use zetta_transport::transport::endpoint::ZtEndpoint;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let endpoint = ZtEndpoint::bind("0.0.0.0:4433", None).await?;
println!("listening on {}", endpoint.local_addr()?);
while let Some(mut connection) = endpoint.accept().await {
tokio::spawn(async move {
while let Some(mut stream) = connection.accept_stream().await {
tokio::spawn(async move {
let mut buffer = [0_u8; 16 * 1024];
loop {
let read = match stream.read(&mut buffer).await {
Ok(0) | Err(_) => break,
Ok(read) => read,
};
if stream.write_all(&buffer[..read]).await.is_err() {
break;
}
}
});
}
});
}
Ok(())
}§Client
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use zetta_transport::transport::endpoint::ZtEndpoint;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let endpoint = ZtEndpoint::bind("0.0.0.0:0", None).await?;
let connection = endpoint.connect("127.0.0.1:4433".parse()?).await?;
let mut stream = connection.open_stream().await?;
stream.write_all(b"hello").await?;
stream.flush().await?;
let mut reply = [0_u8; 5];
stream.read_exact(&mut reply).await?;
assert_eq!(&reply, b"hello");
Ok(())
}§Streams and datagrams
stream::ZtConnectionHandle::open_stream creates a bidirectional stream. Use
stream::ZtConnectionHandle::open_stream_with_type for a send-only stream. A receive-only
stream is created locally when the peer opens a send-only stream; it cannot be opened directly.
Dropping or calling stream::ZtStream::close gracefully finishes a stream. Use
stream::ZtStream::reset to terminate it with an application error code.
Datagrams are encrypted and congestion-controlled but are not ordered or retransmitted. They are appropriate only when losing an individual message is acceptable.
§Preserving close reasons
Convenience receive methods return Option and collapse termination into None. Applications
that need the exact cause should use stream::ZtStream::recv_result,
stream::ZtConnectionHandle::accept_stream_result, and
stream::ZtConnectionHandle::recv_datagram_result. These methods preserve peer reset codes,
peer connection-close reasons, and idle timeouts.
§Authentication
Every endpoint creates an Ed25519 identity at bind time and uses ephemeral X25519 keys for each
connection. By default, cryptographic identity proves handshake integrity but is not tied to a
trusted name. Experiments that need peer authentication should install a verifier with
transport::endpoint::ZtEndpoint::set_peer_key_verifier and may additionally configure a
shared 32-byte PSK through config::ZtConfig::psk. Endpoint identities are currently
ephemeral unless the application pins and redistributes the exposed public key itself.
§Protocol compatibility
Version 0.1.26 speaks ZettaTransport wire protocol version 2. Version 2 is intentionally not wire-compatible with earlier crate releases: it signs transport parameters, transmits stream direction on the wire, and includes a final byte offset in graceful stream closure.
See the crate modules below for the complete API and the repository’s DOCUMENTATION.md for
packet/frame layout and protocol internals.
Modules§
- config
- Endpoint configuration and validation. Validated endpoint configuration.
- error
- Public error and result types. Errors returned by endpoint, connection, and stream operations.
- fuzzing
- Narrow test-only entry points used by the out-of-process fuzz targets.
- simulation
- Deterministic endpoint-scoped network fault injection for tests. Deterministic network fault injection for integration tests.
- stats
- Connection telemetry snapshots. Read-only connection telemetry.
- stream
- Connection and stream application APIs. Application-facing connection and reliable stream handles.
- transport
- Endpoint construction, stream direction, and congestion-control selection. Transport endpoint and policy types.