Skip to main content

hopr_protocol_session/processing/
types.rs

1use std::time::Instant;
2
3use crate::{
4    errors::SessionError,
5    protocol::{Frame, FrameId, MissingSegmentsBitmap, Segment, SeqNum},
6};
7
8/// A helper object that reassembles segments into frames.
9#[derive(Debug)]
10pub struct FrameBuilder {
11    segments: Vec<Option<Segment>>,
12    frame_id: FrameId,
13    seg_remaining: SeqNum,
14    recv_bytes: usize,
15    pub(crate) last_recv: Instant,
16    /// When the frame's first segment arrived.
17    pub(crate) created: Instant,
18}
19
20impl From<Segment> for FrameBuilder {
21    fn from(value: Segment) -> Self {
22        let idx = value.seq_idx;
23        let mut ret = Self {
24            segments: vec![None; value.seq_flags.seq_len() as usize],
25            frame_id: value.frame_id,
26            seg_remaining: value.seq_flags.seq_len() - 1,
27            recv_bytes: value.data.len(),
28            last_recv: Instant::now(),
29            created: Instant::now(),
30        };
31
32        ret.segments[idx as usize] = Some(value);
33
34        ret
35    }
36}
37
38impl FrameBuilder {
39    /// Adds a segment to this frame.
40    ///
41    /// Fails if the segment is invalid for this frame.
42    pub fn add_segment(&mut self, segment: Segment) -> Result<(), SessionError> {
43        let idx = segment.seq_idx;
44        if segment.frame_id != self.frame_id
45            || idx as usize >= self.segments.len()
46            || segment.seq_flags.seq_len() as usize != self.segments.len()
47            || self.seg_remaining == 0
48            || self.segments[idx as usize].is_some()
49        {
50            return Err(SessionError::InvalidSegment);
51        }
52
53        self.recv_bytes += segment.data.len();
54        self.seg_remaining -= 1;
55        self.segments[idx as usize] = Some(segment);
56        self.last_recv = Instant::now();
57        Ok(())
58    }
59
60    /// Retrieves the bitmap of missing segments in this frame.
61    pub fn as_missing(&self) -> MissingSegmentsBitmap {
62        let mut ret = MissingSegmentsBitmap::ZERO;
63        self.segments
64            .iter()
65            .take(SeqNum::BITS as usize)
66            .enumerate()
67            .for_each(|(i, v)| ret.set(i, v.is_none()));
68        ret
69    }
70
71    /// Retrieves the frame's ID.
72    #[inline]
73    pub fn frame_id(&self) -> FrameId {
74        self.frame_id
75    }
76
77    /// Indicates if all segments of this frame were added.
78    #[inline]
79    pub fn is_complete(&self) -> bool {
80        self.seg_remaining == 0
81    }
82}
83
84impl TryFrom<FrameBuilder> for Frame {
85    type Error = SessionError;
86
87    fn try_from(value: FrameBuilder) -> Result<Self, Self::Error> {
88        // The Frame has the terminating flag set
89        // if any of its segments had the terminating indicator set
90        let mut is_terminating = false;
91        value
92            .segments
93            .into_iter()
94            .try_fold(Vec::with_capacity(value.recv_bytes), |mut acc, segment| match segment {
95                Some(segment) => {
96                    acc.extend_from_slice(&segment.data);
97                    is_terminating = is_terminating || segment.seq_flags.is_terminating();
98                    Ok(acc)
99                }
100                None => Err(SessionError::IncompleteFrame(value.frame_id)),
101            })
102            .map(|data| Frame {
103                frame_id: value.frame_id,
104                data: data.into_boxed_slice(),
105                is_terminating,
106            })
107    }
108}
109
110/// Allows inspecting incomplete frame buffer inside the Reassembler.
111// Must use only FrameDashMap, others cannot be reference-cloned
112#[derive(Clone, Debug)]
113pub struct FrameInspector(pub(crate) FrameDashMap);
114
115impl FrameInspector {
116    /// Indicates how many incomplete frames there could be per one complete/discarded frame.
117    pub const INCOMPLETE_FRAME_RATIO: usize = 2;
118
119    pub fn new(capacity: usize) -> Self {
120        Self(FrameDashMap::with_capacity(Self::INCOMPLETE_FRAME_RATIO * capacity + 1))
121    }
122
123    /// Returns a bitmap of missing segments in a frame.
124    pub fn missing_segments(&self, frame_id: &FrameId) -> Option<MissingSegmentsBitmap> {
125        self.0.0.get(frame_id).map(|f| f.as_missing())
126    }
127
128    /// Number of incomplete frames.
129    pub fn len(&self) -> usize {
130        self.0.len()
131    }
132
133    /// Checks if there are no incomplete frames.
134    pub fn is_empty(&self) -> bool {
135        self.0.is_empty()
136    }
137}
138
139/// Trait describing an occupied entry in a [`FrameMap`].
140///
141/// See [`FrameMap::entry`] for details.
142pub trait FrameMapOccupiedEntry {
143    /// Gets mutable reference to the builder assigned to this frame.
144    fn get_builder_mut(&mut self) -> &mut FrameBuilder;
145
146    #[allow(unused)]
147    fn frame_id(&self) -> &FrameId;
148
149    /// Removes the entry and returns the associated [`FrameBuilder`].
150    /// The `FrameBuilder` may or may not be [complete](FrameBuilder::is_complete).
151    fn finalize(self) -> FrameBuilder;
152}
153
154/// Trait describing a vacant entry in a [`FrameMap`].
155///
156/// See [`FrameMap::entry`] for details.
157pub trait FrameMapVacantEntry {
158    /// Insert a new [`FrameBuilder`] into the empty entry.
159    fn insert_builder(self, value: FrameBuilder);
160}
161
162#[derive(strum::EnumTryAs)]
163pub enum FrameMapEntry<O: FrameMapOccupiedEntry, V: FrameMapVacantEntry> {
164    Occupied(O),
165    Vacant(V),
166}
167
168/// An abstraction of a Hash Map, suitable for reassembling frames.
169pub trait FrameMap {
170    type ExistingEntry<'a>: FrameMapOccupiedEntry
171    where
172        Self: 'a;
173    type VacantEntry<'a>: FrameMapVacantEntry
174    where
175        Self: 'a;
176
177    /// Creates a new map with the given capacity.
178    fn with_capacity(capacity: usize) -> Self;
179
180    /// Returns the [`FrameMapEntry`] API for a vacant or existing entry.
181    fn entry(&mut self, frame_id: FrameId) -> FrameMapEntry<Self::ExistingEntry<'_>, Self::VacantEntry<'_>>;
182
183    /// Number of elements in the map.
184    fn len(&self) -> usize;
185
186    /// Indicates whether the map is empty.
187    ///
188    /// Defaults to check if the [`FrameMap::len`] is 0.
189    fn is_empty(&self) -> bool {
190        self.len() == 0
191    }
192
193    /// Removes all elements from the map, for which the given predicate evaluates to `false`.
194    fn retain(&mut self, f: impl FnMut(&FrameId, &mut FrameBuilder) -> bool);
195}
196
197impl FrameMapOccupiedEntry for dashmap::OccupiedEntry<'_, FrameId, FrameBuilder> {
198    fn get_builder_mut(&mut self) -> &mut FrameBuilder {
199        self.get_mut()
200    }
201
202    fn frame_id(&self) -> &FrameId {
203        self.key()
204    }
205
206    fn finalize(self) -> FrameBuilder {
207        self.remove()
208    }
209}
210
211impl FrameMapVacantEntry for dashmap::VacantEntry<'_, FrameId, FrameBuilder> {
212    fn insert_builder(self, value: FrameBuilder) {
213        self.insert(value);
214    }
215}
216
217/// A [`FrameMap`] implementation using reference-counted `dashmap::DashMap` as a backend.
218#[derive(Clone, Debug)]
219pub struct FrameDashMap(std::sync::Arc<dashmap::DashMap<FrameId, FrameBuilder>>);
220
221impl FrameMap for FrameDashMap {
222    type ExistingEntry<'a> = dashmap::OccupiedEntry<'a, FrameId, FrameBuilder>;
223    type VacantEntry<'a> = dashmap::VacantEntry<'a, FrameId, FrameBuilder>;
224
225    fn with_capacity(capacity: usize) -> Self {
226        Self(std::sync::Arc::new(dashmap::DashMap::with_capacity(capacity)))
227    }
228
229    fn entry(&mut self, frame_id: FrameId) -> FrameMapEntry<Self::ExistingEntry<'_>, Self::VacantEntry<'_>> {
230        match self.0.entry(frame_id) {
231            dashmap::Entry::Occupied(e) => FrameMapEntry::Occupied(e),
232            dashmap::Entry::Vacant(v) => FrameMapEntry::Vacant(v),
233        }
234    }
235
236    fn len(&self) -> usize {
237        self.0.len()
238    }
239
240    fn is_empty(&self) -> bool {
241        self.0.is_empty()
242    }
243
244    fn retain(&mut self, f: impl FnMut(&FrameId, &mut FrameBuilder) -> bool) {
245        self.0.retain(f)
246    }
247}
248
249/// A [`FrameMap`] implementation using `std::collections::HashMap` as backend.
250#[cfg(not(feature = "hashbrown"))]
251pub struct FrameHashMap(std::collections::HashMap<FrameId, FrameBuilder>);
252
253#[cfg(not(feature = "hashbrown"))]
254impl FrameMapOccupiedEntry for std::collections::hash_map::OccupiedEntry<'_, FrameId, FrameBuilder> {
255    fn get_builder_mut(&mut self) -> &mut FrameBuilder {
256        self.get_mut()
257    }
258
259    fn frame_id(&self) -> &FrameId {
260        self.key()
261    }
262
263    fn finalize(self) -> FrameBuilder {
264        self.remove()
265    }
266}
267
268#[cfg(not(feature = "hashbrown"))]
269impl FrameMapVacantEntry for std::collections::hash_map::VacantEntry<'_, FrameId, FrameBuilder> {
270    fn insert_builder(self, value: FrameBuilder) {
271        self.insert(value);
272    }
273}
274
275#[cfg(not(feature = "hashbrown"))]
276impl FrameMap for FrameHashMap {
277    type ExistingEntry<'a> = std::collections::hash_map::OccupiedEntry<'a, FrameId, FrameBuilder>;
278    type VacantEntry<'a> = std::collections::hash_map::VacantEntry<'a, FrameId, FrameBuilder>;
279
280    fn with_capacity(capacity: usize) -> Self {
281        Self(std::collections::HashMap::with_capacity(capacity))
282    }
283
284    fn entry(&mut self, frame_id: FrameId) -> FrameMapEntry<Self::ExistingEntry<'_>, Self::VacantEntry<'_>> {
285        match self.0.entry(frame_id) {
286            std::collections::hash_map::Entry::Occupied(e) => FrameMapEntry::Occupied(e),
287            std::collections::hash_map::Entry::Vacant(v) => FrameMapEntry::Vacant(v),
288        }
289    }
290
291    fn len(&self) -> usize {
292        self.0.len()
293    }
294
295    fn is_empty(&self) -> bool {
296        self.0.is_empty()
297    }
298
299    fn retain(&mut self, f: impl FnMut(&FrameId, &mut FrameBuilder) -> bool) {
300        self.0.retain(f)
301    }
302}
303
304/// A [`FrameMap`] implementation using `hashbrown::HashMap` as backend.
305#[cfg(feature = "hashbrown")]
306pub struct FrameHashMap(hashbrown::HashMap<FrameId, FrameBuilder>);
307
308#[cfg(feature = "hashbrown")]
309impl FrameMapOccupiedEntry for hashbrown::hash_map::OccupiedEntry<'_, FrameId, FrameBuilder> {
310    fn get_builder_mut(&mut self) -> &mut FrameBuilder {
311        self.get_mut()
312    }
313
314    fn frame_id(&self) -> &FrameId {
315        self.key()
316    }
317
318    fn finalize(self) -> FrameBuilder {
319        self.remove()
320    }
321}
322
323#[cfg(feature = "hashbrown")]
324impl FrameMapVacantEntry for hashbrown::hash_map::VacantEntry<'_, FrameId, FrameBuilder> {
325    fn insert_builder(self, value: FrameBuilder) {
326        self.insert(value);
327    }
328}
329
330#[cfg(feature = "hashbrown")]
331impl FrameMap for FrameHashMap {
332    type ExistingEntry<'a> = hashbrown::hash_map::OccupiedEntry<'a, FrameId, FrameBuilder>;
333    type VacantEntry<'a> = hashbrown::hash_map::VacantEntry<'a, FrameId, FrameBuilder>;
334
335    fn with_capacity(capacity: usize) -> Self {
336        Self(hashbrown::HashMap::with_capacity(capacity))
337    }
338
339    fn entry(&mut self, frame_id: FrameId) -> FrameMapEntry<Self::ExistingEntry<'_>, Self::VacantEntry<'_>> {
340        match self.0.entry(frame_id) {
341            hashbrown::hash_map::Entry::Occupied(e) => FrameMapEntry::Occupied(e),
342            hashbrown::hash_map::Entry::Vacant(v) => FrameMapEntry::Vacant(v),
343        }
344    }
345
346    fn len(&self) -> usize {
347        self.0.len()
348    }
349
350    fn is_empty(&self) -> bool {
351        self.0.is_empty()
352    }
353
354    fn retain(&mut self, f: impl FnMut(&FrameId, &mut FrameBuilder) -> bool) {
355        self.0.retain(f)
356    }
357}
358
359#[cfg(test)]
360mod tests {
361    use super::*;
362    use crate::protocol::SeqIndicator;
363
364    #[test]
365    fn frame_builder_should_return_ordered_segments() -> anyhow::Result<()> {
366        let mut fb = FrameBuilder::from(Segment {
367            frame_id: 1,
368            seq_idx: 1,
369            seq_flags: 3.try_into()?,
370            data: (*b" new ").into(),
371        });
372
373        fb.add_segment(Segment {
374            frame_id: 1,
375            seq_idx: 2,
376            seq_flags: 3.try_into()?,
377            data: (*b"world").into(),
378        })?;
379
380        fb.add_segment(Segment {
381            frame_id: 1,
382            seq_idx: 0,
383            seq_flags: 3.try_into()?,
384            data: (*b"hello").into(),
385        })?;
386
387        assert!(fb.is_complete());
388        assert_eq!(MissingSegmentsBitmap::ZERO, fb.as_missing());
389
390        let reassembled: Frame = fb.try_into()?;
391        assert_eq!(1, reassembled.frame_id);
392        assert_eq!(b"hello new world", reassembled.data.as_ref());
393
394        Ok(())
395    }
396
397    #[test]
398    fn frame_builder_should_correctly_mark_terminating_flag() -> anyhow::Result<()> {
399        let mut fb = FrameBuilder::from(Segment {
400            frame_id: 1,
401            seq_idx: 1,
402            seq_flags: 3.try_into()?,
403            data: (*b" new ").into(),
404        });
405
406        fb.add_segment(Segment {
407            frame_id: 1,
408            seq_idx: 2,
409            seq_flags: SeqIndicator::new_with_flags(3, true),
410            data: (*b"world").into(),
411        })?;
412
413        fb.add_segment(Segment {
414            frame_id: 1,
415            seq_idx: 0,
416            seq_flags: 3.try_into()?,
417            data: (*b"hello").into(),
418        })?;
419
420        assert!(fb.is_complete());
421        assert_eq!(MissingSegmentsBitmap::ZERO, fb.as_missing());
422
423        let reassembled: Frame = fb.try_into()?;
424        assert_eq!(1, reassembled.frame_id);
425        assert_eq!(b"hello new world", reassembled.data.as_ref());
426        assert!(reassembled.is_terminating);
427
428        Ok(())
429    }
430
431    #[test]
432    fn frame_builder_should_correctly_allow_empty_segments() -> anyhow::Result<()> {
433        let mut fb = FrameBuilder::from(Segment {
434            frame_id: 1,
435            seq_idx: 1,
436            seq_flags: 4.try_into()?,
437            data: (*b" new ").into(),
438        });
439
440        fb.add_segment(Segment {
441            frame_id: 1,
442            seq_idx: 2,
443            seq_flags: 4.try_into()?,
444            data: (*b"world").into(),
445        })?;
446
447        fb.add_segment(Segment {
448            frame_id: 1,
449            seq_idx: 0,
450            seq_flags: 4.try_into()?,
451            data: (*b"hello").into(),
452        })?;
453
454        fb.add_segment(Segment {
455            frame_id: 1,
456            seq_idx: 3,
457            seq_flags: SeqIndicator::new_with_flags(4, true),
458            data: Box::new([]),
459        })?;
460
461        assert!(fb.is_complete());
462        assert_eq!(MissingSegmentsBitmap::ZERO, fb.as_missing());
463
464        let reassembled: Frame = fb.try_into()?;
465        assert_eq!(1, reassembled.frame_id);
466        assert_eq!(b"hello new world", reassembled.data.as_ref());
467        assert!(reassembled.is_terminating);
468
469        Ok(())
470    }
471
472    #[test]
473    fn frame_builder_should_not_accept_invalid_segments() -> anyhow::Result<()> {
474        let mut fb = FrameBuilder::from(Segment {
475            frame_id: 1,
476            seq_idx: 0,
477            seq_flags: 2.try_into()?,
478            data: (*b"hello world").into(),
479        });
480
481        fb.add_segment(Segment {
482            frame_id: 1,
483            seq_idx: 3,
484            seq_flags: 2.try_into()?,
485            data: (*b"foo").into(),
486        })
487        .expect_err("should not accept invalid segment");
488
489        fb.add_segment(Segment {
490            frame_id: 2,
491            seq_idx: 1,
492            seq_flags: 2.try_into()?,
493            data: (*b"foo").into(),
494        })
495        .expect_err("should not accept segment from another frame");
496
497        fb.add_segment(Segment {
498            frame_id: 1,
499            seq_idx: 1,
500            seq_flags: 3.try_into()?,
501            data: (*b"foo").into(),
502        })
503        .expect_err("should not accept invalid segment");
504
505        Ok(())
506    }
507
508    #[test]
509    fn frame_builder_should_not_accept_segments_when_complete() -> anyhow::Result<()> {
510        let mut fb = FrameBuilder::from(Segment {
511            frame_id: 1,
512            seq_idx: 0,
513            seq_flags: 1.try_into()?,
514            data: (*b"hello world").into(),
515        });
516
517        fb.add_segment(Segment {
518            frame_id: 1,
519            seq_idx: 0,
520            seq_flags: 1.try_into()?,
521            data: (*b"foo").into(),
522        })
523        .expect_err("should not accept segment when complete");
524
525        Ok(())
526    }
527
528    #[test]
529    fn frame_builder_should_not_accept_duplicate_segment() -> anyhow::Result<()> {
530        let mut fb = FrameBuilder::from(Segment {
531            frame_id: 1,
532            seq_idx: 0,
533            seq_flags: 2.try_into()?,
534            data: (*b"hello world").into(),
535        });
536
537        fb.add_segment(Segment {
538            frame_id: 1,
539            seq_idx: 0,
540            seq_flags: 2.try_into()?,
541            data: (*b"foo").into(),
542        })
543        .expect_err("should not accept duplicate segment");
544
545        Ok(())
546    }
547}