Skip to main content

psicose/
stream.rs

1//! Application data is **bytes**. The 4-byte frame is only the envelope.
2//!
3//! ```text
4//! JPEG  File  Flash  Sensor  firmware.bin  [u8]
5//!   │     │     │       │         │         │
6//!   └─────┴─────┴───────┴─────────┴─────────┘
7//!                     │
8//!                ByteSource          ← you implement this
9//!                     │ 1 byte
10//!                     ▼
11//!                  PSICOSE           ← never owns the file
12//!                     │ Frame
13//!                     ▼
14//!                ByteTransport
15//!                     │
16//!                ByteSink            ← you implement this
17//!                     │
18//!              File  Flash  RAM
19//! ```
20//!
21//! A JPEG, a 4 GB file, and a 4-byte config blob use the same path.
22//! PSICOSE does not know the type. It only ever holds the current
23//! payload byte (or `N` of them, in a window).
24
25use crate::error::Error;
26use crate::rx::{PollOutcome, Receiver};
27use crate::timeout::IdleBudget;
28use crate::transport::{ByteSink, ByteSource, ByteTransport};
29use crate::tx::{Sender, TxPoll};
30use crate::window::{WindowedReceiver, WindowedSender};
31
32/// Error from a source-to-sink transfer: either the link or the
33/// application reader/writer.
34#[derive(Debug, Clone, Copy, PartialEq, Eq)]
35pub enum StreamError<Link, App> {
36    /// ACK/NACK/CRC/retry failure on the wire.
37    Protocol(Error<Link>),
38    /// [`ByteSource`] or [`ByteSink`] failed.
39    Application(App),
40}
41
42impl<Link: core::fmt::Debug, App: core::fmt::Debug> core::fmt::Display for StreamError<Link, App> {
43    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
44        match self {
45            StreamError::Protocol(e) => write!(f, "protocol: {e}"),
46            StreamError::Application(e) => write!(f, "application: {e:?}"),
47        }
48    }
49}
50
51/// The destination slice had no room for the next byte.
52#[derive(Debug, Clone, Copy, PartialEq, Eq)]
53pub struct SliceFull;
54
55/// Borrowed byte source. The caller owns the buffer; PSICOSE does not.
56pub struct SliceSource<'a> {
57    rest: &'a [u8],
58}
59
60impl<'a> SliceSource<'a> {
61    /// Streams `bytes` from the start.
62    pub const fn new(bytes: &'a [u8]) -> Self {
63        SliceSource { rest: bytes }
64    }
65
66    /// Bytes not yet offered to the sender.
67    pub const fn remaining(&self) -> usize {
68        self.rest.len()
69    }
70}
71
72impl ByteSource for SliceSource<'_> {
73    type Error = core::convert::Infallible;
74
75    fn read_byte(&mut self) -> Result<Option<u8>, Self::Error> {
76        match self.rest.split_first() {
77            Some((byte, rest)) => {
78                self.rest = rest;
79                Ok(Some(*byte))
80            }
81            None => Ok(None),
82        }
83    }
84}
85
86impl<'a> From<&'a [u8]> for SliceSource<'a> {
87    fn from(bytes: &'a [u8]) -> Self {
88        SliceSource::new(bytes)
89    }
90}
91
92/// Borrowed byte sink. The caller owns the buffer; PSICOSE does not.
93pub struct SliceSink<'a> {
94    buf: &'a mut [u8],
95    pos: usize,
96}
97
98impl<'a> SliceSink<'a> {
99    /// Writes into `buf` from index 0.
100    pub fn new(buf: &'a mut [u8]) -> Self {
101        SliceSink { buf, pos: 0 }
102    }
103
104    /// How many bytes were written.
105    pub const fn filled(&self) -> usize {
106        self.pos
107    }
108
109    /// The prefix that was written.
110    pub fn written(&self) -> &[u8] {
111        &self.buf[..self.pos]
112    }
113}
114
115impl ByteSink for SliceSink<'_> {
116    type Error = SliceFull;
117
118    fn write_byte(&mut self, byte: u8) -> Result<(), Self::Error> {
119        if self.pos >= self.buf.len() {
120            return Err(SliceFull);
121        }
122        self.buf[self.pos] = byte;
123        self.pos += 1;
124        Ok(())
125    }
126}
127
128impl<'a> From<&'a mut [u8]> for SliceSink<'a> {
129    fn from(buf: &'a mut [u8]) -> Self {
130        SliceSink::new(buf)
131    }
132}
133
134/// Drain `src` through a stop-and-wait sender, then FINISH.
135///
136/// The source can be a file, flash, camera buffer, or [`SliceSource`].
137/// Returns how many payload bytes were accepted by the peer.
138///
139/// This path expects ACKs on the sender's own transport (scripted
140/// replies). On a live pair, use [`crate::Pump::send_all`] so RX is
141/// polled in the same cooperative step.
142///
143/// In-flight waits use [`crate::timeout::RetryPolicy`] inside
144/// [`Sender::send_byte`](crate::tx::Sender::send_byte) — not an idle budget.
145pub fn send_all<T, S>(
146    tx: &mut Sender<T>,
147    src: &mut S,
148) -> Result<u64, StreamError<T::Error, S::Error>>
149where
150    T: ByteTransport,
151    S: ByteSource,
152{
153    let mut n = 0u64;
154    loop {
155        let byte = src.read_byte().map_err(StreamError::Application)?;
156        match byte {
157            Some(byte) => {
158                tx.send_byte(byte).map_err(StreamError::Protocol)?;
159                n = n.saturating_add(1);
160            }
161            None => {
162                tx.send_finish().map_err(StreamError::Protocol)?;
163                return Ok(n);
164            }
165        }
166    }
167}
168
169/// Drain `src` through a windowed sender, then FINISH.
170pub fn send_all_windowed<T, S, const N: usize>(
171    tx: &mut WindowedSender<T, N>,
172    src: &mut S,
173) -> Result<u64, StreamError<T::Error, S::Error>>
174where
175    T: ByteTransport,
176    S: ByteSource,
177{
178    send_all_windowed_budgeted(tx, src, IdleBudget::DEFAULT)
179}
180
181/// [`send_all_windowed`] with an [`IdleBudget`] on the `WindowFull` spin.
182pub fn send_all_windowed_budgeted<T, S, const N: usize>(
183    tx: &mut WindowedSender<T, N>,
184    src: &mut S,
185    mut budget: IdleBudget,
186) -> Result<u64, StreamError<T::Error, S::Error>>
187where
188    T: ByteTransport,
189    S: ByteSource,
190{
191    let mut n = 0u64;
192    loop {
193        let byte = src.read_byte().map_err(StreamError::Application)?;
194        match byte {
195            Some(byte) => loop {
196                match tx.offer(byte) {
197                    Ok(()) => {
198                        n = n.saturating_add(1);
199                        budget.reset();
200                        break;
201                    }
202                    Err(Error::WindowFull) => match tx.poll().map_err(StreamError::Protocol)? {
203                        TxPoll::Acked => budget.reset(),
204                        TxPoll::Pending => budget.tick().map_err(StreamError::Protocol)?,
205                        TxPoll::Aborted => {
206                            return Err(StreamError::Protocol(Error::Aborted));
207                        }
208                        TxPoll::SessionReady | TxPoll::TransferDone => {
209                            budget.tick().map_err(StreamError::Protocol)?;
210                        }
211                    },
212                    Err(e) => return Err(StreamError::Protocol(e)),
213                }
214            },
215            None => break,
216        }
217    }
218    while tx.outstanding() > 0 {
219        match tx.poll().map_err(StreamError::Protocol)? {
220            TxPoll::Acked => budget.reset(),
221            TxPoll::Pending => budget.tick().map_err(StreamError::Protocol)?,
222            TxPoll::Aborted => return Err(StreamError::Protocol(Error::Aborted)),
223            TxPoll::SessionReady | TxPoll::TransferDone => break,
224        }
225    }
226    tx.send_finish().map_err(StreamError::Protocol)?;
227    Ok(n)
228}
229
230/// Write every delivered payload byte into `sink` until FINISH.
231pub fn recv_all<T, K>(
232    rx: &mut Receiver<T>,
233    sink: &mut K,
234) -> Result<u64, StreamError<T::Error, K::Error>>
235where
236    T: ByteTransport,
237    K: ByteSink,
238{
239    recv_all_budgeted(rx, sink, IdleBudget::DEFAULT)
240}
241
242/// [`recv_all`] with an [`IdleBudget`] so a silent peer cannot hang the loop.
243pub fn recv_all_budgeted<T, K>(
244    rx: &mut Receiver<T>,
245    sink: &mut K,
246    budget: IdleBudget,
247) -> Result<u64, StreamError<T::Error, K::Error>>
248where
249    T: ByteTransport,
250    K: ByteSink,
251{
252    drain_recv(|| rx.poll(), sink, budget)
253}
254
255/// Windowed counterpart of [`recv_all`].
256pub fn recv_all_windowed<T, K, const N: usize>(
257    rx: &mut WindowedReceiver<T, N>,
258    sink: &mut K,
259) -> Result<u64, StreamError<T::Error, K::Error>>
260where
261    T: ByteTransport,
262    K: ByteSink,
263{
264    recv_all_windowed_budgeted(rx, sink, IdleBudget::DEFAULT)
265}
266
267/// [`recv_all_windowed`] with an [`IdleBudget`].
268pub fn recv_all_windowed_budgeted<T, K, const N: usize>(
269    rx: &mut WindowedReceiver<T, N>,
270    sink: &mut K,
271    budget: IdleBudget,
272) -> Result<u64, StreamError<T::Error, K::Error>>
273where
274    T: ByteTransport,
275    K: ByteSink,
276{
277    drain_recv(|| rx.poll(), sink, budget)
278}
279
280fn drain_recv<E, K, F>(
281    mut poll: F,
282    sink: &mut K,
283    mut budget: IdleBudget,
284) -> Result<u64, StreamError<E, K::Error>>
285where
286    F: FnMut() -> Result<PollOutcome, Error<E>>,
287    K: ByteSink,
288{
289    let mut n = 0u64;
290    loop {
291        match poll().map_err(StreamError::Protocol)? {
292            PollOutcome::Delivered(byte) => {
293                sink.write_byte(byte).map_err(StreamError::Application)?;
294                n = n.saturating_add(1);
295                budget.reset();
296            }
297            PollOutcome::TransferFinished => return Ok(n),
298            PollOutcome::Aborted => return Err(StreamError::Protocol(Error::Aborted)),
299            PollOutcome::Started
300            | PollOutcome::DuplicateIgnored
301            | PollOutcome::Rejected
302            | PollOutcome::CrcRejected => budget.reset(),
303            PollOutcome::Pending => budget.tick().map_err(StreamError::Protocol)?,
304        }
305    }
306}
307
308/// Send a borrowed slice. The slice stays with the caller.
309pub fn send_bytes<T: ByteTransport>(
310    tx: &mut Sender<T>,
311    bytes: &[u8],
312) -> Result<u64, Error<T::Error>> {
313    let mut src = SliceSource::new(bytes);
314    match send_all(tx, &mut src) {
315        Ok(n) => Ok(n),
316        Err(StreamError::Protocol(e)) => Err(e),
317        Err(StreamError::Application(never)) => match never {},
318    }
319}
320
321/// Receive into a borrowed slice until FINISH.
322pub fn recv_bytes<'a, T: ByteTransport>(
323    rx: &mut Receiver<T>,
324    buf: &'a mut [u8],
325) -> Result<&'a [u8], StreamError<T::Error, SliceFull>> {
326    let mut sink = SliceSink::new(buf);
327    recv_all(rx, &mut sink)?;
328    let n = sink.filled();
329    Ok(&buf[..n])
330}
331
332#[cfg(test)]
333mod tests {
334    use super::*;
335    use crate::protocol::Frame;
336    use crate::test_support::MockTransport;
337    use crate::timeout::RetryPolicy;
338    use crate::transport::ByteSource;
339    use crate::window::{WindowedReceiver, WindowedSender};
340
341    fn ack_run(data_bytes: u8) -> [u8; 36] {
342        let data_bytes = core::cmp::min(data_bytes, 8);
343        let mut out = [0u8; 36];
344        let frames = data_bytes as usize + 1;
345        for i in 0..frames {
346            let bytes = Frame::ack(i as u8).to_bytes();
347            out[i * 4..i * 4 + 4].copy_from_slice(&bytes);
348        }
349        out
350    }
351
352    #[test]
353    fn slice_source_is_just_bytes() {
354        let jpeg_so_i_like = [0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10];
355        let mut src = SliceSource::new(&jpeg_so_i_like);
356        assert_eq!(src.read_byte(), Ok(Some(0xFF)));
357        assert_eq!(src.read_byte(), Ok(Some(0xD8)));
358        assert_eq!(src.remaining(), 4);
359    }
360
361    #[test]
362    fn send_bytes_moves_any_payload_then_finish() {
363        let payload = [b'P', b'S', b'I', 0x00];
364        let incoming = ack_run(4);
365        let mut tx = Sender::with_policy(
366            MockTransport::with_incoming(&incoming[..20]),
367            RetryPolicy::new(50, 3),
368        );
369        assert_eq!(send_bytes(&mut tx, &payload), Ok(4));
370        assert_eq!(tx.state(), crate::tx::TxState::Finished);
371    }
372
373    #[test]
374    fn recv_bytes_rebuilds_the_payload() {
375        let incoming = crate::test_support::concat3(
376            Frame::data(0, 0xFF).to_bytes(),
377            Frame::data(1, 0xD8).to_bytes(),
378            Frame::finish(2).to_bytes(),
379        );
380        let mut rx = Receiver::new(MockTransport::with_incoming(&incoming));
381        let mut buf = [0u8; 8];
382        assert_eq!(recv_bytes(&mut rx, &mut buf), Ok(&[0xFF, 0xD8][..]));
383    }
384
385    #[test]
386    fn sink_full_is_an_application_error() {
387        let incoming = crate::test_support::concat2(
388            Frame::data(0, 1).to_bytes(),
389            Frame::data(1, 2).to_bytes(),
390        );
391        let mut rx = Receiver::new(MockTransport::with_incoming(&incoming));
392        let mut buf = [0u8; 1];
393        assert_eq!(
394            recv_bytes(&mut rx, &mut buf),
395            Err(StreamError::Application(SliceFull))
396        );
397    }
398
399    #[test]
400    fn send_all_windowed_then_finish() {
401        let payload = [0xDE, 0xAD, 0xBE, 0xEF];
402        let incoming = ack_run(4);
403        let mut tx = WindowedSender::<_, 4>::with_policy(
404            MockTransport::with_incoming(&incoming[..20]),
405            RetryPolicy::new(50, 3),
406        );
407        let mut src = SliceSource::new(&payload);
408        assert_eq!(send_all_windowed(&mut tx, &mut src), Ok(4));
409        assert_eq!(tx.state(), crate::tx::TxState::Finished);
410    }
411
412    #[test]
413    fn recv_all_windowed_rebuilds_any_blob() {
414        let incoming = crate::test_support::concat3(
415            Frame::data(0, b'{').to_bytes(),
416            Frame::data(1, b'}').to_bytes(),
417            Frame::finish(2).to_bytes(),
418        );
419        let mut rx = WindowedReceiver::<_, 4>::new(MockTransport::with_incoming(&incoming));
420        let mut buf = [0u8; 8];
421        let mut sink = SliceSink::new(&mut buf);
422        assert_eq!(recv_all_windowed(&mut rx, &mut sink), Ok(2));
423        assert_eq!(sink.written(), b"{}");
424    }
425
426    #[test]
427    fn recv_all_budgeted_returns_when_peer_disappears() {
428        let mut rx = Receiver::new(MockTransport::with_incoming(&[]));
429        let mut buf = [0u8; 4];
430        let mut sink = SliceSink::new(&mut buf);
431        assert_eq!(
432            recv_all_budgeted(&mut rx, &mut sink, IdleBudget::new(8)),
433            Err(StreamError::Protocol(Error::IdleBudgetExhausted))
434        );
435    }
436}