mqtt_protocol_core/mqtt/packet/
qos.rs

1// MIT License
2//
3// Copyright (c) 2025 Takatoshi Kondo
4//
5// Permission is hereby granted, free of charge, to any person obtaining a copy
6// of this software and associated documentation files (the "Software"), to deal
7// in the Software without restriction, including without limitation the rights
8// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9// copies of the Software, and to permit persons to whom the Software is
10// furnished to do so, subject to the following conditions:
11//
12// The above copyright notice and this permission notice shall be included in all
13// copies or substantial portions of the Software.
14//
15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21// SOFTWARE.
22
23use core::fmt;
24use num_enum::TryFromPrimitive;
25use serde::{Deserialize, Serialize};
26
27/// MQTT Quality of Service levels
28///
29/// Defines the delivery guarantee levels for MQTT message publishing and subscription.
30/// Each QoS level provides different guarantees about message delivery, with higher
31/// levels providing stronger guarantees at the cost of increased overhead.
32///
33/// The QoS level is specified in PUBLISH packets and affects how the message is
34/// handled by both the sender and receiver according to the MQTT protocol specification.
35///
36/// # QoS Level Descriptions
37///
38/// - **QoS 0 (At Most Once)**: Fire-and-forget delivery. Messages are delivered
39///   at most once, or not at all. No acknowledgment is required.
40/// - **QoS 1 (At Least Once)**: Acknowledged delivery. Messages are delivered
41///   at least once. Duplicates may occur but will be handled by the receiver.
42/// - **QoS 2 (Exactly Once)**: Assured delivery. Messages are delivered exactly
43///   once using a four-part handshake protocol.
44///
45/// # Protocol Behavior
46///
47/// Each QoS level has specific protocol requirements:
48///
49/// - **QoS 0**: PUBLISH packet is sent without expecting acknowledgment
50/// - **QoS 1**: PUBLISH packet must be acknowledged with PUBACK
51/// - **QoS 2**: PUBLISH packet initiates a handshake: PUBLISH -> PUBREC -> PUBREL -> PUBCOMP
52///
53/// # Examples
54///
55/// ```ignore
56/// use mqtt_protocol_core::mqtt;
57///
58/// // Fire-and-forget message delivery
59/// let qos0 = mqtt::packet::Qos::AtMostOnce;
60///
61/// // Acknowledged delivery with possible duplicates
62/// let qos1 = mqtt::packet::Qos::AtLeastOnce;
63///
64/// // Exactly-once delivery with handshake
65/// let qos2 = mqtt::packet::Qos::ExactlyOnce;
66///
67/// // Convert from byte value
68/// let qos_from_byte = mqtt::packet::Qos::try_from(1u8).unwrap();
69/// assert_eq!(qos_from_byte, mqtt::packet::Qos::AtLeastOnce);
70/// ```
71#[derive(
72    Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, TryFromPrimitive,
73)]
74#[repr(u8)]
75pub enum Qos {
76    /// QoS level 0: At most once delivery
77    ///
78    /// Messages are delivered at most once, or not at all. There is no
79    /// acknowledgment of delivery and no retry mechanism. This is the
80    /// fastest delivery method but provides no guarantee that the message
81    /// will be received.
82    ///
83    /// This level is suitable for:
84    /// - High-frequency sensor data where missing occasional readings is acceptable
85    /// - Applications where message loss is tolerable
86    /// - Scenarios where network bandwidth and battery life are critical
87    AtMostOnce = 0,
88
89    /// QoS level 1: At least once delivery
90    ///
91    /// Messages are delivered at least once. The receiver acknowledges
92    /// delivery with a PUBACK packet. If the sender doesn't receive the
93    /// acknowledgment within a reasonable time, it retransmits the message.
94    /// Duplicate messages may occur and should be handled by the application.
95    ///
96    /// This level is suitable for:
97    /// - Applications that can handle duplicate messages
98    /// - Scenarios where message delivery is important but duplicates are acceptable
99    /// - Most general-purpose messaging use cases
100    AtLeastOnce = 1,
101
102    /// QoS level 2: Exactly once delivery
103    ///
104    /// Messages are delivered exactly once using a four-part handshake
105    /// protocol (PUBLISH -> PUBREC -> PUBREL -> PUBCOMP). This guarantees
106    /// that messages are neither lost nor duplicated, but requires the
107    /// most network traffic and processing overhead.
108    ///
109    /// This level is suitable for:
110    /// - Financial transactions or billing information
111    /// - Critical control messages
112    /// - Applications where duplicate processing would cause serious problems
113    ExactlyOnce = 2,
114}
115
116/// Implementation of `Display` for `Qos`
117///
118/// Formats the QoS level as a human-readable string representation.
119/// This allows QoS values to be used with `println!`, `format!`, and
120/// other string formatting operations.
121///
122/// # Output Format
123///
124/// * `Qos::AtMostOnce` -> "AtMostOnce"
125/// * `Qos::AtLeastOnce` -> "AtLeastOnce"
126/// * `Qos::ExactlyOnce` -> "ExactlyOnce"
127impl fmt::Display for Qos {
128    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
129        let s = match self {
130            Self::AtMostOnce => "AtMostOnce",
131            Self::AtLeastOnce => "AtLeastOnce",
132            Self::ExactlyOnce => "ExactlyOnce",
133        };
134        write!(f, "{s}")
135    }
136}
mqtt_protocol_core/mqtt/packet/qos.rs

mqtt_protocol_core/mqtt/packet/
qos.rs
