Crate mqtt_protocol_core

MQTT Protocol Core

A Sans-I/O style MQTT protocol library for Rust that supports both MQTT v5.0 and v3.1.1.

This library provides a pure protocol implementation without any I/O operations, making it suitable for use with any async runtime or synchronous I/O framework. All operations are synchronous and the library focuses solely on MQTT protocol message parsing, validation, and generation.

Features

• Sans-I/O Design: Pure protocol implementation with no I/O dependencies
• Dual Version Support: Full support for both MQTT v3.1.1 and v5.0
• Generic Packet ID: Supports custom packet ID types (u16, u32) for broker clustering
• Zero-Copy Payload: Efficient payload handling with ArcPayload
• Comprehensive: All MQTT packet types and features supported
• Type Safety: Compile-time role and version checking

Quick Start

Basic Client Connection

use mqtt_protocol_core::mqtt::{
    Connection, version::Version,
    connection::role::Client,
    packet::v5_0::Connect,
};

// Create a client connection for MQTT v5.0
let mut client = Connection::<Client>::new(Version::V5_0);

// Create a CONNECT packet
let connect = Connect::builder()
    .client_id("my-client")
    .clean_start(true)
    .build()
    .unwrap();

// Send the packet through the connection
let events = client.send(connect.into());

Server with Version Auto-Detection

use mqtt_protocol_core::mqtt::{
    Connection, version::Version,
    connection::role::Server,
};

// Create a server that accepts any MQTT version
let mut server = Connection::<Server>::new(Version::Undetermined);

// The server will automatically adapt to the client's protocol version
// when it receives a CONNECT packet

Architecture

The library is organized into several key modules:

• mqtt::connection - Connection state management and packet processing
• mqtt::packet - MQTT packet definitions for v3.1.1 and v5.0
• mqtt::version - Protocol version handling
• mqtt::arc_payload - Efficient payload management

Sans-I/O Pattern

This library follows the Sans-I/O pattern, meaning it handles protocol logic without performing any I/O operations. Instead, it returns events that tell your application what actions to take:

use mqtt_protocol_core::mqtt::{
    Connection, version::Version,
    connection::{role::Client, event::GenericEvent},
};

let mut client = Connection::<Client>::new(Version::V5_0);
let events = client.recv(&mut data_cursor);

for event in events {
    match event {
        GenericEvent::PacketToSend(packet) => {
            // Send packet over network
        }
        GenericEvent::PacketReceived(packet) => {
            // Handle received packet
        }
        // ... other events
        _ => {}
    }
}

Generic Packet ID Support

The library supports custom packet ID types for advanced use cases like broker clustering, where u32 packet IDs can prevent ID exhaustion:

use mqtt_protocol_core::mqtt::{GenericConnection, connection::role::Server};

// Use u32 packet IDs instead of standard u16
let mut server = GenericConnection::<Server, u32>::new(
    mqtt_protocol_core::mqtt::version::Version::V5_0
);

Modules

logger

MIT License

mqtt