Skip to main content

hopr_protocol_session/protocol/
mod.rs

1//! # `Session` protocol messages
2//!
3//! The protocol components are built via low-level types of the `frame` module, such as
4//! [`Segment`] and [`Frame`].
5//! Most importantly, the `Session` protocol fixes the maximum number of segments per frame
6//! to 8 (see `SessionMessage::MAX_SEGMENTS_PER_FRAME`).
7//! Since each segment must fit within a maximum transmission unit (MTU),
8//! a frame can be at most *eight* times the size of the MTU.
9//!
10//! The [current version](SessionMessage::VERSION) of the protocol consists of three
11//! messages that are sent and received via the underlying transport:
12//! - [`Segment message`](Segment)
13//! - [`Retransmission request`](SegmentRequest)
14//! - [`Frame acknowledgement`](FrameAcknowledgements)
15//!
16//! All of these messages are bundled within the [`SessionMessage`] enum,
17//! which is then encoded as a byte array of a maximum
18//! MTU size `C` (which is a generic const argument of the `SessionMessage` type).
19//! The header of the `SessionMessage` encoding consists of the [`version`](SessionMessage::VERSION)
20//! byte, followed by the discriminator byte of one of the above messages and then followed by
21//! the message length and message's encoding itself.
22//!
23//! ## Segment message ([`Segment`](SessionMessage::Segment))
24//!
25//! The Segment message contains the payload [`Segment`] of some [`Frame`].
26//! The size of this message can range from [`the minimum message size`](SessionMessage::minimum_message_size)
27//! up to `C`.
28//!
29//! ## Retransmission request message ([`Request`](SessionMessage::Request))
30//!
31//! Contains a request for retransmission of missing segments in a frame. This is sent from
32//! the segment recipient to the sender, once it realizes some of the received frames are incomplete
33//! (after a certain period of time).
34//!
35//! The encoding of this message consists of pairs of [frame ID](FrameId) and
36//! a single byte bitmap of requested segments in this frame.
37//! Each pair is therefore [`ENTRY_SIZE`](SegmentRequest::ENTRY_SIZE) bytes-long.
38//! There can be at most [`MAX_ENTRIES`](SegmentRequest::MAX_ENTRIES)
39//! in a single Retransmission request message, given `C` as the MTU size. If the message contains
40//! fewer entries, it is padded with zeros (0 is not a valid frame ID).
41//! If more frames have missing segments, multiple retransmission request messages need to be sent.
42//!
43//! ## Frame acknowledgement message ([`Acknowledge`](SessionMessage::Acknowledge))
44//!
45//! This message is sent from the segment recipient to the segment sender to acknowledge that
46//! all segments of certain frames have been completely and correctly received by the recipient.
47//!
48//! The message consists simply of a [frame ID](FrameId) list of the completely received
49//! frames. There can be at most [`MAX_ACK_FRAMES`](FrameAcknowledgements::MAX_ACK_FRAMES)
50//! per message. If more frames need to be acknowledged, more messages need to be sent.
51//! If the message contains fewer entries, it is padded with zeros (0 is not a valid frame ID).
52
53mod frames;
54mod messages;
55
56use asynchronous_codec::{Decoder, Encoder};
57use bytes::{BufMut, BytesMut};
58pub use frames::{Frame, FrameId, OrderedFrame, Segment, SegmentId, SeqIndicator, SeqNum};
59use futures::{Stream, StreamExt};
60pub use messages::{FrameAcknowledgements, MissingSegmentsBitmap, SegmentRequest};
61
62use crate::errors::SessionError;
63
64/// Contains all messages of the Session sub-protocol.
65///
66/// The maximum size of the Session sub-protocol message is given by `C`.
67#[derive(Debug, Clone, PartialEq, Eq, strum::EnumDiscriminants, strum::EnumTryAs)]
68#[strum_discriminants(derive(strum::FromRepr), repr(u8))]
69pub enum SessionMessage<const C: usize> {
70    /// Represents a message containing a segment.
71    Segment(Segment),
72    /// Represents a message containing a [request](SegmentRequest) for segments.
73    Request(SegmentRequest<C>),
74    /// Represents a message containing [frame acknowledgements](FrameAcknowledgements).
75    Acknowledge(FrameAcknowledgements<C>),
76}
77
78impl<const C: usize> std::fmt::Display for SessionMessage<C> {
79    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
80        match &self {
81            SessionMessage::Segment(s) => write!(f, "segment {}", s.id()),
82            SessionMessage::Request(r) => write!(f, "retransmission request of {:?}", r.0),
83            SessionMessage::Acknowledge(a) => write!(f, "acknowledgement of {:?}", a.0),
84        }
85    }
86}
87
88impl<const C: usize> SessionMessage<C> {
89    /// Header size of the session message.
90    /// This is currently the version byte, the size of [`SessionMessageDiscriminants`] representation
91    /// and two bytes for the message length.
92    pub const HEADER_SIZE: usize = 1 + size_of::<SessionMessageDiscriminants>() + size_of::<u16>();
93    /// Maximum size of the message in v1.
94    pub const MAX_MESSAGE_LENGTH: usize = C.saturating_sub(Self::HEADER_SIZE);
95    /// Size of the overhead that's added to the raw payload of each [`Segment`].
96    ///
97    /// This amounts to [`SessionMessage::HEADER_SIZE`] + [`Segment::HEADER_SIZE`].
98    pub const SEGMENT_OVERHEAD: usize = Self::HEADER_SIZE + Segment::HEADER_SIZE;
99    /// Current version of the protocol.
100    pub const VERSION: u8 = 1;
101
102    /// Returns the minimum size of a [`SessionMessage`].
103    pub fn minimum_message_size() -> usize {
104        // Make this a "const fn" once "min" is const fn too
105        Self::HEADER_SIZE
106            + Segment::HEADER_SIZE
107                .min(SegmentRequest::<C>::SIZE)
108                .min(FrameAcknowledgements::<C>::SIZE)
109    }
110
111    /// Convenience method to encode the session message.
112    pub fn into_encoded(self) -> Box<[u8]> {
113        Vec::from(self).into_boxed_slice()
114    }
115}
116
117impl<const C: usize> From<SessionMessage<C>> for Vec<u8> {
118    fn from(message: SessionMessage<C>) -> Self {
119        debug_assert!(
120            C > SessionMessage::<C>::HEADER_SIZE && SessionMessage::<C>::MAX_MESSAGE_LENGTH <= u16::MAX as usize
121        );
122
123        let mut result = BytesMut::new();
124        SessionCodec::<C>
125            .encode(message, &mut result)
126            .expect("encoding never fails");
127
128        result.to_vec()
129    }
130}
131
132impl<const C: usize> TryFrom<&[u8]> for SessionMessage<C> {
133    type Error = SessionError;
134
135    fn try_from(value: &[u8]) -> Result<Self, Self::Error> {
136        SessionCodec
137            .decode(&mut BytesMut::from(value))?
138            .ok_or(SessionError::IncorrectMessageLength)
139    }
140}
141
142#[derive(Clone, Copy, Default)]
143pub struct SessionCodec<const C: usize>;
144
145/// End the incoming session stream after reporting an untrusted header once.
146///
147/// There is no synchronization marker to safely locate the next message after a wrong version
148/// or an impossible length. These errors are terminal; errors in a message with a known boundary
149/// remain recoverable because the decoder has already consumed that message.
150pub(crate) fn stop_on_invalid_header<const C: usize>(
151    messages: impl Stream<Item = Result<SessionMessage<C>, SessionError>>,
152) -> impl Stream<Item = Result<SessionMessage<C>, SessionError>> {
153    let (stop, registration) = futures::future::AbortHandle::new_pair();
154    futures::stream::Abortable::new(
155        messages.inspect(move |message| {
156            if matches!(message, Err(error) if error.is_fatal_header()) {
157                stop.abort();
158            }
159        }),
160        registration,
161    )
162}
163
164impl<const C: usize> Encoder for SessionCodec<C> {
165    type Error = SessionError;
166    type Item<'a> = SessionMessage<C>;
167
168    fn encode(&mut self, item: Self::Item<'_>, dst: &mut BytesMut) -> Result<(), Self::Error> {
169        debug_assert!(
170            C > SessionMessage::<C>::HEADER_SIZE && SessionMessage::<C>::MAX_MESSAGE_LENGTH <= u16::MAX as usize
171        );
172
173        let disc = SessionMessageDiscriminants::from(&item) as u8;
174
175        let msg = match item {
176            SessionMessage::Segment(s) => Vec::from(s),
177            SessionMessage::Request(r) => Vec::from(r),
178            SessionMessage::Acknowledge(a) => Vec::from(a),
179        };
180
181        if msg.len() > SessionMessage::<C>::MAX_MESSAGE_LENGTH {
182            return Err(SessionError::IncorrectMessageLength);
183        }
184
185        let msg_len = msg.len() as u16;
186        dst.put_u8(SessionMessage::<C>::VERSION);
187        dst.put_u8(disc);
188        dst.put_u16(msg_len);
189        dst.extend_from_slice(&msg);
190
191        tracing::trace!(disc, msg_len, "encoded message");
192        Ok(())
193    }
194}
195
196impl<const C: usize> Decoder for SessionCodec<C> {
197    type Error = SessionError;
198    type Item = SessionMessage<C>;
199
200    /// Decodes one message from `src`.
201    ///
202    /// A malformed message with a trusted length is consumed so the next message can be read.
203    /// `WrongVersion` and an overlong header length are terminal errors: the buffer is left intact,
204    /// and the caller must stop decoding. Session readers enforce this with [`stop_on_invalid_header`].
205    fn decode(&mut self, src: &mut BytesMut) -> Result<Option<Self::Item>, Self::Error> {
206        debug_assert!(C > SessionMessage::<C>::HEADER_SIZE);
207
208        tracing::trace!(msg_len = src.len(), "decoding message");
209        if src.len() < SessionMessage::<C>::minimum_message_size() {
210            return Ok(None);
211        }
212
213        // Protocol version
214        if src[0] != SessionMessage::<C>::VERSION {
215            // The next boundary is unknown; the session reader must terminate.
216            return Err(SessionError::WrongVersion);
217        }
218
219        // Message discriminant
220        let disc = src[1];
221
222        // Message length
223        let payload_len = u16::from_be_bytes([src[2], src[3]]) as usize;
224
225        // Check the maximum message length for version 1
226        if payload_len > SessionMessage::<C>::MAX_MESSAGE_LENGTH {
227            // The next boundary is unknown; the session reader must terminate.
228            return Err(SessionError::IncorrectMessageLength);
229        }
230
231        // Check if there's enough data so that we can read the rest of the message
232        let message_len = SessionMessage::<C>::HEADER_SIZE + payload_len;
233        if src.len() < message_len {
234            return Ok(None);
235        }
236
237        // Take the whole message out of the buffer first, so a message that fails to parse
238        // below is skipped and the next one can still be read.
239        let message = src.split_to(message_len);
240        let payload = &message[SessionMessage::<C>::HEADER_SIZE..];
241
242        let res = match SessionMessageDiscriminants::from_repr(disc).ok_or(SessionError::UnknownMessageTag)? {
243            SessionMessageDiscriminants::Segment => SessionMessage::Segment(payload.try_into()?),
244            SessionMessageDiscriminants::Request => SessionMessage::Request(payload.try_into()?),
245            SessionMessageDiscriminants::Acknowledge => SessionMessage::Acknowledge(payload.try_into()?),
246        };
247
248        Ok(Some(res))
249    }
250}
251
252#[cfg(test)]
253mod tests {
254    use hex_literal::hex;
255    use hopr_protocol_app::prelude::ApplicationData;
256    use rand::{RngExt, rngs::ThreadRng};
257
258    use super::*;
259    use crate::{
260        protocol::{FrameId, SegmentId},
261        session_socket_mtu,
262        utils::segment,
263    };
264
265    #[test]
266    fn ensure_session_protocol_version_1_values() {
267        // All of these values are independent of C, so we can set C = 0
268        assert_eq!(1, SessionMessage::<{ ApplicationData::PAYLOAD_SIZE }>::VERSION);
269        assert_eq!(4, SessionMessage::<{ ApplicationData::PAYLOAD_SIZE }>::HEADER_SIZE);
270        assert_eq!(
271            10,
272            SessionMessage::<{ ApplicationData::PAYLOAD_SIZE }>::SEGMENT_OVERHEAD
273        );
274        assert!(
275            session_socket_mtu::<{ ApplicationData::PAYLOAD_SIZE }>()
276                + SessionMessage::<{ ApplicationData::PAYLOAD_SIZE }>::SEGMENT_OVERHEAD
277                - SessionMessage::<{ ApplicationData::PAYLOAD_SIZE }>::HEADER_SIZE
278                <= SessionMessage::<{ ApplicationData::PAYLOAD_SIZE }>::MAX_MESSAGE_LENGTH
279        );
280    }
281
282    #[test]
283    fn session_message_segment_should_serialize_and_deserialize() -> anyhow::Result<()> {
284        const SEG_SIZE: usize = 8;
285
286        let mut segments = segment(hex!("deadbeefcafebabe"), SEG_SIZE, 10)?;
287
288        const MTU: usize = SEG_SIZE + SessionMessage::<0>::SEGMENT_OVERHEAD;
289
290        let msg_1 = SessionMessage::<MTU>::Segment(segments.pop().unwrap());
291        let data = Vec::from(msg_1.clone());
292        let msg_2 = SessionMessage::try_from(&data[..])?;
293
294        assert_eq!(msg_1, msg_2);
295
296        Ok(())
297    }
298
299    #[test]
300    fn session_message_segment_request_should_serialize_and_deserialize() -> anyhow::Result<()> {
301        // The first 8 segments are missing in Frame 10
302        let msg_1 = SessionMessage::<466>::Request(SegmentRequest::from_iter([
303            (2 as FrameId, [0b11000001].into()),
304            (10 as FrameId, [0b01000100].into()),
305        ]));
306        let data = Vec::from(msg_1.clone());
307        let msg_2 = SessionMessage::try_from(&data[..])?;
308
309        assert_eq!(msg_1, msg_2);
310
311        match msg_1 {
312            SessionMessage::Request(r) => {
313                let missing_segments = r.into_iter().collect::<Vec<_>>();
314                let expected = vec![
315                    SegmentId(2, 0),
316                    SegmentId(2, 1),
317                    SegmentId(2, 7),
318                    SegmentId(10, 1),
319                    SegmentId(10, 5),
320                ];
321                assert_eq!(expected, missing_segments);
322            }
323            _ => panic!("invalid type"),
324        }
325
326        Ok(())
327    }
328
329    #[test]
330    fn session_message_ack_should_serialize_and_deserialize() -> anyhow::Result<()> {
331        let mut rng = ThreadRng::default();
332        let frame_ids: Vec<u32> = (0..FrameAcknowledgements::<466>::MAX_ACK_FRAMES)
333            .map(|_| rng.random())
334            .collect();
335
336        let msg_1 = SessionMessage::<466>::Acknowledge(frame_ids.try_into()?);
337        let data = Vec::from(msg_1.clone());
338        let msg_2 = SessionMessage::try_from(&data[..])?;
339
340        assert_eq!(msg_1, msg_2);
341
342        Ok(())
343    }
344
345    /// Encodes a valid acknowledgement message, used after a bad message in the tests below.
346    fn valid_ack<const C: usize>() -> (SessionMessage<C>, Vec<u8>) {
347        let msg = SessionMessage::<C>::Acknowledge(vec![1 as FrameId, 2].try_into().expect("ack fits"));
348        let data = Vec::from(msg.clone());
349        (msg, data)
350    }
351
352    #[test]
353    fn decode_should_skip_a_message_with_an_unknown_tag() -> anyhow::Result<()> {
354        const MTU: usize = 466;
355        let (valid, valid_data) = valid_ack::<MTU>();
356
357        // Correct version and length, but a tag that does not exist
358        let mut src = BytesMut::from(&[SessionMessage::<MTU>::VERSION, 0xff, 0, 2, 0xaa, 0xbb][..]);
359        src.extend_from_slice(&valid_data);
360
361        let mut codec = SessionCodec::<MTU>;
362        assert!(matches!(codec.decode(&mut src), Err(SessionError::UnknownMessageTag)));
363        assert_eq!(src.len(), valid_data.len(), "the bad message must be consumed");
364        assert_eq!(codec.decode(&mut src)?, Some(valid));
365        assert!(src.is_empty());
366
367        Ok(())
368    }
369
370    #[test]
371    fn decode_should_skip_a_message_that_cannot_be_parsed() -> anyhow::Result<()> {
372        const MTU: usize = 466;
373        let (valid, valid_data) = valid_ack::<MTU>();
374
375        // A valid tag and length, but a segment payload that is too short to be a segment
376        let disc = SessionMessageDiscriminants::Segment as u8;
377        let mut src = BytesMut::from(&[SessionMessage::<MTU>::VERSION, disc, 0, 1, 0xaa][..]);
378        src.extend_from_slice(&valid_data);
379
380        let mut codec = SessionCodec::<MTU>;
381        assert!(codec.decode(&mut src).is_err());
382        assert_eq!(src.len(), valid_data.len(), "the bad message must be consumed");
383        assert_eq!(codec.decode(&mut src)?, Some(valid));
384
385        Ok(())
386    }
387
388    #[test]
389    fn malformed_header_should_leave_buffered_messages_for_connection_teardown() {
390        const MTU: usize = 466;
391        let (_, valid_data) = valid_ack::<MTU>();
392
393        // Neither a wrong-version byte nor an impossible length gives a trustworthy boundary.
394        for prefix in [vec![0xee], vec![SessionMessage::<MTU>::VERSION, 0, 0xff, 0xff]] {
395            let mut src = BytesMut::from(prefix.as_slice());
396            src.extend_from_slice(&valid_data);
397            let original = src.clone();
398            let error = SessionCodec::<MTU>.decode(&mut src);
399            assert!(matches!(
400                error,
401                Err(SessionError::WrongVersion | SessionError::IncorrectMessageLength)
402            ));
403            assert_eq!(
404                src, original,
405                "fatal header errors must not silently discard buffered messages"
406            );
407        }
408    }
409
410    #[test]
411    fn framed_reader_should_move_on_after_a_bad_message() {
412        use futures::StreamExt;
413
414        const MTU: usize = 466;
415        let (valid, valid_data) = valid_ack::<MTU>();
416
417        let mut data = vec![SessionMessage::<MTU>::VERSION, 0xff, 0, 2, 0xaa, 0xbb];
418        data.extend_from_slice(&valid_data);
419
420        // Before the fix, the reader returned the same error forever; `take` keeps the test from hanging
421        let items = futures::executor::block_on(
422            stop_on_invalid_header(asynchronous_codec::FramedRead::new(
423                futures::io::Cursor::new(data),
424                SessionCodec::<MTU>,
425            ))
426            .take(10)
427            .collect::<Vec<_>>(),
428        );
429
430        assert_eq!(items.len(), 2, "expected one error, then the valid message");
431        assert!(matches!(items[0], Err(SessionError::UnknownMessageTag)));
432        assert_eq!(items[1].as_ref().ok(), Some(&valid));
433    }
434
435    #[test]
436    fn framed_reader_should_report_fatal_header_once_then_end() {
437        const MTU: usize = 466;
438        let (_, valid_data) = valid_ack::<MTU>();
439        for prefix in [vec![0xee], vec![SessionMessage::<MTU>::VERSION, 0, 0xff, 0xff]] {
440            let wrong_version = prefix[0] != SessionMessage::<MTU>::VERSION;
441            let mut data = prefix;
442            data.extend_from_slice(&valid_data);
443            let messages = stop_on_invalid_header(asynchronous_codec::FramedRead::new(
444                futures::io::Cursor::new(data),
445                SessionCodec::<MTU>,
446            ));
447            futures::executor::block_on(async {
448                let mut messages = Box::pin(messages);
449                let first = messages.next().await;
450                if wrong_version {
451                    assert!(matches!(first, Some(Err(SessionError::WrongVersion))));
452                } else {
453                    assert!(matches!(first, Some(Err(SessionError::IncorrectMessageLength))));
454                }
455                assert!(messages.next().await.is_none());
456                assert!(messages.next().await.is_none(), "fatal termination must be permanent");
457            });
458        }
459    }
460
461    #[test]
462    fn session_message_segment_request_should_yield_correct_bitset_values() {
463        let seg_req = SegmentRequest::<466>::from_iter([(10, MissingSegmentsBitmap::from([0b00101000]))]);
464
465        let mut iter = seg_req.into_iter();
466        assert_eq!(iter.next(), Some(SegmentId(10, 2)));
467        assert_eq!(iter.next(), Some(SegmentId(10, 4)));
468        assert_eq!(iter.next(), None);
469    }
470}