mqtt_endpoint_tokio/
lib.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
23//! # MQTT Endpoint Tokio
24//!
25//! A high-performance async MQTT client/server library for Rust with tokio, supporting
26//! MQTT v5.0 and v3.1.1 with TCP, TLS, WebSocket, and QUIC transports.
27//!
28//! This library provides a Sans-I/O MQTT protocol implementation built on top of
29//! `mqtt-protocol-core`, with async I/O operations handled by tokio.
30//!
31//! ## Features
32//!
33//! - **MQTT Protocol Support**: Both MQTT v3.1.1 and v5.0
34//! - **Multiple Transports**: TCP, TLS, WebSocket, and QUIC
35//! - **Generic Packet ID Types**: Support for u16 and u32 packet IDs for broker clustering
36//! - **Client and Server Roles**: Both client and server endpoint implementations
37//! - **Async/Await**: Built on tokio for high-performance async I/O
38//! - **Type Safety**: Comprehensive type system for MQTT packet handling
39//!
40//! ## Quick Start
41//!
42//! ```ignore
43//! use mqtt_endpoint_tokio::mqtt_ep;
44//!
45//! // Create a client endpoint
46//! let endpoint = mqtt_ep::endpoint::Endpoint::new(mqtt_ep::Version::V5_0);
47//!
48//! // Connect to TCP transport
49//! let transport = mqtt_ep::transport::tcp::TcpTransport::new("localhost:1883").await?;
50//! endpoint.attach(transport).await?;
51//!
52//! // Send CONNECT packet
53//! let connect = mqtt_ep::packet::Connect::builder()
54//!     .client_id("my-client")
55//!     .build()?;
56//! endpoint.send(connect.into()).await?;
57//!
58//! // Receive CONNACK
59//! let packet = endpoint.recv().await?;
60//! println!("Received: {packet:?}");
61//! ```
62//!
63//! ## Main Components
64//!
65//! - [`mqtt_ep::endpoint`]: Core endpoint functionality for both client and server
66//! - [`mqtt_ep::transport`]: Transport layer implementations (TCP, TLS, WebSocket, QUIC)
67//! - [`mqtt_ep::connection_option`]: Configuration options for connection behavior
68//! - [`mqtt_ep::packet`]: MQTT packet types and builders
69//! - [`mqtt_ep::packet_filter`]: Packet filtering for selective message reception
70//! - [`mqtt_ep::connection_error`]: Error handling for connection operations
71//!
72//! ## Generic Packet ID Support
73//!
74//! The library supports generic packet ID types (u16, u32) for broker clustering scenarios:
75//!
76//! ```ignore
77//! // Standard u16 packet IDs
78//! type Endpoint = mqtt_ep::endpoint::GenericEndpoint<mqtt_ep::role::Client, u16>;
79//!
80//! // Extended u32 packet IDs for broker clustering
81//! type ExtendedEndpoint = mqtt_ep::endpoint::GenericEndpoint<mqtt_ep::role::Client, u32>;
82//! ```
83
84pub mod mqtt_ep;
mqtt_endpoint_tokio/lib.rs

mqtt_endpoint_tokio/
lib.rs
