Struct ReliableStream 

pub struct ReliableStream { /* private fields */ }

Reliable stream mode with selective NACKs.

Features:

• Bounded retransmit window (32 packets)
• Selective NACKs (receiver-driven)
• Per-stream state
• Configurable RTO

Suitable for:

• Tool call results
• Guardrail decisions
• Session lifecycle events
• Error propagation

Implementations

impl ReliableStream

pub const DEFAULT_RTO: Duration

Default retransmit timeout — the starting RTO before any RTT sample, and the value used by fixed-RTO callers.

pub const MIN_RTO: Duration

Lower bound on the adaptive RTO (H-5). Floors the estimate so a near-zero localhost RTT can’t drive the RTO below the grant-drain

• processing latency and cause spurious resends.

pub const MAX_RTO: Duration

Upper bound on the adaptive RTO (H-5). Caps how long a genuinely lost packet waits before the timeout backstop resends it.

pub const DEFAULT_MAX_PENDING: usize = 32

Default max pending packets — also the floor when the window is auto-sized from a stream’s tx-window (see Self::max_pending_for_window).

pub const MIN_TRACKED_PACKET_BYTES: u32 = 512

Lower bound on the per-packet size assumed when sizing the retransmit window from a tx-window. The window must track at least tx_window / MIN_TRACKED_PACKET_BYTES packets so nothing in flight is evicted before it can be retransmitted. 512 B covers bulk (MTU) and typical control packets; sub-512 B spam on a huge window is the only residual eviction risk — surfaced loudly via Self::untracked_evictions (H-2).

pub const MAX_RETRANSMIT_WINDOW: usize = 16_384

Hard cap on the auto-sized retransmit window, bounding the pending queue’s worst-case growth under sustained loss.

pub const DEFAULT_MAX_RETRIES: u8 = 3

Default max retries

pub const INIT_CWND: f64 = 32.0

Initial congestion window in packets (H-6). ~TCP initial window; big enough that low-volume reliable streams (nRPC) never feel it.

pub const MIN_CWND: f64 = 2.0

Congestion-window floor — a stream under sustained loss still makes forward progress at this many packets in flight.

pub fn max_pending_for_window(tx_window: u32) -> usize

Size the retransmit window to a stream’s tx-credit window so the sender can never have more packets in flight than it can retransmit (the H-1 invariant: tx-window ≤ retransmit-window). tx_window == 0 (backpressure disabled) falls back to the default.

pub fn new() -> Self

Create a new reliable stream with default settings.

pending is NOT pre-reserved: it grows on demand to the actual in-flight count (itself bounded by the tx-window’s bytes), so a generous max_pending costs nothing up front — important when thousands of small-payload streams each carry a reliability state.

pub fn with_settings(rto: Duration, max_pending: usize, max_retries: u8) -> Self

Create with custom settings. pending grows on demand (no pre-reservation) — see Self::new.

pub fn untracked_evictions(&self) -> u64

Number of unacknowledged packets that the stream evicted from its retransmit window because the window was full at on_send time. Each eviction means the caller’s syscall succeeded (bytes left this node) but the packet is no longer tracked for retransmit — a NACK can no longer recover it. A non-zero value indicates max_pending is undersized for the stream’s sustained throughput. Operators should size up or apply upstream backpressure rather than accepting silent loss.

pub fn set_rto(&mut self, rto: Duration)

Set the retransmit timeout

pub fn next_expected(&self) -> u64

Lowest sequence number we have not yet received. All sequences strictly below this value are contiguously received.

pub fn last_received_contiguous(&self) -> Option<u64>

Highest contiguously-received sequence number, or None if no packets have been received yet.

pub fn ack_seq(&self) -> u64

Get the current ack sequence (highest contiguously-received seq). Returns 0 when nothing has been received yet — callers that need to distinguish “received seq 0” from “received nothing” should use Self::last_received_contiguous instead.

Trait Implementations

impl Debug for ReliableStream

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ReliableStream

fn default() -> Self

Returns the “default value” for a type.

impl ReliabilityMode for ReliableStream

fn on_send(&mut self, descriptor: Arc<RetransmitDescriptor>)

Called when a packet is sent. The descriptor carries pre- encryption inputs so the retransmit path can rebuild a fresh-counter packet rather than replaying stale ciphertext.

fn on_receive(&mut self, seq: u64) -> bool

Called when a packet is received. Returns true if accepted.

fn needs_ack(&self) -> bool

Check if this mode requires acknowledgments

fn build_nack(&self) -> Option<NackPayload>

Build a NACK payload if there are missing sequences

fn on_nack(&mut self, nack: &NackPayload) -> Vec<Arc<RetransmitDescriptor>>

Process a received NACK and return descriptors for the caller to rebuild + dispatch. The returned Arc clones share the inner RetransmitDescriptor allocation; the caller bumps the refcount instead of deep-cloning the Vec<Bytes> of events.

fn get_timed_out(&mut self) -> Vec<Arc<RetransmitDescriptor>>

Get descriptors that need retransmission due to timeout. See Self::on_nack for the Arc-sharing contract.

fn take_failed(&mut self) -> bool

Take-and-clear the “stream has given up” flag (H-3): true once after a packet exhausts max_retries while still unacked — the reliable layer can no longer recover that gap, so the caller should signal a stream reset to the peer rather than let it stall to a higher-level timeout. Default false (fire-and-forget never gives up — it tracks nothing).

fn rx_ack_seq(&self) -> u64

The receiver’s cumulative ack — the lowest sequence not yet contiguously received (next_expected). The peer piggybacks this on its window grants so the sender can prune (H-9). Default 0 (fire-and-forget tracks no sequence).

fn on_ack(&mut self, ack_seq: u64)

Sender-side: a cumulative ack arrived — every sequence below ack_seq has been received, so drop them from the retransmit window (H-9). Without this, packets linger in pending on the happy path until they spuriously time out and get resent (and, post-H-3, spuriously give up). Default no-op.

fn can_send(&self) -> bool

Whether the sender may put another packet in flight under its congestion window (H-6). Default true (fire-and-forget has no congestion state). A reliable stream returns false once in-flight reaches its cwnd, so the send path back-pressures and paces to the cwnd under loss.

fn has_pending(&self) -> bool

Check if there are unacknowledged packets

fn name(&self) -> &'static str

Get the name of this reliability mode