Skip to main content

symqtt_codec/
lib.rs

1//! MQTT 3.1.1 / 5.0 packet codec
2//!
3//! Role-neutral encoder/decoder for client and server packets. No async runtime.
4//! Framing is in [`v3::Packet::decode`] / [`v5::Packet::decode`]: a partial packet
5//! returns `Ok(None)` and consumes nothing.
6//!
7//! # Modules
8//!
9//! - [`v3`] — MQTT 3.1.1 packets
10//! - [`v5`] — MQTT 5.0 packets, properties, reason codes
11//!
12//! # Example
13//!
14//! ```
15//! use bytes::BytesMut;
16//! use symqtt_codec::v3::{Packet, Subscribe, SubscribeFilter};
17//! use symqtt_codec::QoS;
18//!
19//! let mut wire = BytesMut::new();
20//! Packet::Subscribe(Subscribe {
21//!     pkid: 1,
22//!     filters: vec![SubscribeFilter { topic: "a/b".to_owned(), qos: QoS::AtLeastOnce }],
23//! })
24//! .encode(&mut wire)?;
25//!
26//! // Framing lives in decode: a partial packet yields Ok(None) and consumes nothing
27//! let packet = Packet::decode(&mut wire)?.expect("a whole packet");
28//! # Ok::<(), Box<dyn std::error::Error>>(())
29//! ```
30
31#![cfg_attr(docsrs, feature(doc_cfg))]
32
33pub(crate) mod error;
34pub(crate) mod fixed_header;
35pub(crate) mod primitives;
36pub(crate) mod varint;
37
38pub mod v3;
39pub mod v5;
40
41pub use error::{DecodeError, EncodeError};
42pub use fixed_header::PacketType;
43
44/// Largest remaining length the four-byte variable-length integer can express [MQTT-2.2.3]
45pub const MAX_REMAINING_LEN: usize = 268_435_455;
46
47/// MQTT Quality of Service level [MQTT-4.3]
48#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
49pub enum QoS {
50    /// QoS 0 — at most once delivery
51    AtMostOnce = 0,
52    /// QoS 1 — at least once delivery
53    AtLeastOnce = 1,
54    /// QoS 2 — exactly once delivery
55    ExactlyOnce = 2,
56}
57
58impl TryFrom<u8> for QoS {
59    type Error = DecodeError;
60
61    fn try_from(value: u8) -> Result<Self, Self::Error> {
62        match value {
63            0 => Ok(Self::AtMostOnce),
64            1 => Ok(Self::AtLeastOnce),
65            2 => Ok(Self::ExactlyOnce),
66            _ => Err(DecodeError::ProtocolError {
67                reason: "invalid QoS value",
68            }),
69        }
70    }
71}
72
73#[cfg(test)]
74mod tests {
75    use super::*;
76
77    #[test]
78    fn qos_from_0() {
79        assert_eq!(QoS::try_from(0u8), Ok(QoS::AtMostOnce));
80    }
81
82    #[test]
83    fn qos_from_1() {
84        assert_eq!(QoS::try_from(1u8), Ok(QoS::AtLeastOnce));
85    }
86
87    #[test]
88    fn qos_from_2() {
89        assert_eq!(QoS::try_from(2u8), Ok(QoS::ExactlyOnce));
90    }
91
92    #[test]
93    fn qos_from_3_invalid() {
94        assert_eq!(
95            QoS::try_from(3u8),
96            Err(DecodeError::ProtocolError {
97                reason: "invalid QoS value"
98            })
99        );
100    }
101
102    #[test]
103    fn qos_from_255_invalid() {
104        assert!(QoS::try_from(255u8).is_err());
105    }
106}