mqtt_protocol_core/
lib.rs

1//! # MQTT Protocol Core
2//!
3//! A Sans-I/O style MQTT protocol library for Rust that supports both MQTT v5.0 and v3.1.1.
4//!
5//! This library provides a pure protocol implementation without any I/O operations,
6//! making it suitable for use with any async runtime or synchronous I/O framework.
7//! All operations are synchronous and the library focuses solely on MQTT protocol
8//! message parsing, validation, and generation.
9//!
10//! ## Features
11//!
12//! - **Sans-I/O Design**: Pure protocol implementation with no I/O dependencies
13//! - **Dual Version Support**: Full support for both MQTT v3.1.1 and v5.0
14//! - **Generic Packet ID**: Supports custom packet ID types (u16, u32) for broker clustering
15//! - **Zero-Copy Payload**: Efficient payload handling with `ArcPayload`
16//! - **Comprehensive**: All MQTT packet types and features supported
17//! - **Type Safety**: Compile-time role and version checking
18//!
19//! ## Quick Start
20//!
21//! ### Basic Client Connection
22//!
23//! ```rust,no_run
24//! use mqtt_protocol_core::mqtt::{
25//!     Connection, Version,
26//!     connection::role::Client,
27//!     packet::v5_0::Connect,
28//! };
29//!
30//! // Create a client connection for MQTT v5.0
31//! let mut client = Connection::<Client>::new(Version::V5_0);
32//!
33//! // Create a CONNECT packet
34//! let connect = Connect::builder()
35//!     .client_id("my-client")
36//!     .unwrap()
37//!     .clean_start(true)
38//!     .build()
39//!     .unwrap();
40//!
41//! // Send the packet through the connection
42//! let events = client.send(connect.into());
43//! ```
44//!
45//! ### Server with Version Auto-Detection
46//!
47//! ```rust,no_run
48//! use mqtt_protocol_core::mqtt::{
49//!     Connection, Version,
50//!     connection::role::Server,
51//! };
52//!
53//! // Create a server that accepts any MQTT version
54//! let mut server = Connection::<Server>::new(Version::Undetermined);
55//!
56//! // The server will automatically adapt to the client's protocol version
57//! // when it receives a CONNECT packet
58//! ```
59//!
60//! ## Architecture
61//!
62//! The library is organized into several key modules:
63//!
64//! - [`mqtt::connection`] - Connection state management and packet processing
65//! - [`mqtt::packet`] - MQTT packet definitions for v3.1.1 and v5.0
66//! - [`mqtt::Version`] - Protocol version handling
67//! - [`mqtt::ArcPayload`] - Efficient payload management
68//!
69//! ## Sans-I/O Pattern
70//!
71//! This library follows the Sans-I/O pattern, meaning it handles protocol logic
72//! without performing any I/O operations. Instead, it returns events that tell
73//! your application what actions to take:
74//!
75//! ```rust,no_run
76//! use mqtt_protocol_core::mqtt::{
77//!     Connection, Version,
78//!     connection::{role::Client, event::GenericEvent},
79//! };
80//! use std::io::Cursor;
81//!
82//! let mut client = Connection::<Client>::new(Version::V5_0);
83//! let data = &[0u8; 0][..];
84//! let mut data_cursor = Cursor::new(data);
85//! let events = client.recv(&mut data_cursor);
86//!
87//! for event in events {
88//!     match event {
89//!         GenericEvent::RequestSendPacket { packet, .. } => {
90//!             // Send packet over network
91//!         }
92//!         GenericEvent::NotifyPacketReceived(packet) => {
93//!             // Handle received packet
94//!         }
95//!         // ... other events
96//!         _ => {}
97//!     }
98//! }
99//! ```
100//!
101//! ## Generic Packet ID Support
102//!
103//! The library supports custom packet ID types for advanced use cases like
104//! broker clustering, where u32 packet IDs can prevent ID exhaustion:
105//!
106//! ```rust,no_run
107//! use mqtt_protocol_core::mqtt::{GenericConnection, connection::role::Server};
108//!
109//! // Use u32 packet IDs instead of standard u16
110//! let mut server = GenericConnection::<Server, u32>::new(
111//!     mqtt_protocol_core::mqtt::Version::V5_0
112//! );
113//! ```
114
115/**
116 * MIT License
117 *
118 * Copyright (c) 2025 Takatoshi Kondo
119 *
120 * Permission is hereby granted, free of charge, to any person obtaining a copy
121 * of this software and associated documentation files (the "Software"), to deal
122 * in the Software without restriction, including without limitation the rights
123 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
124 * copies of the Software, and to permit persons to whom the Software is
125 * furnished to do so, subject to the following conditions:
126 *
127 * The above copyright notice and this permission notice shall be included in all
128 * copies or substantial portions of the Software.
129 *
130 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
131 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
132 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
133 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
134 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
135 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
136 * SOFTWARE.
137 */
138pub mod logger;
139pub mod mqtt;
mqtt_protocol_core/lib.rs

mqtt_protocol_core/
lib.rs
