[![CodeCov][codecov-image]][codecov-url]

RocketMQ-Rust

🚀 A high-performance, reliable, and feature-rich unofficial Rust implementation of Apache RocketMQ, designed to bring enterprise-grade message middleware to the Rust ecosystem.

✨ Overview

RocketMQ-Rust is a complete reimplementation of Apache RocketMQ in Rust, leveraging Rust's unique advantages in memory safety, zero-cost abstractions, and fearless concurrency. This project aims to provide Rust developers with a production-ready distributed message queue system that delivers exceptional performance while maintaining full compatibility with the RocketMQ protocol.

🎯 Why RocketMQ-Rust?

• 🦀 Memory Safety: Built on Rust's ownership model, eliminating entire classes of bugs like null pointer dereferences, buffer overflows, and data races at compile time
• ⚡ High Performance: Zero-cost abstractions and efficient async runtime deliver exceptional throughput with minimal resource overhead
• 🔒 Thread Safety: Fearless concurrency enables safe parallel processing without the risk of race conditions
• 🌐 Cross-Platform: First-class support for Linux, Windows, and macOS with native performance on each platform
• 🔌 Ecosystem Integration: Seamlessly integrates with the rich Rust ecosystem including Tokio, Serde, and other modern libraries
• 📦 Production Ready: Battle-tested architecture with comprehensive error handling and observability

🏗️ Architecture

RocketMQ-Rust implements a distributed architecture with the following core components:

• Name Server: Lightweight service discovery and routing coordination
• Broker: Message storage and delivery engine with support for topics, queues, and consumer groups
• Producer Client: High-performance message publishing with various sending modes
• Consumer Client: Flexible message consumption with push and pull models
• Store: Efficient local storage engine optimized for sequential writes
• Controller: Advanced high availability and failover capabilities

📚 Documentation

• 📖 Official Documentation: rocketmqrust.com - Comprehensive guides, API references, and best practices
• 🤖 AI-Powered Docs: DeepWiki - Interactive documentation with intelligent search
• 📝 API Docs: docs.rs/rocketmq-rust - Complete API documentation
• 📋 Examples: rocketmq-client/examples - Ready-to-run code samples

🚀 Quick Start

Prerequisites

• Rust toolchain 1.95.0
• A shell with cargo available
• Separate terminals for the NameServer, Broker, and client examples

See the toolchain and dependency trust policy for the pinned toolchain, dependency admission rules, and local validation contract.

1. Build the Workspace

git clone https://github.com/mxsm/rocketmq-rust.git
cd rocketmq-rust
cargo build --workspace

If you only want to use the client SDK from your own application, add the current release to Cargo.toml:

[dependencies]
rocketmq-client-rust = "1.0.0"
rocketmq-model = "1.0.0"
rocketmq-protocol = "1.0.0"

2. Start the NameServer

cargo run --bin rocketmq-namesrv-rust

The default NameServer endpoint is 127.0.0.1:9876. To bind explicitly:

cargo run --bin rocketmq-namesrv-rust -- --ip 127.0.0.1 --port 9876

3. Start the Broker

The Broker requires ROCKETMQ_HOME. Point it at an existing RocketMQ home or create a local runtime directory for quick testing.

Linux/macOS:

export ROCKETMQ_HOME="$(pwd)/.rocketmq"
mkdir -p "$ROCKETMQ_HOME/conf"
cargo run --bin rocketmq-broker-rust -- -n 127.0.0.1:9876

Windows PowerShell:

$env:ROCKETMQ_HOME = "$PWD\.rocketmq"
New-Item -ItemType Directory -Force "$env:ROCKETMQ_HOME\conf" | Out-Null
cargo run --bin rocketmq-broker-rust -- -n 127.0.0.1:9876

Use cargo run --bin rocketmq-broker-rust -- --help to inspect configuration flags such as --configFile, --namesrvAddr, and config printing options.

4. Send and Receive Messages

Start the consumer example first:

cargo run -p rocketmq-client-rust --example consumer

Then send messages from another terminal:

cargo run -p rocketmq-client-rust --example producer

The quickstart examples use 127.0.0.1:9876 and TopicTest by default. For more messaging patterns, see:

• Send single messages
• Send batch messages
• RPC messaging
• All examples

📦 Components & Crates

RocketMQ-Rust is organized into deployable services, reusable protocol/runtime crates, and operational applications. The tables below focus on responsibility and integration boundaries instead of per-crate maturity labels.

Core Runtime Services

Client, Protocol, and Shared Libraries