<p align="center"> <img src="resources/RocketMQ-Rust.png" width="30%" height="auto"/> <img src="resources/logo.png" width="30%" height="auto"/> </p> <div align="center">

[![CodeCov][codecov-image]][codecov-url] <br/>

</div> <div align="center"> <a href="https://trendshift.io/repositories/12176" target="_blank"><img src="https://trendshift.io/api/badge/repositories/12176" alt="mxsm%2Frocketmq-rust | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a> <a href="https://trendshift.io/developers/3818" target="_blank"><img src="https://trendshift.io/api/badge/developers/3818" alt="mxsm | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a> </div>

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.

<div align="center">

<br/>

</div>

---

✨ 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

<p align="center"> <img src="resources/architecture-current-v4.png" alt="RocketMQ-Rust Architecture" width="100%"/> </p>

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

| Crate | Responsibility | |-------|----------------| | rocketmq-namesrv | NameServer implementation for broker registration, topic routing, and service discovery. | | rocketmq-broker | Broker implementation for message storage, dispatch, delivery, and consumer coordination. | | rocketmq-controller | Controller service for broker coordination and high availability workflows. | | rocketmq-proxy | Proxy layer for gateway-style client access and protocol integration. | | rocketmq-proxy-core | Stable proxy contracts, use cases, and ingress-independent models. | | rocketmq-proxy-cluster | Cluster-mode proxy adapter with keyed execution and remote Broker access. | | rocketmq-proxy-local | Local-mode proxy adapter. |

Client, Protocol, and Shared Libraries

| Crate | Responsibility | |-------|----------------| | rocketmq-client | Async producer, consumer, and admin SDK for application integration. | | rocketmq-protocol | RocketMQ wire commands, headers, serialization, and compatibility contracts. | | rocketmq-transport | Runtime-owned network sessions and canonical per-session writers. | | rocketmq-model | Shared message, route, configuration, and domain models. | | rocketmq-auth | Authentication, authorization, ACL evaluation, and request context support. | | rocketmq-security-api | Runtime-neutral authentication, authorization, signing, and maintenance contracts. | | rocketmq-filter | Message filtering support, including tag and expression-based filtering. |

Storage, Runtime, and Observability

| Crate | Responsibility | |-------|----------------| | rocketmq-store | Durable local storage engine for commit logs, consume queues, and message indexes. | | rocketmq-store-api | Backend-neutral append, read, lifecycle, replication, checkpoint, and health capabilities. | | rocketmq-store-local | Local CommitLog, ConsumeQueue, Index, mapped-file, and recovery implementation. | | rocketmq-store-rocksdb | RocksDB-backed store implementation. | | rocketmq-tieredstore | Tiered storage abstractions for extending message data beyond local disks. | | rocketmq-runtime | Async runtime abstractions and runtime-friendly coordination utilities. | | rocketmq-error | Shared error types and result conventions across workspace crates. | | rocketmq-macros | Procedural macros used by RocketMQ-Rust crates and examples. | | rocketmq-observability | Metrics and tracing integration for service and client instrumentation. |

The cross-cutting ownership, cancellation, error, limit, compatibility, and failure-mode contracts are documented in the core capability contracts.

Tools, Examples, and Dashboards

| Project | Responsibility | |---------|----------------| | rocketmq-example | Standalone examples covering producer, consumer, request/reply, ordering, delay, and transaction flows. | | rocketmq-tools | Command-line tools and operational utilities. | | rocketmq-admin-cli | Command-line administration interface for cluster and broker operations. | | rocketmq-admin-core | Shared admin functionality