use crate::error::Error;
use crate::protocol::{Frame, FrameAssembler, FrameError, FrameType, OutBuf, Sequence};
use crate::transport::ByteTransport;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RxState {
Idle,
Receiving,
Validating,
Acknowledging,
Finished,
Aborted,
}
pub struct Receiver<T: ByteTransport> {
transport: T,
expected_seq: Sequence,
state: RxState,
assembler: FrameAssembler,
out: OutBuf,
pending: Option<PendingAction>,
finish_seq: Option<u8>,
abort_latched: bool,
}
#[derive(Clone, Copy)]
enum PendingAction {
Deliver(u8),
Duplicate,
Started,
Finished,
Aborted,
Rejected,
CrcRejected,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PollOutcome {
Pending,
Delivered(u8),
DuplicateIgnored,
Started,
TransferFinished,
Rejected,
CrcRejected,
Aborted,
}
impl PollOutcome {
pub const fn is_closed(self) -> bool {
matches!(self, Self::TransferFinished | Self::Aborted)
}
}
impl<T: ByteTransport> Receiver<T> {
pub fn new(transport: T) -> Self {
Receiver {
transport,
expected_seq: Sequence::new(),
state: RxState::Idle,
assembler: FrameAssembler::new(),
out: OutBuf::empty(),
pending: None,
finish_seq: None,
abort_latched: false,
}
}
pub fn state(&self) -> RxState {
self.state
}
pub fn expected_seq(&self) -> u8 {
self.expected_seq.current()
}
#[cfg(test)]
pub(crate) fn set_expected_seq(&mut self, seq: u8) {
self.expected_seq = Sequence::from_raw(seq);
}
fn settle_idle(&mut self) {
self.state = if self.abort_latched {
RxState::Aborted
} else if self.finish_seq.is_some() {
RxState::Finished
} else {
RxState::Idle
};
}
fn is_closed(&self) -> bool {
self.abort_latched || self.finish_seq.is_some()
}
fn begin_reply(&mut self, frame: &Frame, action: PendingAction) {
self.out.load(frame);
self.pending = Some(action);
self.state = RxState::Acknowledging;
}
fn pump_reply(&mut self) -> Result<Option<PollOutcome>, Error<T::Error>> {
let Some(byte) = self.out.peek() else {
return Ok(self.take_pending());
};
self.transport.write_byte(byte).map_err(Error::Transport)?;
self.out.commit();
if self.out.is_idle() {
Ok(self.take_pending())
} else {
self.state = RxState::Acknowledging;
Ok(None)
}
}
fn take_pending(&mut self) -> Option<PollOutcome> {
let action = self.pending.take()?;
match action {
PendingAction::Deliver(byte) => {
self.expected_seq.advance();
self.state = RxState::Idle;
Some(PollOutcome::Delivered(byte))
}
PendingAction::Duplicate => {
self.settle_idle();
Some(PollOutcome::DuplicateIgnored)
}
PendingAction::Started => {
self.finish_seq = None;
self.state = RxState::Idle;
Some(PollOutcome::Started)
}
PendingAction::Finished => {
self.state = RxState::Finished;
Some(PollOutcome::TransferFinished)
}
PendingAction::Aborted => {
self.state = RxState::Aborted;
Some(PollOutcome::Aborted)
}
PendingAction::Rejected => {
self.settle_idle();
Some(PollOutcome::Rejected)
}
PendingAction::CrcRejected => {
self.settle_idle();
Some(PollOutcome::CrcRejected)
}
}
}
pub fn poll(&mut self) -> Result<PollOutcome, Error<T::Error>> {
if !self.out.is_idle() {
return Ok(match self.pump_reply()? {
Some(outcome) => outcome,
None => PollOutcome::Pending,
});
}
self.state = RxState::Receiving;
let Some(byte) = self.transport.read_byte().map_err(Error::Transport)? else {
self.settle_idle();
return Ok(PollOutcome::Pending);
};
let Some(decode_result) = self.assembler.push(byte) else {
return Ok(PollOutcome::Pending);
};
self.state = RxState::Validating;
let frame = match decode_result {
Ok(frame) => frame,
Err(err) => {
if self.is_closed() {
self.settle_idle();
return Ok(PollOutcome::Pending);
}
let action = match err {
FrameError::CrcMismatch { .. } => PendingAction::CrcRejected,
_ => PendingAction::Rejected,
};
self.begin_reply(&Frame::nack(self.expected_seq.current()), action);
return Ok(match self.pump_reply()? {
Some(outcome) => outcome,
None => PollOutcome::Pending,
});
}
};
match frame.frame_type() {
FrameType::Data => self.handle_data(frame)?,
FrameType::Start => self.handle_start()?,
FrameType::Finish => self.handle_finish(frame.seq())?,
FrameType::Abort => self.handle_abort()?,
FrameType::Ack | FrameType::Nack => {
self.settle_idle();
return Ok(PollOutcome::Pending);
}
}
Ok(match self.pump_reply()? {
Some(outcome) => outcome,
None => PollOutcome::Pending,
})
}
fn handle_start(&mut self) -> Result<(), Error<T::Error>> {
self.expected_seq = Sequence::new();
self.finish_seq = None;
self.abort_latched = false;
self.begin_reply(&Frame::ack(0), PendingAction::Started);
Ok(())
}
fn handle_abort(&mut self) -> Result<(), Error<T::Error>> {
if self.finish_seq.is_some() {
self.state = RxState::Finished;
return Ok(());
}
self.abort_latched = true;
self.expected_seq = Sequence::new();
self.begin_reply(&Frame::ack(0), PendingAction::Aborted);
Ok(())
}
fn handle_finish(&mut self, seq: u8) -> Result<(), Error<T::Error>> {
if self.abort_latched {
self.state = RxState::Aborted;
return Ok(());
}
if let Some(closed) = self.finish_seq {
if seq == closed {
self.begin_reply(&Frame::ack(seq), PendingAction::Finished);
} else {
self.state = RxState::Finished;
}
return Ok(());
}
if seq != self.expected_seq.current() {
self.begin_reply(&Frame::nack(seq), PendingAction::Rejected);
return Ok(());
}
self.finish_seq = Some(seq);
self.begin_reply(&Frame::ack(seq), PendingAction::Finished);
Ok(())
}
fn handle_data(&mut self, frame: Frame) -> Result<(), Error<T::Error>> {
if self.abort_latched {
self.state = RxState::Aborted;
return Ok(());
}
if self.finish_seq.is_some() {
self.state = RxState::Finished;
return Ok(());
}
let expected = self.expected_seq.current();
if frame.seq() == expected {
self.begin_reply(
&Frame::ack(expected),
PendingAction::Deliver(frame.payload()),
);
return Ok(());
}
if frame.seq() == self.expected_seq.previous() {
self.begin_reply(&Frame::ack(frame.seq()), PendingAction::Duplicate);
return Ok(());
}
self.begin_reply(&Frame::nack(frame.seq()), PendingAction::Rejected);
Ok(())
}
pub fn release(self) -> T {
self.transport
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::test_support::MockTransport;
fn poll_until_settled<T: ByteTransport>(
rx: &mut Receiver<T>,
) -> Result<PollOutcome, Error<T::Error>> {
loop {
match rx.poll()? {
PollOutcome::Pending => continue,
other => return Ok(other),
}
}
}
#[test]
fn delivers_in_order_byte_and_acks_it() {
let incoming = Frame::data(0, 0x42).to_bytes();
let transport = MockTransport::with_incoming(&incoming);
let mut rx = Receiver::new(transport);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::Delivered(0x42))
);
assert_eq!(rx.expected_seq(), 1);
assert_eq!(rx.transport.written(), Frame::ack(0).to_bytes());
}
#[test]
fn delivered_only_after_ack_is_fully_written() {
let incoming = Frame::data(0, 0x42).to_bytes();
let mut rx = Receiver::new(MockTransport::with_incoming(&incoming));
for _ in 0..3 {
assert_eq!(rx.poll(), Ok(PollOutcome::Pending));
assert!(rx.transport.written().is_empty());
}
assert_eq!(rx.poll(), Ok(PollOutcome::Pending));
assert_eq!(rx.transport.written().len(), 1);
assert_eq!(rx.expected_seq(), 0, "must not advance before ACK is out");
assert_eq!(rx.poll(), Ok(PollOutcome::Pending));
assert_eq!(rx.poll(), Ok(PollOutcome::Pending));
assert_eq!(rx.poll(), Ok(PollOutcome::Delivered(0x42)));
assert_eq!(rx.expected_seq(), 1);
assert_eq!(rx.transport.written(), Frame::ack(0).to_bytes());
}
#[test]
fn pending_when_frame_incomplete() {
let bytes = Frame::data(0, 1).to_bytes();
let transport = MockTransport::with_incoming(&bytes[..2]);
let mut rx = Receiver::new(transport);
assert_eq!(rx.poll(), Ok(PollOutcome::Pending));
assert_eq!(rx.poll(), Ok(PollOutcome::Pending));
assert_eq!(rx.poll(), Ok(PollOutcome::Pending));
}
#[test]
fn duplicate_retransmission_is_reacked_not_redelivered() {
let incoming = crate::test_support::concat2(
Frame::data(0, 0xAA).to_bytes(),
Frame::data(0, 0xAA).to_bytes(),
);
let transport = MockTransport::with_incoming(&incoming);
let mut rx = Receiver::new(transport);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::Delivered(0xAA))
);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::DuplicateIgnored)
);
assert_eq!(rx.expected_seq(), 1);
}
#[test]
fn corrupted_frame_triggers_nack_and_propagates_error() {
let mut bytes = Frame::data(0, 1).to_bytes();
bytes[2] ^= 0xFF;
let transport = MockTransport::with_incoming(&bytes);
let mut rx = Receiver::new(transport);
assert_eq!(poll_until_settled(&mut rx), Ok(PollOutcome::CrcRejected));
assert_eq!(rx.expected_seq(), 0);
assert_eq!(rx.transport.written(), Frame::nack(0).to_bytes());
}
#[test]
fn start_resets_expected_seq_and_acks() {
let incoming = crate::test_support::concat3(
Frame::data(0, 0x10).to_bytes(),
Frame::data(1, 0x11).to_bytes(),
Frame::start().to_bytes(),
);
let transport = MockTransport::with_incoming(&incoming);
let mut rx = Receiver::new(transport);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::Delivered(0x10))
);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::Delivered(0x11))
);
assert_eq!(rx.expected_seq(), 2);
assert_eq!(poll_until_settled(&mut rx), Ok(PollOutcome::Started));
assert_eq!(rx.expected_seq(), 0);
assert_eq!(rx.state(), RxState::Idle);
}
#[test]
fn finish_is_accepted_only_at_expected_seq() {
let incoming = crate::test_support::concat2(
Frame::data(0, 0x10).to_bytes(),
Frame::finish(0).to_bytes(),
);
let mut rx = Receiver::new(MockTransport::with_incoming(&incoming));
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::Delivered(0x10))
);
assert_eq!(rx.expected_seq(), 1);
assert_eq!(poll_until_settled(&mut rx), Ok(PollOutcome::Rejected));
assert_eq!(rx.state(), RxState::Idle);
assert_eq!(rx.expected_seq(), 1);
}
#[test]
fn finish_at_expected_seq_is_acked_then_closed() {
let transport = MockTransport::with_incoming(&Frame::finish(0).to_bytes());
let mut rx = Receiver::new(transport);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::TransferFinished)
);
assert_eq!(rx.state(), RxState::Finished);
assert_eq!(rx.transport.written(), Frame::ack(0).to_bytes());
}
#[test]
fn duplicate_finish_is_reacked_not_an_error() {
let incoming =
crate::test_support::concat2(Frame::finish(0).to_bytes(), Frame::finish(0).to_bytes());
let transport = MockTransport::with_incoming(&incoming);
let mut rx = Receiver::new(transport);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::TransferFinished)
);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::TransferFinished)
);
assert_eq!(
rx.transport.written(),
crate::test_support::concat2(Frame::ack(0).to_bytes(), Frame::ack(0).to_bytes())
);
assert_eq!(rx.state(), RxState::Finished);
}
#[test]
fn data_after_finish_is_not_delivered() {
let incoming = crate::test_support::concat2(
Frame::finish(0).to_bytes(),
Frame::data(0, 0x99).to_bytes(),
);
let mut rx = Receiver::new(MockTransport::with_incoming(&incoming));
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::TransferFinished)
);
for _ in 0..8 {
assert_eq!(rx.poll(), Ok(PollOutcome::Pending));
}
assert_eq!(rx.state(), RxState::Finished);
assert_eq!(rx.transport.written(), Frame::ack(0).to_bytes());
}
#[test]
fn corrupt_after_finish_does_not_nack_or_leave_finished() {
let finish = Frame::finish(0).to_bytes();
let mut bad = Frame::data(0, 1).to_bytes();
bad[3] ^= 0xFF;
let incoming = crate::test_support::concat2(finish, bad);
let mut rx = Receiver::new(MockTransport::with_incoming(&incoming));
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::TransferFinished)
);
for _ in 0..8 {
assert_eq!(rx.poll(), Ok(PollOutcome::Pending));
}
assert_eq!(rx.state(), RxState::Finished);
assert_eq!(rx.transport.written(), Frame::ack(0).to_bytes());
}
#[test]
fn start_after_finish_reopens_the_session() {
let incoming = crate::test_support::concat3(
Frame::finish(0).to_bytes(),
Frame::start().to_bytes(),
Frame::data(0, 0xAB).to_bytes(),
);
let mut rx = Receiver::new(MockTransport::with_incoming(&incoming));
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::TransferFinished)
);
assert_eq!(poll_until_settled(&mut rx), Ok(PollOutcome::Started));
assert_eq!(rx.expected_seq(), 0);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::Delivered(0xAB))
);
assert_eq!(rx.expected_seq(), 1);
}
#[test]
fn reordered_data_is_rejected_and_not_delivered() {
let incoming = crate::test_support::concat3(
Frame::data(0, 0x10).to_bytes(),
Frame::data(2, 0x12).to_bytes(),
Frame::data(1, 0x11).to_bytes(),
);
let transport = MockTransport::with_incoming(&incoming);
let mut rx = Receiver::new(transport);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::Delivered(0x10))
);
assert_eq!(poll_until_settled(&mut rx), Ok(PollOutcome::Rejected));
assert_eq!(rx.expected_seq(), 1);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::Delivered(0x11))
);
assert_eq!(rx.expected_seq(), 2);
}
#[test]
fn wraparound_duplicate_of_255_is_not_redelivered() {
let incoming = crate::test_support::concat2(
Frame::data(255, 0xFE).to_bytes(),
Frame::data(0, 0x00).to_bytes(),
);
let transport = MockTransport::with_incoming(&incoming);
let mut rx = Receiver::new(transport);
rx.set_expected_seq(0);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::DuplicateIgnored)
);
assert_eq!(rx.expected_seq(), 0);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::Delivered(0x00))
);
assert_eq!(rx.expected_seq(), 1);
}
#[test]
fn wraparound_255_then_0_delivers_both() {
let incoming = crate::test_support::concat2(
Frame::data(255, 0xFE).to_bytes(),
Frame::data(0, 0x00).to_bytes(),
);
let transport = MockTransport::with_incoming(&incoming);
let mut rx = Receiver::new(transport);
rx.set_expected_seq(255);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::Delivered(0xFE))
);
assert_eq!(rx.expected_seq(), 0);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::Delivered(0x00))
);
assert_eq!(rx.expected_seq(), 1);
}
#[test]
fn abort_is_acked_and_cancels() {
let transport = MockTransport::with_incoming(&Frame::abort().to_bytes());
let mut rx = Receiver::new(transport);
assert_eq!(poll_until_settled(&mut rx), Ok(PollOutcome::Aborted));
assert_eq!(rx.state(), RxState::Aborted);
assert_eq!(rx.transport.written(), Frame::ack(0).to_bytes());
}
#[test]
fn data_after_abort_is_not_delivered() {
let incoming = crate::test_support::concat2(
Frame::abort().to_bytes(),
Frame::data(0, 0x99).to_bytes(),
);
let mut rx = Receiver::new(MockTransport::with_incoming(&incoming));
assert_eq!(poll_until_settled(&mut rx), Ok(PollOutcome::Aborted));
for _ in 0..8 {
assert_eq!(rx.poll(), Ok(PollOutcome::Pending));
}
assert_eq!(rx.state(), RxState::Aborted);
assert_eq!(rx.transport.written(), Frame::ack(0).to_bytes());
}
#[test]
fn abort_after_finish_is_ignored() {
let incoming =
crate::test_support::concat2(Frame::finish(0).to_bytes(), Frame::abort().to_bytes());
let mut rx = Receiver::new(MockTransport::with_incoming(&incoming));
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::TransferFinished)
);
for _ in 0..8 {
assert_eq!(rx.poll(), Ok(PollOutcome::Pending));
}
assert_eq!(rx.state(), RxState::Finished);
assert_eq!(rx.transport.written(), Frame::ack(0).to_bytes());
}
#[test]
fn start_after_abort_reopens_the_session() {
let incoming = crate::test_support::concat3(
Frame::abort().to_bytes(),
Frame::start().to_bytes(),
Frame::data(0, 0xAB).to_bytes(),
);
let mut rx = Receiver::new(MockTransport::with_incoming(&incoming));
assert_eq!(poll_until_settled(&mut rx), Ok(PollOutcome::Aborted));
assert_eq!(poll_until_settled(&mut rx), Ok(PollOutcome::Started));
assert_eq!(rx.expected_seq(), 0);
assert_eq!(
poll_until_settled(&mut rx),
Ok(PollOutcome::Delivered(0xAB))
);
assert_eq!(rx.expected_seq(), 1);
}
#[test]
fn duplicate_abort_is_reacked() {
let incoming =
crate::test_support::concat2(Frame::abort().to_bytes(), Frame::abort().to_bytes());
let mut rx = Receiver::new(MockTransport::with_incoming(&incoming));
assert_eq!(poll_until_settled(&mut rx), Ok(PollOutcome::Aborted));
assert_eq!(poll_until_settled(&mut rx), Ok(PollOutcome::Aborted));
assert_eq!(
rx.transport.written(),
crate::test_support::concat2(Frame::ack(0).to_bytes(), Frame::ack(0).to_bytes())
);
assert_eq!(rx.state(), RxState::Aborted);
}
}