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

RocketMQ-Rust

English | 简体中文

🚀 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 reimplements Apache RocketMQ in Rust: the NameServer, Broker, Controller and Proxy services, an async client SDK, and the tooling to operate them. It keeps RocketMQ's model of topics, queues, consumer groups and NameServer routing, speaks the RocketMQ remoting protocol, and serves the gRPC MessagingService through its Proxy, while relying on Rust's ownership model for memory safety and on Tokio for asynchronous I/O.

Status: 1.0.0 is the current stable release. All 28 workspace crates are published on crates.io, and 13 container images are published on Docker Hub and GHCR. RocketMQ-Rust is an independent community distribution, not an official Apache Software Foundation release.

🎯 Why RocketMQ-Rust?

• 🦀 Memory Safety: Rust's ownership model removes whole classes of bugs such as use-after-free and data races at compile time, with no garbage-collection pauses
• ⚡ Async by Design: Services and clients run on Tokio with explicit runtime ownership, bounded queues and admission control, and graceful shutdown that reports what it stopped
• 🔁 RocketMQ Compatible: Implements the remoting wire protocol and the gRPC MessagingService, and converts existing Java Broker .properties files; Apache RocketMQ 5.5.0 is the comparison baseline
• 💾 Pluggable Storage: Local CommitLog and ConsumeQueue files by default, with optional RocksDB and tiered storage backends
• 🔒 Secure and Observable: ACL authentication and authorization, TLS transport, and OpenTelemetry metrics, traces and logs with OTLP and Prometheus exporters
• 🛠️ Operations Included: Admin CLI and terminal UI, web and desktop dashboards, container images, Helm charts and Kubernetes manifests
• 🤖 AI-Ready Operations: A read-only MCP server for diagnostics, a separately controlled MCP server for supervised changes, and an AI SRE platform
• 🌐 Cross-Platform: Built and tested in CI on Linux, Windows and macOS

🏗️ Architecture

RocketMQ-Rust is built from the components below. A minimal cluster needs only a NameServer, a Broker and a client; the rest is optional.

• NameServer: Broker registration, liveness tracking and topic route lookup
• Broker: Request processing, topic and consumer-group metadata, message storage and delivery
• Store: The storage engine inside the Broker, with CommitLog, ConsumeQueue and index files plus optional RocksDB and tiered backends
• Client SDK: Producers and push, lite pull and POP consumers for Rust applications
• Proxy: gRPC and optional remoting ingress, in front of a cluster or with an embedded Broker
• Controller: OpenRaft-based master election and replica coordination for controller-mode high availability
• Operations tooling: Admin CLI and TUI, dashboards and MCP servers, all off the message path

The architecture overview covers the message lifecycle, storage and high-availability design.

📚 Documentation

• 📖 Official Documentation: rocketmqrust.com - Getting started, architecture, configuration, deployment and operations guides, in English and Chinese
• 📝 API Docs: docs.rs/rocketmq-client-rust - API reference for the client SDK
• 📋 Examples: rocketmq-example and rocketmq-client/examples - Ready-to-run producer and consumer samples
• 🧭 Design Documents: rocketmq-doc - Architecture decision records, protocol notes and migration guides
• 📦 Releases: GitHub Releases and CHANGELOG.md - Release notes and change history
• 🤖 AI-Powered Docs: DeepWiki - Interactive documentation with intelligent search

🚀 Quick Start

Run a single-node cluster from source and exchange messages. Every listener binds to 127.0.0.1, and the Broker keeps its data in the git-ignored .rocketmq/ directory.

Prerequisites

• Git and a Rust toolchain installed through rustup; the repository pins Rust 1.95.0 in rust-toolchain.toml
• A C/C++ build toolchain for native dependencies: MSVC Build Tools on Windows, Xcode Command Line Tools on macOS, or GCC/Clang on Linux
• Free TCP ports 9876, 10909, 10911 and 10912, and about 1.5 GB of disk space for the Broker's preallocated store files

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

Run every command below from the repository root, with each service in its own terminal. The first build takes several minutes.

1. Start the NameServer

cargo run -p rocketmq-namesrv --bin rocketmq-namesrv-rust -- --rocketmqHome .rocketmq --bindAddress 127.0.0.1

The NameServer listens on 127.0.0.1:9876. It needs a home directory: pass --rocketmqHome or set ROCKETMQ_HOME, otherwise it exits during startup.

2. Start the Broker

Create the .rocketmq directory and save this configuration as .rocketmq/broker.toml:

[broker]
namesrvAddr = "127.0.0.1:9876"
brokerIp1 = "127.0.0.1"
storePathRootDir = "./.rocketmq/broker"

[broker.brokerServerConfig]
bindAddress = "127.0.0.1"

[store]
storePathRootDir = "./.rocketmq/store"
haListenAddress = "127.0.0.1"

cargo run -p rocketmq-broker --bin rocketmq-broker-rust -- -c .rocketmq/broker.toml

Wait for the started successfully log line. The Broker registers with the NameServer and listens on 127.0.0.1:10911. Without a configuration file it binds to all interfaces, advertises an auto-detected address and stores its data under ~/store.

3. Send and Receive Messages

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

The producer sends ten messages to TopicTest, which the Broker creates on first use, and exits. Then start the consumer:

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

The consumer prints the ten messages and keeps waiting for more. Press Ctrl+C to stop it.