mqute_codec/
lib.rs

1//! # MQTT Packet Codec
2//!
3//! This module provides packet construction and serialization/deserialization for MQTT protocol.
4//! It handles the binary representation of MQTT packets but does NOT include:
5//! - Network I/O operations
6//! - Protocol state management
7//! - Session handling
8//! - Quality of Service guarantees
9//!
10//! ## Responsibilities
11//! - Packet structure definitions for all MQTT versions (3.1, 3.1.1, 5.0)
12//! - Encoding packets to wire format
13//! - Decoding packets from wire format
14//! - Basic protocol validation
15//!
16//! ## Supported MQTT Versions
17//!
18//! | Version   | Specification | Status       | Notable Features |
19//! |-----------|---------------|--------------|------------------|
20//! | MQTT 3.1  | [MQTT 3.1]    | Full Support | Basic pub/sub, QoS 0-2 |
21//! | MQTT 3.1.1| [MQTT 3.1.1]  | Full Support | Clean session, Last Will |
22//! | MQTT 5.0  | [MQTT 5.0]    | Full Support | Properties, Enhanced Auth |
23//!
24//! [MQTT 3.1]: http://public.dhe.ibm.com/software/dw/webservices/ws-mqtt/mqtt-v3r1.html
25//! [MQTT 3.1.1]: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html
26//! [MQTT 5.0]: https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html
27//!
28//! ## Feature Highlights
29//!
30//! - **Multi-Version Support**: Single API for all MQTT versions
31//! - **Zero-Copy Parsing**: Maximizes performance by minimizing allocations
32//! - **Protocol Bridging**: Tools for interoperability between versions
33//! - **Validation**: Strict protocol compliance checking
34//! - **Async Ready**: Works seamlessly with async runtimes
35
36/// ## Codec Implementation
37///
38/// Contains the core encoding/decoding logic for MQTT packets.
39///
40/// ### Main Components
41/// - `PacketCodec`: The primary codec for encoding/decoding packets
42/// - `RawPacket`: Intermediate packet representation
43///
44/// ### Example
45///
46/// ```rust
47/// use mqute_codec::codec::{PacketCodec, RawPacket, Encode, Decode, Encoded};
48/// use tokio_util::codec::Decoder;
49/// use bytes::BytesMut;
50/// use mqute_codec::protocol::PacketType;
51///
52/// let mut codec = PacketCodec::new(Some(4096), Some(4096));
53/// let mut buf = BytesMut::new();
54/// buf.extend_from_slice(b"\x10\x29\x00\x04MQTT\x04\xd6\x00\x10\x00\x06client\x00\x04/abc\x00\x03bye\x00\x04user\x00\x04pass");
55///
56/// match codec.decode(&mut buf) {
57///     Ok(Some(packet)) => {
58///         assert_eq!(packet.header.packet_type(), PacketType::Connect);
59///     }
60///     _ => panic!("Decoding failed"),
61/// }
62/// ```
63pub mod codec;
64
65/// ## Protocol Implementation
66///
67/// Contains all MQTT packet definitions and protocol logic.
68///
69/// ### Organization
70/// - `v3`: MQTT v3.1 protocol implementation
71/// - `v4`: MQTT v3.1.1 protocol implementation
72/// - `v5`: MQTT v5.0 protocol implementation
73/// - `common`: Shared types between protocol versions
74///
75/// ### Example: Creating a CONNECT Packet
76/// ```rust
77/// use mqute_codec::protocol::{v5::Connect, Credentials};
78///
79/// let connect = Connect::new(
80///     "client_id",
81///     Some(Credentials::login("user", "pass")),
82///     None,
83///     30,  // keep alive
84///     true // clean session
85/// );
86/// ```
87///
88/// ### Example: Creating a PUBLISH Packet
89/// ```rust
90/// use mqute_codec::protocol::v4::{Publish};
91/// use mqute_codec::protocol::{Flags, QoS};
92/// use bytes::Bytes;
93///
94/// let flag = Flags::new(QoS::AtLeastOnce);
95///
96/// let publish = Publish::new(
97///     "topic",
98///     1234,
99///     Bytes::from("payload"),
100///     flag
101/// );
102/// ```
103pub mod protocol;
104
105/// ## Error Handling
106///
107/// Unified error type for all codec operations.
108///
109/// ### Example
110/// ```rust
111/// use mqute_codec::{Error, codec::PacketCodec};
112/// use tokio_util::codec::Decoder;
113/// use bytes::BytesMut;
114///
115/// let mut codec = PacketCodec::new(None, None);
116/// let mut buf = BytesMut::new();
117/// buf.extend_from_slice(b"\x0f\x04\x00\x00\x00\x00");
118///
119/// match codec.decode(&mut buf) {
120///     Err(Error::InvalidPacketType(_)) => println!("Got expected error"),
121///     _ => panic!("Should have failed"),
122/// }
123/// ```
124mod error;
125pub use error::Error;
mqute_codec/lib.rs

mqute_codec/
lib.rs
