Trait ReliabilityMode 

pub trait ReliabilityMode: Send + Sync {
    // Required methods
    fn on_send(&mut self, descriptor: Arc<RetransmitDescriptor>);
    fn on_receive(&mut self, seq: u64) -> bool;
    fn needs_ack(&self) -> bool;
    fn build_nack(&self) -> Option<NackPayload>;
    fn on_nack(&mut self, nack: &NackPayload) -> Vec<Arc<RetransmitDescriptor>>;
    fn get_timed_out(&mut self) -> Vec<Arc<RetransmitDescriptor>>;
    fn has_pending(&self) -> bool;
    fn name(&self) -> &'static str;

    // Provided methods
    fn take_failed(&mut self) -> bool { ... }
    fn rx_ack_seq(&self) -> u64 { ... }
    fn on_ack(&mut self, _ack_seq: u64) { ... }
    fn on_ack_ranges(&mut self, _ack_seq: u64, _ranges: &[(u64, u64)]) { ... }
    fn build_ack_ranges(&self, _max_ranges: usize) -> Vec<(u64, u64)> { ... }
    fn can_send(&self) -> bool { ... }
}

Trait for reliability mode implementations.

Per crypto-session perf #133, the descriptor is exchanged as Arc<RetransmitDescriptor> across the trait boundary. The RetransmitDescriptor itself carries an inner Vec<Bytes> of pre-encryption event payloads — at max_pending = 32 and ~10 events per packet that’s ~320 Bytes refcounts dangling off the retransmit window at any given time. Pre-fix on_send moved the descriptor in by value (one Vec spine + one refcount bump per inner Bytes), and on_nack / get_timed_out deep-cloned the descriptor per retransmit (one Vec alloc + N Bytes refcount bumps per emission). Wrapping in Arc makes both paths one atomic refcount bump regardless of the inner Vec’s length.

Required Methods

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 has_pending(&self) -> bool

Check if there are unacknowledged packets

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

Get the name of this reliability mode

Provided Methods

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 on_ack_ranges(&mut self, _ack_seq: u64, _ranges: &[(u64, u64)])

Sender-side: a positive SACK-range ack arrived (R-3). ack_seq carries the cumulative ack (applied exactly like Self::on_ack); ranges are half-open [start, end) received runs strictly above it. SACKed packets are REMOVED from the retransmit window — the receiver has them, so they leave in-flight accounting and are never retransmit-eligible again. This is what stops one lost head packet from RTO- flooding every tracked packet behind it. Default no-op (fire-and-forget tracks nothing).

fn build_ack_ranges(&self, _max_ranges: usize) -> Vec<(u64, u64)>

Receiver-side: the current out-of-order received runs above Self::rx_ack_seq, newest-first (descending by end), at most max_ranges entries — the payload of an outgoing StreamAckRanges (R-4). Default empty (fire-and-forget tracks nothing; a gapless reliable stream has none).

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.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl ReliabilityMode for FireAndForget

impl ReliabilityMode for ReliableStream