hopr_protocol_session/protocol/
mod.rs1mod 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#[derive(Debug, Clone, PartialEq, Eq, strum::EnumDiscriminants, strum::EnumTryAs)]
68#[strum_discriminants(derive(strum::FromRepr), repr(u8))]
69pub enum SessionMessage<const C: usize> {
70 Segment(Segment),
72 Request(SegmentRequest<C>),
74 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 pub const HEADER_SIZE: usize = 1 + size_of::<SessionMessageDiscriminants>() + size_of::<u16>();
93 pub const MAX_MESSAGE_LENGTH: usize = C.saturating_sub(Self::HEADER_SIZE);
95 pub const SEGMENT_OVERHEAD: usize = Self::HEADER_SIZE + Segment::HEADER_SIZE;
99 pub const VERSION: u8 = 1;
101
102 pub fn minimum_message_size() -> usize {
104 Self::HEADER_SIZE
106 + Segment::HEADER_SIZE
107 .min(SegmentRequest::<C>::SIZE)
108 .min(FrameAcknowledgements::<C>::SIZE)
109 }
110
111 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
145pub(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 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 if src[0] != SessionMessage::<C>::VERSION {
215 return Err(SessionError::WrongVersion);
217 }
218
219 let disc = src[1];
221
222 let payload_len = u16::from_be_bytes([src[2], src[3]]) as usize;
224
225 if payload_len > SessionMessage::<C>::MAX_MESSAGE_LENGTH {
227 return Err(SessionError::IncorrectMessageLength);
229 }
230
231 let message_len = SessionMessage::<C>::HEADER_SIZE + payload_len;
233 if src.len() < message_len {
234 return Ok(None);
235 }
236
237 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 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 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 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 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 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 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 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}