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}