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 std::time::Duration;
78/// use mqute_codec::protocol::{v5::Connect, Credentials};
79///
80/// let connect = Connect::new(
81///     "client_id",
82///     Some(Credentials::login("user", "pass")),
83///     None,
84///     Duration::from_secs(30),  // keep alive
85///     true // clean session
86/// );
87/// ```
88///
89/// ### Example: Creating a PUBLISH Packet
90/// ```rust
91/// use mqute_codec::protocol::v4::{Publish};
92/// use mqute_codec::protocol::{Flags, QoS};
93/// use bytes::Bytes;
94///
95/// let flag = Flags::new(QoS::AtLeastOnce);
96///
97/// let publish = Publish::new(
98///     "topic",
99///     1234,
100///     Bytes::from("payload"),
101///     flag
102/// );
103/// ```
104pub mod protocol;
105
106/// ## Error Handling
107///
108/// Unified error type for all codec operations.
109///
110/// ### Example
111/// ```rust
112/// use mqute_codec::{Error, codec::PacketCodec};
113/// use tokio_util::codec::Decoder;
114/// use bytes::BytesMut;
115///
116/// let mut codec = PacketCodec::new(None, None);
117/// let mut buf = BytesMut::new();
118/// buf.extend_from_slice(b"\x0f\x04\x00\x00\x00\x00");
119///
120/// match codec.decode(&mut buf) {
121///     Err(Error::InvalidPacketType(_)) => println!("Got expected error"),
122///     _ => panic!("Should have failed"),
123/// }
124/// ```
125mod error;
126pub use error::Error;
mqute_codec/lib.rs

mqute_codec/
lib.rs
