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::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//!     .clean_start(true)
37//!     .build()
38//!     .unwrap();
39//!
40//! // Send the packet through the connection
41//! let events = client.send(connect.into());
42//! ```
43//!
44//! ### Server with Version Auto-Detection
45//!
46//! ```rust,no_run
47//! use mqtt_protocol_core::mqtt::{
48//!     Connection, version::Version,
49//!     connection::role::Server,
50//! };
51//!
52//! // Create a server that accepts any MQTT version
53//! let mut server = Connection::<Server>::new(Version::Undetermined);
54//!
55//! // The server will automatically adapt to the client's protocol version
56//! // when it receives a CONNECT packet
57//! ```
58//!
59//! ## Architecture
60//!
61//! The library is organized into several key modules:
62//!
63//! - [`mqtt::connection`] - Connection state management and packet processing
64//! - [`mqtt::packet`] - MQTT packet definitions for v3.1.1 and v5.0
65//! - [`mqtt::version`] - Protocol version handling
66//! - [`mqtt::arc_payload`] - Efficient payload management
67//!
68//! ## Sans-I/O Pattern
69//!
70//! This library follows the Sans-I/O pattern, meaning it handles protocol logic
71//! without performing any I/O operations. Instead, it returns events that tell
72//! your application what actions to take:
73//!
74//! ```rust,no_run
75//! use mqtt_protocol_core::mqtt::{
76//!     Connection, version::Version,
77//!     connection::{role::Client, event::GenericEvent},
78//! };
79//!
80//! let mut client = Connection::<Client>::new(Version::V5_0);
81//! let events = client.recv(&mut data_cursor);
82//!
83//! for event in events {
84//!     match event {
85//!         GenericEvent::PacketToSend(packet) => {
86//!             // Send packet over network
87//!         }
88//!         GenericEvent::PacketReceived(packet) => {
89//!             // Handle received packet
90//!         }
91//!         // ... other events
92//!         _ => {}
93//!     }
94//! }
95//! ```
96//!
97//! ## Generic Packet ID Support
98//!
99//! The library supports custom packet ID types for advanced use cases like
100//! broker clustering, where u32 packet IDs can prevent ID exhaustion:
101//!
102//! ```rust,no_run
103//! use mqtt_protocol_core::mqtt::{GenericConnection, connection::role::Server};
104//!
105//! // Use u32 packet IDs instead of standard u16
106//! let mut server = GenericConnection::<Server, u32>::new(
107//!     mqtt_protocol_core::mqtt::version::Version::V5_0
108//! );
109//! ```
110
111/**
112 * MIT License
113 *
114 * Copyright (c) 2025 Takatoshi Kondo
115 *
116 * Permission is hereby granted, free of charge, to any person obtaining a copy
117 * of this software and associated documentation files (the "Software"), to deal
118 * in the Software without restriction, including without limitation the rights
119 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
120 * copies of the Software, and to permit persons to whom the Software is
121 * furnished to do so, subject to the following conditions:
122 *
123 * The above copyright notice and this permission notice shall be included in all
124 * copies or substantial portions of the Software.
125 *
126 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
127 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
128 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
129 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
130 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
131 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
132 * SOFTWARE.
133 */
134
135pub mod logger;
136pub mod mqtt;
mqtt_protocol_core/lib.rs

mqtt_protocol_core/
lib.rs
