Struct StreamMultiplexer 

pub struct StreamMultiplexer {
    pub config: MultiplexerConfig,
    /* private fields */
}

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

Example

use ipfrs_network::stream_multiplexer::{
    MultiplexerConfig, StreamMultiplexer, StreamPriority,
};

let config = MultiplexerConfig::default();
let mut mux = StreamMultiplexer::new(config);

let sid = mux.open_stream(StreamPriority::Normal).expect("open stream");
let bytes = mux.send(sid, b"hello world".to_vec(), 0).expect("send");
assert_eq!(bytes, 11);

// Drain all enqueued frames (SYN + data)
let frames = mux.dequeue_frames(10);
assert_eq!(frames.len(), 2);

Fields

config: MultiplexerConfig

Effective configuration for this multiplexer instance.

Implementations

impl StreamMultiplexer

pub fn new(config: MultiplexerConfig) -> Self

Create a new multiplexer with the given configuration.

pub fn open_stream( &mut self, priority: StreamPriority, ) -> Result<StreamId, MuxError>

Open a new logical stream with the specified priority.

A SYN frame (flags = FLAG_SYN) is immediately enqueued.

Errors

Returns MuxError::MaxStreamsReached if MultiplexerConfig::max_streams streams are already open.

pub fn open_stream_with_priority( &mut self, priority_raw: u8, ) -> Result<StreamId, MuxError>

Open a new logical stream with a raw priority byte (0-255).

The raw byte is mapped to the nearest StreamPriority tier via priority_from_u8. The raw value is preserved in LogicalStream::priority_raw.

Errors

Returns MuxError::MaxStreamsReached if the maximum stream count is exceeded.

pub fn close_stream(&mut self, stream_id: StreamId) -> Result<(), MuxError>

Send a FIN frame and transition the stream to StreamState::HalfClosed.

Errors

• MuxError::StreamNotFound if the stream does not exist.
• MuxError::StreamNotOpen if the stream is already Closed or Reset.

pub fn reset_stream(&mut self, stream_id: StreamId) -> Result<(), MuxError>

Send an RST frame and transition the stream to StreamState::Reset.

Errors

• MuxError::StreamNotFound if the stream does not exist.

pub fn send( &mut self, stream_id: StreamId, data: Vec<u8>, now: u64, ) -> Result<usize, MuxError>

Fragment data into frames of at most MultiplexerConfig::max_frame_size bytes and enqueue them on the send queue.

Returns the total number of bytes enqueued.

Errors

• MuxError::StreamNotFound if the stream does not exist.
• MuxError::StreamNotOpen if the stream is not StreamState::Open.
• MuxError::WindowExhausted if data.len() exceeds the remaining send window.

pub fn receive_events( &mut self, frame: StreamFrame, now: u64, ) -> Result<Vec<MuxEvent>, MuxError>

Process an incoming frame from the remote peer.

Returns a list of MuxEvents describing what happened:

• SYN → MuxEvent::StreamOpened (opens the stream if not present)
• DATA → MuxEvent::FrameReceived (payload buffered in recv buffer)
• FIN → MuxEvent::StreamClosed
• RST → MuxEvent::StreamReset
• Recv buffer full → MuxEvent::SendBufferFull (frame dropped, counted in dropped_frames)

Errors

• MuxError::StreamNotFound if the stream is unknown and frame is not SYN.
• MuxError::SequenceError if the frame arrives out of order.

pub fn receive( &mut self, frame: StreamFrame, _now: u64, ) -> Result<Vec<u8>, MuxError>

Process an incoming frame from the remote peer (original API).

Handles RST, FIN, and data frames. Returns the payload bytes.

Errors

• MuxError::StreamNotFound if the stream is unknown.
• MuxError::SequenceError if the frame arrives out of order.

pub fn drain_recv_buffer( &mut self, stream_id: StreamId, ) -> Result<Vec<Vec<u8>>, MuxError>

Drain all buffered receive payloads for stream_id.

Returns a Vec of payload byte vectors in arrival order. The receive buffer is emptied after this call.

Errors

Returns MuxError::StreamNotFound if the stream does not exist.

pub fn dequeue_frame(&mut self) -> Option<StreamFrame>

Pop the highest-priority frame from the send queue.

Updates total_frames_sent. For data frames (no control flags), the stream’s send_window has already been decremented in send; no further deduction is needed here.

pub fn dequeue_frames(&mut self, n: usize) -> Vec<StreamFrame>

Pop up to n frames from the send queue in priority order.

pub fn drain_send_queue(&mut self) -> Vec<StreamFrame>

Drain all pending outbound frames across all streams in priority order.

Equivalent to calling dequeue_frames with usize::MAX, but more efficient since it drains the heap directly.

pub fn expire_idle(&mut self, current_ts: u64) -> Vec<MuxEvent>

Expire streams that have been idle longer than MultiplexerConfig::idle_timeout_us.

A stream is considered idle if last_activity + idle_timeout_us < current_ts.

Expired streams are transitioned to StreamState::Closed and a MuxEvent::IdleStreamExpired event is emitted for each one.

pub fn update_window(&mut self, stream_id: StreamId, increment: u32) -> bool

Add increment bytes to the send window for stream_id.

Returns true if the stream exists and the window was updated, false otherwise.

pub fn stream_state(&self, stream_id: StreamId) -> Option<&LogicalStream>

Return a reference to the LogicalStream for the given id, or None.

pub fn stream_info(&self, stream_id: StreamId) -> Result<StreamInfo, MuxError>

Return a read-only StreamInfo snapshot for the given stream.

Errors

Returns MuxError::StreamNotFound if the stream does not exist.

pub fn active_streams(&self) -> Vec<StreamId>

Return the ids of all currently active (Open or Opening) streams.

pub fn open_stream_count(&self) -> usize

Number of streams currently in StreamState::Open.

pub fn stats(&self) -> MuxStats

Return the original compact statistics snapshot (MuxStats).

pub fn multiplexer_stats(&self) -> MultiplexerStats

Return the richer MultiplexerStats snapshot.