Expand description
§peaplex
A profoundly minimal, zero-copy stream multiplexer. Pluggable onto any
AsyncRead + AsyncWrite connection - a tokio::net::TcpStream, the two
halves of a tokio::io::duplex, a TLS-wrapped stream, a pea2pea
connection (see examples/pea2pea.rs), etc.
§What it is
A single duplex connection between two peers carries a peaplex session.
That session exposes an arbitrary number of independent, ordered,
full-duplex substreams that look like tokio::io byte streams.
§Design
Four frame types (Open, Data, Close, GoAway) and a 9-byte
header. No per-stream flow-control windows, no keepalive pings, no
half-close, no SYN/ACK/FIN round-trips. peaplex moves frames;
any policy on top (flow control, backpressure, quotas) belongs to the
layer above.
There are two ways to use the crate, and the choice decides whether you can enforce flow control and memory bounds:
Multiplexer- the convenience path. It owns the transport and the dispatch loop; you getopen_stream/accept/Streamfor free, but the per-substream receive buffers are unbounded and there is no admission hook, so you cannot push back on a flooding peer from outside the API. Use it when you trust the peer or an outer layer already bounds traffic.Frame+FrameCodec- the control path. Plug the codec into your own read/write loop and you own dispatch, so you can cap per-substream buffers, drop/Closemisbehaving substreams, or apply socket backpressure.examples/pea2pea.rsis a complete worked example.
Note: peaplex has no protocol-level flow control (no window/credit
frame). Cooperative flow control is an application concern you can run
inside Data payloads on either path; defensively bounding a hostile
peer requires owning dispatch, i.e. the control path. peaplex also
speaks only to peaplex - the wire format is its own and is not
compatible with yamux, mplex, or any other multiplexer.
§Wire format
+--------+-------------------------------------------------+
| Flag | Stream ID | (1 + 4 bytes)
+--------+-------------------------------------------------+
| Length (bytes) | (4 bytes)
+----------------------------------------------------------+
| Payload (Length bytes) | (0..16 MiB)
+----------------------------------------------------------+| Flag | Value | Meaning |
|---|---|---|
| Open | 0x01 | announces a new substream |
| Data | 0x02 | carries a chunk of substream payload |
| Close | 0x04 | tears down a substream in both directions |
| GoAway | 0x08 | tears down the entire connection |
Stream IDs are partitioned by side to avoid collisions: the dialing
side (Side::Initiator) mints odd IDs starting at 1; the listening
side (Side::Responder) mints even IDs starting at 2. 0 is
reserved.
§Zero copy
Payloads are wrapped in bytes::Bytes, a refcounted view onto the
underlying read buffer. Decoding a frame is O(1) and never copies
the payload; an inbound Data chunk is delivered to the user as a
slice of the same memory the kernel handed us.
§Usage
use peaplex::{Multiplexer, Side};
use tokio::io::duplex;
async fn run() {
// Any AsyncRead + AsyncWrite will do. Here we use an in-memory
// duplex pair just to make the example self-contained.
let (a, b) = duplex(64 * 1024);
let a = Multiplexer::new(a, Side::Initiator);
let b = Multiplexer::new(b, Side::Responder);
// Spawn an accept-loop on b.
tokio::spawn(async move {
let mut s = b.accept().await.unwrap();
// ... use `s` as an AsyncRead + AsyncWrite
});
// Open a stream from a and write something.
let mut s = a.open_stream().unwrap();
// ... use `s` as an AsyncRead + AsyncWrite
}For the pea2pea integration, see examples/pea2pea.rs.
Structs§
- Accept
- Future returned by
Multiplexer::accept. - Frame
- A single decoded peaplex frame.
- Frame
Codec - A stateless
Decoder/Encoderfor peaplex frames. - Multiplexer
- A zero-copy peaplex session running on top of an
AsyncRead + AsyncWriteconnection. - Stream
- A single peaplex substream.
- Stream
Id - Identifier of a single substream within a peaplex connection.
Enums§
- Flag
- The kind of message carried by a
Frame. - Side
- Which side of the underlying connection this
Multiplexeris.
Constants§
- FLAG_
CLOSE - Flag byte for a
Closeframe. - FLAG_
DATA - Flag byte for a
Dataframe. - FLAG_
GOAWAY - Flag byte for a
GoAwayframe. - FLAG_
OPEN - Flag byte for an
Openframe. - FRAME_
HEADER_ LEN - Size in bytes of the peaplex frame header.
- MAX_
FRAME_ PAYLOAD - Maximum size in bytes of a single frame’s payload (16 MiB).