Skip to main content

hopr_protocol_session/processing/
segmenter.rs

1//! This module defines a [`Segmenter`] adaptor for [`futures::Sink`].
2use std::{
3    collections::VecDeque,
4    pin::Pin,
5    task::{Context, Poll},
6};
7
8use tracing::instrument;
9
10use crate::{
11    protocol::{FrameId, Segment, SeqIndicator},
12    session_socket_mtu,
13    utils::segment_into,
14};
15
16/// Segmenter is an adaptor to [`futures::Sink`] of [`Segment`] items
17/// that turns it into [`futures::io::AsyncWrite`].
18///
19/// Bytes written to the Segmenter are buffered up and/or chopped into [`Segment`]
20/// of at most `C` in payload size (the `data` member).
21///
22/// The bytes are written to the
23/// underlying Sink once more than `frame_size` is written (or unless flushed),
24/// so the Segmenter naturally acts as a buffered writer.
25/// Any unflushed bytes written to the Segmenter will be lost when it is closed.
26///
27/// The data are grouped into [`Frames`](crate::protocol::Frame) of the size given by the `frame_size`
28/// parameter, segments in each such group share the same [`FrameId`].
29/// This acts as a natural buffering feature of a Segmenter.
30///
31/// Segmenter can optionally send a [terminating](Segment::terminating) when `poll_close`
32/// is called.
33///
34/// Segmenter is essentially inverse of [`Reassembler`](super::reassembly::Reassembler).
35///
36/// Use [`SegmenterExt`] to turn a `Segment` sink into an `AsyncWrite` object using the `Segmenter`.
37#[must_use = "sinks do nothing unless polled"]
38#[pin_project::pin_project]
39pub struct Segmenter<const C: usize, S> {
40    #[pin]
41    inner: S,
42    state: State,
43    frame: Vec<u8>,
44    ready_segments: VecDeque<Segment>,
45    frame_size: usize,
46    frame_id: FrameId,
47    is_closed: bool,
48    send_terminating_segment: bool,
49    /// Datagram mode: emit exactly one frame per write (preserve datagram boundaries) instead of
50    /// coalescing writes up to `frame_size`. On stateless sessions the `hopr-transport-session`
51    /// crate enables this for the `NoDelay` (UDP-like) capability.
52    datagram: bool,
53}
54
55enum State {
56    BufferingFrame,
57    WritingFrame,
58}
59
60impl<const C: usize, S> Segmenter<C, S>
61where
62    S: futures::Sink<Segment>,
63    S::Error: std::error::Error + Send + Sync + 'static,
64{
65    fn new(inner: S, frame_size: usize, send_terminating_segment: bool, datagram: bool) -> Self {
66        // Clamp frame_size to [SESSION_MTU, SESSION_MTU * (SeqIndicator::MAX + 1)].
67        // Minimum is SESSION_MTU so that a single frame fits in one
68        // HOPR packet (1 segment). Maximum is bounded by SeqIndicator capacity.
69        //
70        // In datagram mode `frame_size` no longer bounds a frame (each write is its own frame);
71        // an individual datagram may be up to the same SeqIndicator-bounded maximum. `frame_size`
72        // is then only a capacity hint for the frame buffer.
73        let frame_size = frame_size.clamp(
74            session_socket_mtu::<C>(),
75            session_socket_mtu::<C>() * (SeqIndicator::MAX + 1) as usize,
76        );
77
78        Self {
79            inner,
80            state: State::BufferingFrame,
81            frame: Vec::with_capacity(frame_size),
82            // Segments are `session_socket_mtu` bytes, not `C - SEGMENT_OVERHEAD`; sizing this on the
83            // latter under-counts whenever the MAX_SESSION_MTU cap binds.
84            ready_segments: VecDeque::with_capacity(frame_size.div_ceil(session_socket_mtu::<C>())),
85            frame_size,
86            frame_id: 1,
87            is_closed: false,
88            send_terminating_segment,
89            datagram,
90        }
91    }
92}
93
94impl<const C: usize, S> futures::io::AsyncWrite for Segmenter<C, S>
95where
96    S: futures::Sink<Segment>,
97    S::Error: std::error::Error + Send + Sync + 'static,
98{
99    #[instrument(name = "Segmenter::poll_write", level = "trace", skip(self, cx, buf), fields(frame_id = self.frame_id, buf_len = buf.len(), frame_size = self.frame.len(), ready_segments = self.ready_segments.len()), ret)]
100    fn poll_write(self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8]) -> Poll<std::io::Result<usize>> {
101        if self.is_closed {
102            return Poll::Ready(Err(std::io::Error::new(
103                std::io::ErrorKind::BrokenPipe,
104                "segmenter closed",
105            )));
106        }
107
108        let mut this = self.project();
109        loop {
110            match this.state {
111                State::BufferingFrame => {
112                    // Datagram mode: emit exactly one frame per write so datagram boundaries are
113                    // preserved (the peer reads one datagram per read), regardless of `frame_size`.
114                    // Segment `buf` directly — there is nothing to accumulate, so the `frame`
115                    // buffer is left untouched. Segments drain on the next poll_write / poll_flush.
116                    if *this.datagram {
117                        if buf.is_empty() {
118                            return Poll::Ready(Ok(0));
119                        }
120                        segment_into(buf, session_socket_mtu::<C>(), *this.frame_id, this.ready_segments)
121                            .map_err(std::io::Error::other)?;
122
123                        tracing::trace!(
124                            num_segments = this.ready_segments.len(),
125                            datagram_len = buf.len(),
126                            "datagram frame ready"
127                        );
128
129                        *this.frame_id += 1;
130                        *this.state = State::WritingFrame;
131
132                        return Poll::Ready(Ok(buf.len()));
133                    }
134
135                    // If there's space in the frame, keep writing to it
136                    if *this.frame_size > this.frame.len() {
137                        let to_write = buf.len().min(*this.frame_size - this.frame.len());
138                        this.frame.extend_from_slice(&buf[..to_write]);
139
140                        return Poll::Ready(Ok(to_write));
141                    } else {
142                        // No more space in the frame buffer, we need to segment it
143                        // and write segments to the downstream
144                        segment_into(
145                            this.frame.as_slice(),
146                            session_socket_mtu::<C>(),
147                            *this.frame_id,
148                            this.ready_segments,
149                        )
150                        .map_err(std::io::Error::other)?;
151
152                        tracing::trace!(num_segments = this.ready_segments.len(), "frame ready");
153
154                        this.frame.clear();
155                        *this.frame_id += 1;
156                        *this.state = State::WritingFrame;
157                    }
158                }
159                State::WritingFrame => {
160                    if !this.ready_segments.is_empty() {
161                        // Keep writing segments to downstream
162                        futures::ready!(this.inner.as_mut().poll_ready(cx).map_err(std::io::Error::other))?;
163
164                        let segment = this.ready_segments.pop_front().unwrap();
165                        tracing::trace!(seg_id = %segment.id(), "segment goes out");
166                        this.inner.as_mut().start_send(segment).map_err(std::io::Error::other)?;
167                    } else {
168                        // Once we're done, we can buffer another frame
169                        *this.state = State::BufferingFrame;
170                        tracing::trace!("all segments out");
171                    }
172                }
173            }
174        }
175    }
176
177    #[instrument(name = "Segmenter::poll_flush", level = "trace", skip(self, cx), fields(frame_id = self.frame_id, frame_size = self.frame.len(), ready_segments = self.ready_segments.len()), ret)]
178    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
179        if self.is_closed {
180            return Poll::Ready(Err(std::io::Error::new(
181                std::io::ErrorKind::BrokenPipe,
182                "segmenter closed",
183            )));
184        }
185
186        let mut this = self.project();
187        loop {
188            // If there's any data in the unfinished frame, segment it
189            if !this.frame.is_empty() {
190                // Flush the downstream sink first
191                futures::ready!(this.inner.as_mut().poll_flush(cx).map_err(std::io::Error::other))?;
192
193                // Segment whatever data is in the frame
194                // At this point ready_segments must be empty,
195                // because poll_write always makes sure it is before returning Ready
196                segment_into(
197                    this.frame.as_slice(),
198                    session_socket_mtu::<C>(),
199                    *this.frame_id,
200                    this.ready_segments,
201                )
202                .map_err(std::io::Error::other)?;
203
204                tracing::trace!(num_segments = this.ready_segments.len(), "flushed frame ready");
205
206                this.frame.clear();
207                *this.frame_id += 1;
208            } else if !this.ready_segments.is_empty() {
209                futures::ready!(this.inner.as_mut().poll_ready(cx).map_err(std::io::Error::other))?;
210
211                let segment = this.ready_segments.pop_front().unwrap();
212                tracing::trace!(seg_id = %segment.id(), "segment flushing out");
213
214                this.inner.as_mut().start_send(segment).map_err(std::io::Error::other)?;
215            } else {
216                // Both buffers are empty, so only flush the downstream
217                futures::ready!(this.inner.as_mut().poll_flush(cx).map_err(std::io::Error::other))?;
218
219                tracing::trace!("all segments flushed out");
220                return Poll::Ready(Ok(()));
221            }
222        }
223    }
224
225    #[instrument(name = "Segmenter::poll_close", level = "trace", skip(self, cx), fields(frame_id = self.frame_id) , ret)]
226    fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
227        let mut this = self.project();
228
229        if *this.send_terminating_segment && !*this.is_closed {
230            futures::ready!(this.inner.as_mut().poll_ready(cx).map_err(std::io::Error::other))?;
231            let dummy = Segment::terminating(*this.frame_id);
232            this.inner.as_mut().start_send(dummy).map_err(std::io::Error::other)?;
233            tracing::trace!("sent terminating segment");
234        }
235
236        *this.is_closed = true;
237        this.inner.as_mut().poll_close(cx).map_err(std::io::Error::other)
238    }
239}
240
241/// Sink extension methods for segmenting binary data into a sink.
242pub trait SegmenterExt: futures::Sink<Segment> {
243    /// Attaches a [`Segmenter`] to the underlying sink.
244    fn segmenter<const C: usize>(self, frame_size: usize) -> Segmenter<C, Self>
245    where
246        Self: Sized,
247        Self::Error: std::error::Error + Send + Sync + 'static,
248    {
249        Segmenter::new(self, frame_size, false, false)
250    }
251
252    /// Attaches a [`Segmenter`] to the underlying sink.
253    /// The `Segmenter` also sends a [terminating](Segment::terminating) when closed.
254    ///
255    /// When `datagram` is set, each write is emitted as exactly one frame (datagram boundaries are
256    /// preserved) instead of being coalesced up to `frame_size`.
257    fn segmenter_with_terminating_segment<const C: usize>(self, frame_size: usize, datagram: bool) -> Segmenter<C, Self>
258    where
259        Self: Sized,
260        Self::Error: std::error::Error + Send + Sync + 'static,
261    {
262        Segmenter::new(self, frame_size, true, datagram)
263    }
264}
265
266impl<T: ?Sized> SegmenterExt for T where T: futures::Sink<Segment> {}
267
268#[cfg(test)]
269mod tests {
270    use anyhow::{Context, anyhow};
271    use futures::{AsyncWriteExt, Stream, StreamExt, pin_mut};
272    use futures_time::future::FutureExt;
273
274    use super::*;
275    use crate::{
276        MAX_SESSION_MTU,
277        protocol::{SeqNum, SessionMessage},
278        utils::segment,
279    };
280
281    const MTU: usize = 1000;
282    const SMTU: usize = MTU - SessionMessage::<MTU>::SEGMENT_OVERHEAD;
283    const FRAME_SIZE: usize = MAX_SESSION_MTU;
284
285    const SEGMENTS_PER_FRAME: usize = FRAME_SIZE / MTU + 1;
286
287    async fn assert_frame_segments(
288        start_frame_id: FrameId,
289        num_frames: usize,
290        segments: &mut (impl Stream<Item = Segment> + Unpin),
291        data: &[u8],
292    ) -> anyhow::Result<()> {
293        for i in 0..num_frames * SEGMENTS_PER_FRAME {
294            let start_frame_id = start_frame_id as usize;
295            let frame_id = i / SEGMENTS_PER_FRAME + start_frame_id;
296            tracing::debug!("testing frame id {frame_id} {}", (i % SEGMENTS_PER_FRAME) as SeqNum);
297
298            let seg = segments
299                .next()
300                .timeout(futures_time::time::Duration::from_millis(500))
301                .await
302                .context(format!("assert_frame_segments {i}"))?
303                .ok_or(anyhow!("no more segments"))?;
304
305            assert_eq!(frame_id as FrameId, seg.frame_id);
306            assert_eq!((i % SEGMENTS_PER_FRAME) as SeqNum, seg.seq_idx);
307            assert_eq!((FRAME_SIZE / MTU + 1) as SeqNum, seg.seq_flags.seq_len());
308            if i % SEGMENTS_PER_FRAME == 0 {
309                assert_eq!(SMTU, seg.data.len());
310                assert_eq!(
311                    &data[(frame_id - start_frame_id) * FRAME_SIZE + i % SEGMENTS_PER_FRAME * SMTU
312                        ..(frame_id - start_frame_id) * FRAME_SIZE + i % SEGMENTS_PER_FRAME * SMTU + SMTU],
313                    seg.data.as_ref()
314                );
315            } else {
316                assert_eq!(FRAME_SIZE % SMTU, seg.data.len());
317                assert_eq!(
318                    &data[(frame_id - start_frame_id) * FRAME_SIZE + i % SEGMENTS_PER_FRAME * SMTU
319                        ..(frame_id - start_frame_id) * FRAME_SIZE + i % SEGMENTS_PER_FRAME * SMTU + FRAME_SIZE % SMTU],
320                    seg.data.as_ref()
321                );
322            }
323        }
324
325        Ok(())
326    }
327
328    #[tokio::test]
329    async fn segmenter_should_not_segment_small_data_unless_flushed() -> anyhow::Result<()> {
330        let (segments_tx, segments) = futures::channel::mpsc::unbounded();
331        let mut writer = segments_tx.segmenter::<MTU>(FRAME_SIZE);
332
333        writer.write_all(b"test").await?;
334
335        pin_mut!(segments);
336        segments
337            .next()
338            .timeout(futures_time::time::Duration::from_millis(10))
339            .await
340            .expect_err("should time out");
341
342        writer.flush().await?;
343
344        let seg = segments.next().await.ok_or(anyhow!("no more segments"))?;
345        assert_eq!(1, seg.frame_id);
346        assert_eq!(1, seg.seq_flags.seq_len());
347        assert_eq!(0, seg.seq_idx);
348        assert_eq!(b"test", seg.data.as_ref());
349
350        Ok(())
351    }
352
353    #[tokio::test]
354    async fn datagram_mode_emits_one_frame_per_write() -> anyhow::Result<()> {
355        let (segments_tx, segments) = futures::channel::mpsc::unbounded();
356        let mut writer = segments_tx.segmenter_with_terminating_segment::<MTU>(FRAME_SIZE, true);
357        pin_mut!(segments);
358
359        // Two small datagrams that would coalesce into a single frame in byte-stream mode. In
360        // datagram mode each write is its own frame (distinct frame_id), so the boundary is kept.
361        writer.write_all(b"hello").await?;
362        writer.write_all(b"world").await?;
363        writer.flush().await?;
364
365        let first = segments.next().await.ok_or(anyhow!("no first datagram"))?;
366        assert_eq!(1, first.frame_id);
367        assert_eq!(0, first.seq_idx);
368        assert_eq!(1, first.seq_flags.seq_len(), "single-segment datagram");
369        assert_eq!(b"hello", first.data.as_ref());
370
371        let second = segments.next().await.ok_or(anyhow!("no second datagram"))?;
372        assert_eq!(2, second.frame_id, "each write is a distinct frame");
373        assert_eq!(0, second.seq_idx);
374        assert_eq!(1, second.seq_flags.seq_len());
375        assert_eq!(b"world", second.data.as_ref());
376
377        Ok(())
378    }
379
380    #[tokio::test]
381    async fn datagram_mode_keeps_a_multi_segment_datagram_in_one_frame() -> anyhow::Result<()> {
382        const DATAGRAM_MTU: usize = hopr_crypto_packet::prelude::HoprPacket::PAYLOAD_SIZE;
383        let segment_size = session_socket_mtu::<DATAGRAM_MTU>();
384        let (segments_tx, segments) = futures::channel::mpsc::unbounded();
385        let mut writer = segments_tx.segmenter_with_terminating_segment::<DATAGRAM_MTU>(FRAME_SIZE, true);
386        pin_mut!(segments);
387
388        // A datagram larger than one segment (and larger than frame_size) stays a single frame: all
389        // segments share one frame_id/seq_len with contiguous indices, matching a direct segment().
390        let datagram = vec![0xABu8; segment_size * 2 + 10];
391        writer.write_all(&datagram).await?;
392        writer.flush().await?;
393
394        for expected in segment(&datagram, segment_size, 1)? {
395            let seg = segments
396                .next()
397                .timeout(futures_time::time::Duration::from_millis(500))
398                .await
399                .context("multi-segment datagram")?
400                .ok_or(anyhow!("no more segments"))?;
401            assert_eq!(1, seg.frame_id, "one frame_id for the whole datagram");
402            assert_eq!(expected.seq_idx, seg.seq_idx);
403            assert_eq!(expected.seq_flags.seq_len(), seg.seq_flags.seq_len());
404            assert_eq!(expected.data.as_ref(), seg.data.as_ref());
405        }
406
407        Ok(())
408    }
409
410    #[parameterized::parameterized(num_frames = { 1, 3, 5, 11 })]
411    #[parameterized_macro(tokio::test)]
412    async fn segmenter_should_segment_complete_frames(num_frames: usize) -> anyhow::Result<()> {
413        let (segments_tx, segments) = futures::channel::mpsc::unbounded();
414        let mut writer = segments_tx.segmenter::<MTU>(FRAME_SIZE);
415
416        let mut all_data = Vec::new();
417        for _ in 0..num_frames {
418            let data = hopr_types::crypto_random::random_bytes::<FRAME_SIZE>();
419            writer.write_all(&data).await?;
420            all_data.extend(data);
421        }
422
423        writer.flush().await?;
424
425        pin_mut!(segments);
426        assert_frame_segments(1, num_frames, &mut segments, &all_data).await?;
427
428        writer.close().await?;
429
430        assert_eq!(None, segments.next().await);
431        Ok(())
432    }
433
434    #[tokio::test]
435    async fn segmenter_full_frame_segmentation_must_be_consistent_with_segment_function() -> anyhow::Result<()> {
436        let (segments_tx, segments) = futures::channel::mpsc::unbounded();
437        let mut writer = segments_tx.segmenter::<MTU>(FRAME_SIZE);
438
439        let data = hopr_types::crypto_random::random_bytes::<FRAME_SIZE>();
440
441        writer.write_all(&data).await?;
442        writer.flush().await?;
443        writer.close().await?;
444
445        // Segmenter already takes into account the SessionMessage overhead
446        let expected = segment(data, SMTU, 1)?;
447        let actual = segments.collect::<Vec<_>>().await;
448
449        assert_eq!(expected, actual);
450
451        Ok(())
452    }
453
454    #[test_log::test(tokio::test)]
455    async fn segmenter_full_frame_segmentation_must_also_include_terminating_segment() -> anyhow::Result<()> {
456        let (segments_tx, segments) = futures::channel::mpsc::unbounded();
457        let mut writer = segments_tx.segmenter_with_terminating_segment::<MTU>(FRAME_SIZE, false);
458
459        let data = hopr_types::crypto_random::random_bytes::<FRAME_SIZE>();
460
461        writer.write_all(&data).await?;
462        writer.flush().await?;
463        writer.close().await?;
464
465        // Segmenter already takes into account the SessionMessage overhead
466        let mut expected = segment(data, SMTU, 1)?;
467        expected.push(Segment::terminating(2));
468        let actual = segments.collect::<Vec<_>>().await;
469
470        assert_eq!(expected, actual);
471
472        Ok(())
473    }
474
475    #[test_log::test(tokio::test)]
476    async fn segmenter_should_segment_complete_frame_with_misaligned_mtu() -> anyhow::Result<()> {
477        let (segments_tx, segments) = futures::channel::mpsc::unbounded();
478        let mut writer = segments_tx.segmenter::<MTU>(FRAME_SIZE);
479
480        // Make sure the FRAME_SIZE is not a multiple of MTU
481        assert_ne!(0, FRAME_SIZE % MTU);
482
483        let data = hopr_types::crypto_random::random_bytes::<FRAME_SIZE>();
484        writer.write_all(&data).await?;
485        writer.flush().await?;
486        writer.close().await?;
487
488        pin_mut!(segments);
489
490        for i in 0..(FRAME_SIZE / MTU) {
491            let seg = segments.next().await.ok_or(anyhow!("no more segments"))?;
492            assert_eq!(1, seg.frame_id);
493            assert_eq!(i as SeqNum, seg.seq_idx);
494            assert_eq!(((FRAME_SIZE / SMTU) + 1) as SeqNum, seg.seq_flags.seq_len());
495            assert_eq!(SMTU, seg.data.len());
496            assert_eq!(&data[i * SMTU..i * SMTU + SMTU], seg.data.as_ref());
497        }
498
499        let seg = segments.next().await.ok_or(anyhow!("no more segments"))?;
500        assert_eq!(1, seg.frame_id);
501        assert_eq!((FRAME_SIZE / SMTU) as SeqNum, seg.seq_idx);
502        assert_eq!(((FRAME_SIZE / SMTU) + 1) as SeqNum, seg.seq_flags.seq_len());
503        assert_eq!(FRAME_SIZE % SMTU, seg.data.len());
504        assert_eq!(&data[FRAME_SIZE - FRAME_SIZE % SMTU..], seg.data.as_ref());
505
506        assert_eq!(None, segments.next().await);
507        Ok(())
508    }
509
510    #[test_log::test(tokio::test)]
511    async fn segmenter_should_segment_multiple_complete_frames_and_incomplete_frame_on_flush() -> anyhow::Result<()> {
512        let (segments_tx, segments) = futures::channel::mpsc::unbounded();
513        let mut writer = segments_tx.segmenter::<MTU>(FRAME_SIZE);
514
515        let data = hopr_types::crypto_random::random_bytes::<{ FRAME_SIZE + 4 }>();
516        writer.write_all(&data).await?;
517
518        pin_mut!(segments);
519
520        // The first frame should come out even without a flush
521        assert_frame_segments(1, 1, &mut segments, &data).await?;
522
523        // And no more segment comes out for the remaining bytes
524        segments
525            .next()
526            .timeout(futures_time::time::Duration::from_millis(10))
527            .await
528            .expect_err("should time out");
529
530        // ... until it is flushed
531        writer.flush().await?;
532
533        let seg = segments
534            .next()
535            .timeout(futures_time::time::Duration::from_millis(500))
536            .await?
537            .ok_or(anyhow!("no more segments"))?;
538        assert_eq!(2, seg.frame_id);
539        assert_eq!(0, seg.seq_idx);
540        assert_eq!(1, seg.seq_flags.seq_len());
541        assert_eq!(4, seg.data.len());
542        assert_eq!(&data[FRAME_SIZE..], seg.data.as_ref());
543
544        // The next full frame should come out normally after a flush
545        let data = hopr_types::crypto_random::random_bytes::<FRAME_SIZE>();
546        writer.write_all(&data).await?;
547        writer.flush().await?;
548
549        assert_frame_segments(3, 1, &mut segments, &data).await?;
550
551        Ok(())
552    }
553
554    #[test_log::test(tokio::test)]
555    async fn segmenter_should_work_with_buffering_backend() -> anyhow::Result<()> {
556        let (tx, rx) = futures::channel::mpsc::channel(5);
557        let mut writer = tx.segmenter::<MTU>(FRAME_SIZE);
558
559        let data = hopr_types::crypto_random::random_bytes::<{ 10 * FRAME_SIZE }>();
560
561        let jh_recv = tokio::task::spawn(
562            rx.collect::<Vec<_>>()
563                .delay(futures_time::time::Duration::from_millis(200)),
564        );
565        let jh_send = tokio::task::spawn(async move {
566            writer.write_all(&data).await?;
567            writer.flush().await?;
568            writer.close().await?;
569            Ok::<_, std::io::Error>(())
570        });
571
572        let (segments, send_res) = futures::future::try_join(jh_recv, jh_send).await?;
573        send_res?;
574
575        assert_frame_segments(1, 10, &mut futures::stream::iter(segments), &data).await
576    }
577}