bookclerk_plugin_sdk::mux
Bidirectional multiplexed byte streams with per-stream credit windows.
Used for the native-behind-workerd socket proxy (guest Mux::open,
gateway Mux::accept) and the OAuth callback tunnel (host opens, guest
accepts). Either side may initiate; connection ids from a client are odd
and from a server are even so they cannot collide.
The peer is untrusted. Frame length is rejected before a payload buffer is
allocated. Each stream buffers at most MAX_BUFFERED_PER_STREAM unread
bytes, the connection buffers at most MAX_AGGREGATE_BUFFERED, and at
most MAX_LIVE_STREAMS stream objects exist. That cap covers streams
waiting in the accept queue and streams the peer has already closed: a
Close frame does not free the slot while the MuxStream is still
alive. Credit and close records for a generation stay reserved until the
writer drops both, so a blocked writer cannot accumulate them after the
map slot is released. A new Open is refused while either record vector or
that reservation table is already at the cap. Each slot has a generation
so dropping an old stream cannot remove a replacement that reused the id.
Window updates saturate at INITIAL_WINDOW and are coalesced until the
writer accepts them, so a full control queue cannot drop receive credit.
Close is written only after Data already accepted for that same stream.
Window updates and other streams' control frames are not stuck behind one
unread stream. A stream flush or shutdown waits until that stream's
accepted output is written. Mux::shutdown and dropping the last mux
cancel both tasks without draining queued frames.
Frame layout (big-endian):
u32 length_of_rest | u8 type | u32 conn_id | payload
Types: Open=1, Data=2, Close=3, Window=4. Data payloads are capped
at 1 MiB. A Window frame carries a u32 credit (bytes the peer may
send). Each stream starts with INITIAL_WINDOW bytes of send credit.
| Item | Kind | Summary |
|---|---|---|
Mux |
struct | One multiplexed endpoint. Cheap to clone (shared tasks + id allocator). |
MuxStream |
struct | One multiplexed logical connection implementing AsyncRead + AsyncWrite. |
live_mux_task_count |
function | In-process mux reader and writer tasks that have not returned. |
TYPE_OPEN |
constant | Frame type byte for opening a multiplexed connection. |
TYPE_DATA |
constant | Frame type byte for payload bytes on an open connection. |
TYPE_CLOSE |
constant | Frame type byte for closing a multiplexed connection. |
TYPE_WINDOW |
constant | Frame type byte for a credit-window update. |
MAX_FRAME_PAYLOAD |
constant | Maximum Data-frame payload in bytes (1 MiB); larger writes are split. |
INITIAL_WINDOW |
constant | Initial per-stream send credit, in bytes. |
MAX_BUFFERED_PER_STREAM |
constant | Unread bytes kept for one stream. Further Data is discarded and the stream is closed so the reader can still take Window and Close for others. |
MAX_AGGREGATE_BUFFERED |
constant | Unread bytes kept across every stream on one mux. |
MAX_LIVE_STREAMS |
constant | Live local and peer streams, including those not yet accepted. |
pub struct Mux {
/* private fields */
}
One multiplexed endpoint. Cheap to clone (shared tasks + id allocator).
Clones share one task owner. Dropping a clone does not stop the reader or
writer while another clone remains. Dropping the last clone, or calling
Mux::shutdown, cancels both tasks even if the peer is still connected.
pub fn client<R, W>(reader: R, writer: W) -> Self
where
R: AsyncRead + Send + Unpin + 'static,
W: AsyncWrite + Send + Unpin + 'static,
Client endpoint (odd connection ids). Socket-proxy guests and OAuth hosts.
pub fn server<R, W>(reader: R, writer: W) -> Self
where
R: AsyncRead + Send + Unpin + 'static,
W: AsyncWrite + Send + Unpin + 'static,
Server endpoint (even connection ids). Socket-proxy gateway and OAuth guests.
pub fn shutdown(&self)
Stop the reader and writer even if other clones of this mux still exist.
The peer does not have to hang up. Self::closed resolves when both
tasks have left their loops and dropped the transport.
pub fn closed(&self) -> impl Future<Output = ()> + Send + 'static
Wait until the reader and writer tasks have finished.
The returned future does not hold this mux. Dropping the last owner while it is pending still cancels tasks that have not been polled.
pub async fn open(&self) -> Result<MuxStream>
Open a logical stream toward the peer.
Returns SdkError when the writer task has exited or the live-stream
cap is already full.
pub async fn accept(&self) -> Result<MuxStream>
Wait for the next logical stream opened by the peer.
Returns SdkError when the reader task exits (peer hangup or bad frame).
Implements: Clone
pub struct MuxStream {
/* private fields */
}
One multiplexed logical connection implementing AsyncRead + AsyncWrite.
pub fn id(&self) -> u32
Stable connection id shared with the peer for this logical stream.
Implements: AsyncRead, AsyncWrite, Drop
pub fn live_mux_task_count() -> usize
In-process mux reader and writer tasks that have not returned.
pub const TYPE_OPEN: u8 = 1;
Frame type byte for opening a multiplexed connection.
pub const TYPE_DATA: u8 = 2;
Frame type byte for payload bytes on an open connection.
pub const TYPE_CLOSE: u8 = 3;
Frame type byte for closing a multiplexed connection.
pub const TYPE_WINDOW: u8 = 4;
Frame type byte for a credit-window update.
pub const MAX_FRAME_PAYLOAD: usize = _;
Maximum Data-frame payload in bytes (1 MiB); larger writes are split.
pub const INITIAL_WINDOW: u32 = _;
Initial per-stream send credit, in bytes.
pub const MAX_BUFFERED_PER_STREAM: usize = _;
Unread bytes kept for one stream. Further Data is discarded and the stream
is closed so the reader can still take Window and Close for others.
pub const MAX_AGGREGATE_BUFFERED: usize = _;
Unread bytes kept across every stream on one mux.
pub const MAX_LIVE_STREAMS: usize = 32;
Live local and peer streams, including those not yet accepted.
Generated from crates/bookclerk-plugin-sdk at main · View as Markdown