Module stream_multiplexer 

Stream Multiplexer — multiplexes multiple logical streams over a single connection with flow control, priority scheduling, and proper frame lifecycle management.

Design

Each logical StreamId carries its own sequence counter, send/receive windows, and priority. The shared send queue is a max-BinaryHeap keyed on (priority_weight, Reverse(enqueue_sequence)) so that within the same priority tier frames are emitted in FIFO order.

Frame flags (FrameFlags bit positions)

Bit	Name	Value	Meaning
0	SYN	0x01	Open (create) a new stream
1	FIN	0x02	Close stream after this frame
2	RST	0x04	Reset stream immediately
3	ACK	0x08	Acknowledgement
4	DATA	0x10	Frame carries payload data

Legacy flag constants (raw u8)

For backwards compatibility the original raw constants are preserved: FLAG_FIN=0x01, FLAG_RST=0x02, FLAG_SYN=0x04.

Flow control

send_window tracks how many bytes may still be enqueued for sending on a given stream. Each call to StreamMultiplexer::send checks that data.len() <= send_window and deducts the amount from the window. StreamMultiplexer::update_window adds credits back (simulating receipt of a window-update ACK from the remote side).

Structs

FrameFlags

Bitfield wrapper for stream-frame control flags.

LogicalStream

State and bookkeeping for a single logical stream.

MultiplexerConfig

Configuration for StreamMultiplexer.

MultiplexerStats

Rich statistics snapshot for the multiplexer (task-spec version).

MuxStats

Compact snapshot of StreamMultiplexer statistics (original form).

StreamFrame

A framed unit of data for one logical stream.

StreamId

Newtype identifier for a logical stream.

StreamInfo

Read-only snapshot of per-stream statistics.

StreamMultiplexer

Multiplexes multiple logical streams over a single connection with flow control and priority-based scheduling.

Enums

MuxError

Errors returned by StreamMultiplexer operations.

MuxEvent

Events emitted by StreamMultiplexer::receive and other operations.

StreamPriority

Priority level for a logical stream.

StreamState

Lifecycle state of a logical stream.

Constants

FLAG_FIN

Bit mask for the FIN flag in StreamFrame::flags (legacy raw u8 form).

FLAG_RST

Bit mask for the RST flag in StreamFrame::flags (legacy raw u8 form).

FLAG_SYN

Bit mask for the SYN flag in StreamFrame::flags (legacy raw u8 form).

Functions

priority_from_u8

Convert a raw priority byte (0-255) to the nearest StreamPriority tier.

xorshift64

Xorshift64 PRNG — seedable, dependency-free random number source for tests.