1use 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#[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: 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 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 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 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 *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 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 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 *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 !this.frame.is_empty() {
190 futures::ready!(this.inner.as_mut().poll_flush(cx).map_err(std::io::Error::other))?;
192
193 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 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
241pub trait SegmenterExt: futures::Sink<Segment> {
243 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 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 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 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 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 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 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 assert_frame_segments(1, 1, &mut segments, &data).await?;
522
523 segments
525 .next()
526 .timeout(futures_time::time::Duration::from_millis(10))
527 .await
528 .expect_err("should time out");
529
530 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 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}