Skip to content
Back to search

rocketmq-rust

๐Ÿš€ Apache RocketMQ built in Rust ๐Ÿฆ€ โ€” faster, safer, and more memory-efficient. Powering high-performance messaging for the AI era, with AI Agent, MCP, and AI-SRE capabilities.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mxsm/rocketmq-rust with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mxsm/rocketmq-rust'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mxsm--rocketmq-rust/badge.svg)](/listings/mxsm--rocketmq-rust)

HTML

<a href="/listings/mxsm--rocketmq-rust"><img src="/api/listings/mxsm--rocketmq-rust/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](rocketmq-doc/en/toolchain-and-dependency-policy.md) 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](https://github.com/mxsm/rocketmq-rust/blob/main/rocketmq-client/README.md#send-a-single-message) - [Send batch messages](https://github.com/mxsm/rocketmq-rust/blob/main/rocketmq-client/README.md#send-batch-messages) - [RPC messaging](https://github.com/mxsm/rocketmq-rust/blob/main/rocketmq-client/README.md#send-rpc-messages) - [All examples](https://github.com/mxsm/rocketmq-rust/tree/main/rocketmq-client/examples)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md ยท README ยท 458 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="resources/RocketMQ-Rust.png" width="30%" height="auto" alt="RocketMQ-Rust logo"/>
  3. <img src="resources/logo-animated-transparent.gif" width="60%" height="auto" alt="RocketMQ-Rust animated wordmark"/>
  4. </p>
  5. <div align="center">
  6. [![GitHub last commit](https://img.shields.io/github/last-commit/mxsm/rocketmq-rust)](https://github.com/mxsm/rocketmq-rust/commits/main)
  7. [![Crates.io](https://img.shields.io/crates/v/rocketmq-client-rust.svg)](https://crates.io/crates/rocketmq-client-rust)
  8. [![Docs.rs](https://docs.rs/rocketmq-client-rust/badge.svg)](https://docs.rs/rocketmq-client-rust)
  9. [![Docker](https://img.shields.io/docker/v/mxsm/rocketmq-rust-broker?label=docker)](https://hub.docker.com/u/mxsm)
  10. [![CI](https://github.com/mxsm/rocketmq-rust/actions/workflows/rocketmq-rust-ci.yaml/badge.svg?branch=main)](https://github.com/mxsm/rocketmq-rust/actions/workflows/rocketmq-rust-ci.yaml)
  11. [![Website Deploy](https://github.com/mxsm/rocketmq-rust/actions/workflows/deploy.yml/badge.svg)](https://github.com/mxsm/rocketmq-rust/actions/workflows/deploy.yml)
  12. [![Website Check](https://github.com/mxsm/rocketmq-rust/actions/workflows/website-check.yml/badge.svg)](https://github.com/mxsm/rocketmq-rust/actions/workflows/website-check.yml)
  13. [![CodeCov][codecov-image]][codecov-url] [![GitHub contributors](https://img.shields.io/github/contributors/mxsm/rocketmq-rust)](https://github.com/mxsm/rocketmq-rust/graphs/contributors) [![License](https://img.shields.io/crates/l/rocketmq-client-rust)](#-license)
  14. <br/>
  15. ![GitHub repo size](https://img.shields.io/github/repo-size/mxsm/rocketmq-rust)
  16. ![MSRV](https://img.shields.io/badge/MSRV-1.95.0%2B-25b373)
  17. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/mxsm/rocketmq-rust)
  18. </div>
  19. <div align="center">
  20. <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>
  21. <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>
  22. </div>
  23. # RocketMQ-Rust
  24. [English](README.md) | [็ฎ€ไฝ“ไธญๆ–‡](README-zh_cn.md)
  25. ๐Ÿš€ A high-performance, reliable, and feature-rich **unofficial Rust implementation** of [Apache RocketMQ](https://github.com/apache/rocketmq), designed to bring enterprise-grade message middleware to the Rust ecosystem.
  26. <div align="center">
  27. [![Overview](https://img.shields.io/badge/๐Ÿ“–_Overview-4A90E2?style=flat-square&labelColor=2C5F9E&color=4A90E2)](#-overview)
  28. [![Quick Start](https://img.shields.io/badge/๐Ÿš€_Quick_Start-50C878?style=flat-square&labelColor=2D7A4F&color=50C878)](#-quick-start)
  29. [![Documentation](https://img.shields.io/badge/๐Ÿ“š_Documentation-FF8C42?style=flat-square&labelColor=CC6A2F&color=FF8C42)](#-documentation)
  30. [![Components](https://img.shields.io/badge/๐Ÿ“ฆ_Components-9B59B6?style=flat-square&labelColor=6C3483&color=9B59B6)](#-components--crates)
  31. <br/>
  32. [![Deployment](https://img.shields.io/badge/๐Ÿšข_Deployment-1ABC9C?style=flat-square&labelColor=117A65&color=1ABC9C)](#-deployment)
  33. [![Contributing](https://img.shields.io/badge/๐Ÿค_Contributing-F39C12?style=flat-square&labelColor=B9770E&color=F39C12)](#-contributing)
  34. [![FAQ](https://img.shields.io/badge/โ“_FAQ-E74C3C?style=flat-square&labelColor=A93226&color=E74C3C)](#-faq)
  35. [![Community](https://img.shields.io/badge/๐Ÿ‘ฅ_Community-8E44AD?style=flat-square&labelColor=633974&color=8E44AD)](#-community--support)
  36. </div>
  37. ---
  38. ## โœจ Overview
  39. **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.
  40. > **Status:** `1.0.0` is the current stable release. All 28 workspace crates are published on [crates.io](https://crates.io/crates/rocketmq-client-rust), and 13 container images are published on [Docker Hub](https://hub.docker.com/u/mxsm) and [GHCR](https://github.com/mxsm?tab=packages&repo_name=rocketmq-rust). RocketMQ-Rust is an independent community distribution, not an official Apache Software Foundation release.
  41. ### ๐ŸŽฏ Why RocketMQ-Rust?
  42. - **๐Ÿฆ€ 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
  43. - **โšก 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
  44. - **๐Ÿ” 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
  45. - **๐Ÿ’พ Pluggable Storage**: Local CommitLog and ConsumeQueue files by default, with optional RocksDB and tiered storage backends
  46. - **๐Ÿ”’ Secure and Observable**: ACL authentication and authorization, TLS transport, and OpenTelemetry metrics, traces and logs with OTLP and Prometheus exporters
  47. - **๐Ÿ› ๏ธ Operations Included**: Admin CLI and terminal UI, web and desktop dashboards, container images, Helm charts and Kubernetes manifests
  48. - **๐Ÿค– AI-Ready Operations**: A read-only MCP server for diagnostics, a separately controlled MCP server for supervised changes, and an AI SRE platform
  49. - **๐ŸŒ Cross-Platform**: Built and tested in CI on Linux, Windows and macOS
  50. ## ๐Ÿ—๏ธ Architecture
  51. <p align="center">
  52. <img src="resources/rocketmq-rust-architecture.svg" alt="RocketMQ-Rust Architecture" width="100%"/>
  53. </p>
  54. RocketMQ-Rust is built from the components below. A minimal cluster needs only a NameServer, a Broker and a client; the rest is optional.
  55. - **NameServer**: Broker registration, liveness tracking and topic route lookup
  56. - **Broker**: Request processing, topic and consumer-group metadata, message storage and delivery
  57. - **Store**: The storage engine inside the Broker, with CommitLog, ConsumeQueue and index files plus optional RocksDB and tiered backends
  58. - **Client SDK**: Producers and push, lite pull and POP consumers for Rust applications
  59. - **Proxy**: gRPC and optional remoting ingress, in front of a cluster or with an embedded Broker
  60. - **Controller**: OpenRaft-based master election and replica coordination for controller-mode high availability
  61. - **Operations tooling**: Admin CLI and TUI, dashboards and MCP servers, all off the message path
  62. The [architecture overview](https://rocketmqrust.com/docs/architecture/overview) covers the message lifecycle, storage and high-availability design.
  63. ## ๐Ÿ“š Documentation
  64. - **๐Ÿ“– Official Documentation**: [rocketmqrust.com](https://rocketmqrust.com) - Getting started, architecture, configuration, deployment and operations guides, in English and Chinese
  65. - **๐Ÿ“ API Docs**: [docs.rs/rocketmq-client-rust](https://docs.rs/rocketmq-client-rust) - API reference for the client SDK
  66. - **๐Ÿ“‹ Examples**: [rocketmq-example](./rocketmq-example) and [rocketmq-client/examples](./rocketmq-client/examples) - Ready-to-run producer and consumer samples
  67. - **๐Ÿงญ Design Documents**: [rocketmq-doc](./rocketmq-doc) - Architecture decision records, protocol notes and migration guides
  68. - **๐Ÿ“ฆ Releases**: [GitHub Releases](https://github.com/mxsm/rocketmq-rust/releases) and [CHANGELOG.md](CHANGELOG.md) - Release notes and change history
  69. - **๐Ÿค– AI-Powered Docs**: [DeepWiki](https://deepwiki.com/mxsm/rocketmq-rust) - Interactive documentation with intelligent search
  70. ## ๐Ÿš€ Quick Start
  71. 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.
  72. ### Prerequisites
  73. - Git and a Rust toolchain installed through [rustup](https://rustup.rs); the repository pins Rust 1.95.0 in `rust-toolchain.toml`
  74. - A C/C++ build toolchain for native dependencies: MSVC Build Tools on Windows, Xcode Command Line Tools on macOS, or GCC/Clang on Linux
  75. - Free TCP ports `9876`, `10909`, `10911` and `10912`, and about 1.5 GB of disk space for the Broker's preallocated store files
  76. ```bash
  77. git clone https://github.com/mxsm/rocketmq-rust.git
  78. cd rocketmq-rust
  79. ```
  80. Run every command below from the repository root, with each service in its own terminal. The first build takes several minutes.
  81. ### 1. Start the NameServer
  82. ```bash
  83. cargo run -p rocketmq-namesrv --bin rocketmq-namesrv-rust -- --rocketmqHome .rocketmq --bindAddress 127.0.0.1
  84. ```
  85. 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.
  86. ### 2. Start the Broker
  87. Create the `.rocketmq` directory and save this configuration as `.rocketmq/broker.toml`:
  88. ```toml
  89. [broker]
  90. namesrvAddr = "127.0.0.1:9876"
  91. brokerIp1 = "127.0.0.1"
  92. storePathRootDir = "./.rocketmq/broker"
  93. [broker.brokerServerConfig]
  94. bindAddress = "127.0.0.1"
  95. [store]
  96. storePathRootDir = "./.rocketmq/store"
  97. haListenAddress = "127.0.0.1"
  98. ```
  99. ```bash
  100. cargo run -p rocketmq-broker --bin rocketmq-broker-rust -- -c .rocketmq/broker.toml
  101. ```
  102. 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`.
  103. ### 3. Send and Receive Messages
  104. ```bash
  105. cargo run -p rocketmq-client-rust --example simple-producer
  106. ```
  107. The producer sends ten messages to `TopicTest`, which the Broker creates on first use, and exits. Then start the consumer:
  108. ```bash
  109. cargo run -p rocketmq-client-rust --example consumer
  110. ```
  111. The consumer prints the ten messages and keeps waiting for more. Press `Ctrl+C` to stop it.
  112. ### 4. Stop and Clean Up
  113. Press `Ctrl+C` in the Broker terminal, let its shutdown finish, then stop the NameServer the same way. Delete `.rocketmq/` to discard the data.
  114. > This walkthrough runs without authentication or TLS, which is why every listener stays on loopback. Read the [deployment security guide](https://rocketmqrust.com/docs/deployment/security) before exposing a service to a network.
  115. ### Use the Client SDK in Your Application
  116. Add the client and the three crates it is used with:
  117. ```toml
  118. [dependencies]
  119. rocketmq-client-rust = "1.0.0"
  120. rocketmq-model = "1.0.0"
  121. rocketmq-runtime = "1.0.0"
  122. rocketmq-observability = "1.0.0"
  123. ```
  124. The application owns the runtime and hands it to every client. A minimal producer:
  125. ```rust
  126. use rocketmq_client_rust::{ClientRuntime, ClientRuntimeConfig, DefaultMQProducer};
  127. use rocketmq_model::common::message::message_single::Message;
  128. use rocketmq_observability::TelemetryRuntimeGuard;
  129. use rocketmq_runtime::RuntimeOwner;
  130. fn main() -> Result<(), Box<dyn std::error::Error>> {
  131. // The application owns the runtime; the client never creates a hidden one.
  132. let owner = RuntimeOwner::new()?;
  133. let telemetry = TelemetryRuntimeGuard::noop();
  134. let client_runtime = ClientRuntime::try_new(
  135. owner.root_context().component("example-client"),
  136. ClientRuntimeConfig::default(),
  137. telemetry.handle(),
  138. )?;
  139. let (sent, client_report) = owner.block_on(async {
  140. let mut producer = DefaultMQProducer::builder(client_runtime.clone())
  141. .producer_group("example_producer_group")
  142. .name_server_addr("127.0.0.1:9876")
  143. .build();
  144. let sent = async {
  145. producer.start().await?;
  146. let message = Message::builder()
  147. .topic("TopicTest")
  148. .body_slice(b"Hello RocketMQ")
  149. .build()?;
  150. producer.send_with_timeout(message, 3000).await
  151. }
  152. .await;
  153. // Shut down in order: producer, shared client runtime, then the owner.
  154. producer.shutdown().await;
  155. (sent, client_runtime.shutdown().await)
  156. });
  157. let runtime_report = owner.shutdown_runtime_blocking()?;
  158. println!("send result: {:?}", sent?);
  159. if !client_report.is_healthy() || !runtime_report.is_healthy() {
  160. return Err("client shutdown did not complete cleanly".into());
  161. }
  162. Ok(())
  163. }
  164. ```
  165. Consumers follow the same ownership pattern. Continue with:
  166. - [Client guide](./rocketmq-client) - Push and lite pull consumer examples, Cargo features and TLS
  167. - [First-message tutorial](https://rocketmqrust.com/docs/getting-started/quick-start) - The same path with an explicitly created topic and consumer group
  168. - [rocketmq-example](./rocketmq-example) - Ordered, delayed, transactional, batch and request/reply messaging
  169. - [Rust API migration guide](https://rocketmqrust.com/docs/migration/rust-api) - Source changes when upgrading from 0.x
  170. ## ๐Ÿ“ฆ Components & Crates
  171. The root Cargo workspace contains 29 crates. Publishable members use the shared workspace version. Directory and package names match, except that the `rocketmq-client` directory holds the `rocketmq-client-rust` package. Dashboard applications, AI operations products, examples and the website are standalone projects with their own manifests.
  172. ### Core Runtime Services
  173. | Crate | Responsibility |
  174. |-------|----------------|
  175. | [rocketmq-namesrv](./rocketmq-namesrv) | NameServer for Broker registration, liveness tracking, topic routing and KV configuration. Binary: `rocketmq-namesrv-rust`. |
  176. | [rocketmq-broker](./rocketmq-broker) | Broker for request processing, topic and consumer-group metadata, message storage, delivery and HA integration. Binary: `rocketmq-broker-rust`. |
  177. | [rocketmq-controller](./rocketmq-controller) | Controller for OpenRaft consensus, master election and replica metadata. Binary: `rocketmq-controller-rust`. |
  178. | [rocketmq-proxy](./rocketmq-proxy) | Proxy runtime exposing the gRPC `MessagingService` and an optional remoting ingress. Binary: `rocketmq-proxy-rust`. |
  179. | [rocketmq-proxy-core](./rocketmq-proxy-core) | Backend-neutral proxy contracts, protobuf bindings and ingress/session state. |
  180. | [rocketmq-proxy-cluster](./rocketmq-proxy-cluster) | Cluster-mode proxy adapter that reaches NameServers and Brokers through the client SDK. |
  181. | [rocketmq-proxy-local](./rocketmq-proxy-local) | Local-mode proxy adapter backed by an embedded Broker. |
  182. ### Client, Protocol, and Shared Libraries
  183. | Crate | Responsibility |
  184. |-------|----------------|
  185. | [rocketmq-client](./rocketmq-client) | Async client SDK with producers, transaction producers, push and lite pull consumers, and optional admin APIs. |
  186. | [rocketmq-protocol](./rocketmq-protocol) | RocketMQ wire contracts: request and response codes, remoting command frames, typed headers and bodies. |
  187. | [rocketmq-transport](./rocketmq-transport) | Bounded TCP/TLS transport with connection admission, dispatch and request deadlines. |
  188. | [rocketmq-model](./rocketmq-model) | Runtime-neutral domain types for messages, queues, topics and results. |
  189. | [rocketmq-auth](./rocketmq-auth) | Authentication and ACL authorization: access-key signatures, ACL files, users and policies. |
  190. | [rocketmq-security-api](./rocketmq-security-api) | Shared security contracts for principals, request policies, secret providers and bootstrap checks. |
  191. | [rocketmq-filter](./rocketmq-filter) | Tag and SQL92 message filtering, expression evaluation and Bloom filter utilities. |
  192. ### Storage, Runtime, and Observability
  193. | Crate | Responsibility |
  194. |-------|----------------|
  195. | [rocketmq-store](./rocketmq-store) | Broker-facing storage layer for CommitLog, ConsumeQueue, index, timer messages, POP checkpoints and HA replication. |
  196. | [rocketmq-store-api](./rocketmq-store-api) | Backend-neutral storage contracts for append, read, lifecycle, replication, checkpoint and health capabilities. |
  197. | [rocketmq-store-local](./rocketmq-store-local) | Local-file primitives: mapped files, flush, recovery, consume queues and indexes. |
  198. | [rocketmq-store-rocksdb](./rocketmq-store-rocksdb) | Optional RocksDB-backed derived state for consume queues, indexes, timers and transactions. |
  199. | [rocketmq-tieredstore](./rocketmq-tieredstore) | Optional tiered storage that dispatches older messages to a secondary storage layer and fetches them back. |
  200. | [rocketmq-runtime](./rocketmq-runtime) | Runtime substrate on Tokio: runtime ownership, tracked tasks, scheduling, bounded blocking execution and shutdown reports. |
  201. | [rocketmq-error](./rocketmq-error) | Shared error kernel with typed causes, stable descriptors and redaction-safe views. |
  202. | [rocketmq-macros](./rocketmq-macros) | Procedural macros for protocol types and request headers. |
  203. | [rocketmq-observability](./rocketmq-observability) | Logging, metrics and tracing with optional OpenTelemetry, OTLP and Prometheus exporters. |
  204. ### Operations Tooling
  205. | Crate | Responsibility |
  206. |-------|----------------|
  207. | [rocketmq-admin-cli](./rocketmq-tools/rocketmq-admin/rocketmq-admin-cli) | Command-line administration with a Java `mqadmin`-compatible command surface. |
  208. | [rocketmq-admin-tui](./rocketmq-tools/rocketmq-admin/rocketmq-admin-tui) | Interactive terminal UI for the same administration commands. |
  209. | [rocketmq-admin-core](./rocketmq-tools/rocketmq-admin/rocketmq-admin-core) | Presentation-independent admin services shared by the CLI, TUI, dashboards and MCP. |
  210. | [rocketmq-store-inspect](./rocketmq-tools/rocketmq-store-inspect) | Offline CommitLog inspection, downgrade preflight and multipath consolidation. Binary: `rocketmq-cli-rust`. |
  211. | [rocketmq-dashboard-common](./rocketmq-dashboard/rocketmq-dashboard-common) | Shared dashboard models and services. |
  212. | [rocketmq-dashboard-storage](./rocketmq-dashboard/rocketmq-dashboard-storage) | Native dashboard persistence with file storage and optional SQLite, MySQL and PostgreSQL drivers. |
  213. <p align="center">
  214. <img src="resources/rocketmq-admin-tui.png" alt="rocketmq-admin-tui showing consumer progress" width="85%"/>
  215. </p>
  216. ### Standalone Projects
  217. These projects live in this repository but outside the root workspace. Build each one from its own directory.
  218. | Project | Responsibility |
  219. |---------|----------------|
  220. | [rocketmq-example](./rocketmq-example) | Client examples covering send modes, ordered, delayed and transactional messages, request/reply, and push, lite pull and POP consumers. |
  221. | [rocketmq-dashboard-web](./rocketmq-dashboard/rocketmq-dashboard-web) | Web dashboard with a Rust backend and a React frontend. |
  222. | [rocketmq-dashboard-gpui](./rocketmq-dashboard/rocketmq-dashboard-gpui) | Native desktop dashboard built with GPUI. |
  223. | [rocketmq-dashboard-tauri](./rocketmq-dashboard/rocketmq-dashboard-tauri) | Cross-platform desktop dashboard built with Tauri and React. |
  224. | [rocketmq-mcp](./rocketmq-ai/rocketmq-mcp) | Read-only Model Context Protocol server for cluster diagnostics. |
  225. | [rocketmq-mcp-control](./rocketmq-ai/rocketmq-mcp-control) | Isolated, deny-by-default MCP server for supervised cluster changes. |
  226. | [rocketmq-mcp-auth](./rocketmq-ai/rocketmq-mcp-auth) | JWKS retrieval, caching and RS256 key selection shared by the two MCP servers. |
  227. | [rocketmq-sre](./rocketmq-ai/rocketmq-sre) | AI SRE platform for evidence collection, diagnostics, planning and controlled automation. |
  228. | [rocketmq-website](./rocketmq-website) | Docusaurus source of [rocketmqrust.com](https://rocketmqrust.com). |
  229. | [fuzz](./fuzz) | `cargo-fuzz` targets for protocol, configuration, controller snapshot and store recovery inputs. |
  230. ## ๐Ÿ’ก Capabilities
  231. | Area | What it provides |
  232. |------|------------------|
  233. | Messaging services | NameServer, Broker, Controller and Proxy with TOML configuration, health probes and graceful shutdown. The Broker also loads Java `.properties` files. |
  234. | Message types | Normal, ordered, delayed and timer, transactional, batch and request/reply messages, plus message recall. |
  235. | Producing | Synchronous, callback and one-way sends, batching and custom queue selection. |
  236. | Consuming | Push consumers with concurrent or orderly listeners, lite pull and POP consumption, clustering and broadcasting, tag and SQL92 filtering. |
  237. | Protocol | RocketMQ remoting commands, headers and serialization, and the gRPC `MessagingService` through the Proxy. |
  238. | Storage | Local CommitLog, ConsumeQueue and index files by default, with optional RocksDB and tiered storage. |
  239. | High availability | Master/replica replication with synchronous or asynchronous acknowledgement, and controller-mode failover built on OpenRaft. |
  240. | Security | Access-key authentication, ACL authorization, TLS transport and security bootstrap profiles. |
  241. | Observability | Structured logging, OpenTelemetry metrics, traces and logs, OTLP and Prometheus exporters. |
  242. | Operations | Admin CLI and TUI, offline store inspection, web and desktop dashboards, MCP servers and AI SRE. |
  243. Availability depends on Cargo features, runtime configuration and the selected storage backend or topology. The [capability matrix](https://rocketmqrust.com/docs/overview/capability-matrix) lists the conditions for each capability.
  244. ## ๐Ÿšข Deployment
  245. | Option | What you get | Start here |
  246. |--------|--------------|------------|
  247. | From source | Service binaries built with Cargo on Linux, Windows or macOS. | [Installation](https://rocketmqrust.com/docs/getting-started/installation) |
  248. | Container images | 13 `linux/amd64` images per release, with Cosign signatures and CycloneDX SBOM attestations on Docker Hub. | [Containers](https://rocketmqrust.com/docs/deployment/containers) |
  249. | Kubernetes | Helm charts and Kustomize manifests under [distribution](./distribution). | [Kubernetes](https://rocketmqrust.com/docs/deployment/kubernetes) |
  250. | High availability | Master/replica or controller-managed Broker groups. | [High availability](https://rocketmqrust.com/docs/deployment/high-availability) |
  251. Release images use the same component names in both registries:
  252. ```text
  253. docker.io/mxsm/rocketmq-rust-<component>:<version>
  254. ghcr.io/mxsm/rocketmq-rust/<component>:<version>
  255. ```
  256. The components are `namesrv`, `broker`, `controller`, `proxy`, `mcp`, `dashboard-web-backend`, `dashboard-web-frontend`, `sre-control-plane`, `sre-connector`, `sre-executor`, `sre-execution-agent`, `sre-probe` and `sre-ui`. Images ship without deployment configuration: a core service reads `/etc/rocketmq/<component>.toml` and keeps its data under `/var/lib/rocketmq`, so mount both. See the [release and image guide](rocketmq-doc/en/releasing.md) for details.
  257. ## ๐Ÿงช Build & Validation
  258. Cargo selects packages by name, so use `rocketmq-client-rust` for the `rocketmq-client` directory.
  259. | Task | Command |
  260. |------|---------|
  261. | Check one crate | `cargo check -p rocketmq-broker` |
  262. | Test one crate | `cargo test -p rocketmq-client-rust` |
  263. | Run a single test | `cargo test -p rocketmq-namesrv <test_name>` |
  264. | Check formatting of one crate | `cargo fmt -p rocketmq-broker -- --check` |
  265. | Lint one crate | `cargo clippy -p rocketmq-broker --no-deps -- -D warnings` |
  266. | Build the workspace | `cargo build --workspace` |
  267. | Test the workspace | `cargo test --workspace` |
  268. | Build local API documentation | `cargo doc --workspace --no-deps` |
  269. A full workspace build also compiles RocksDB and the Proxy's protobuf bindings, so it additionally needs Clang (libclang) and `protoc`, either on `PATH` or through the `PROTOC` environment variable. Standalone projects under `rocketmq-example/`, `rocketmq-dashboard/`, `rocketmq-ai/`, `rocketmq-website/` and `fuzz/` are built and validated from their own directories.
  270. ## ๐Ÿค Contributing
  271. We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or sharing ideas, your input is valuable.
  272. ### How to Contribute
  273. 1. **Pick** an [open issue](https://github.com/mxsm/rocketmq-rust/issues) or create one from the [issue templates](https://github.com/mxsm/rocketmq-rust/issues/new/choose); issues labeled [good first issue](https://github.com/mxsm/rocketmq-rust/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) are scoped for newcomers
  274. 2. **Fork** the repository and create a branch from `main`
  275. 3. **Change** one thing at a time, add or update tests, and run the [checks](#-build--validation) for the crates you touched
  276. 4. **Record** user-visible changes under **Unreleased** in [CHANGELOG.md](CHANGELOG.md)
  277. 5. **Open** a Pull Request against `main` that links the issue, with a title such as `[ISSUE #1234]๐Ÿ“Clarify consumer offset completion`
  278. ### Contribution Guidelines
  279. - Follow Rust best practices and the engineering rules in [AGENTS.md](AGENTS.md), which apply to people and AI coding agents alike
  280. - Add tests for new functionality
  281. - Update documentation as needed
  282. - Keep pull requests focused and leave unrelated code untouched
  283. - Follow the [Code of Conduct](CODE_OF_CONDUCT.md)
  284. For detailed guidelines, please read [CONTRIBUTING.md](CONTRIBUTING.md) and our [Contribution Guide](https://rocketmqrust.com/docs/contributing/overview).
  285. ### Repository Activity
  286. ![Repository Activity](https://repobeats.axiom.co/api/embed/6ca125de92b36e1f78c6681d0a1296b8958adea1.svg "Repobeats analytics image")
  287. ## โ“ FAQ
  288. <details>
  289. <summary><b>Is RocketMQ-Rust production-ready?</b></summary>
  290. `1.0.0` is the first stable release. The services ship with health probes, graceful shutdown, security profiles and observability, but production readiness also depends on your workload, topology and failure model. Validate the message paths you rely on and work through the [production checklist](https://rocketmqrust.com/docs/deployment/production-checklist) before going live.
  291. </details>
  292. <details>
  293. <summary><b>Is it compatible with Apache RocketMQ?</b></summary>
  294. RocketMQ-Rust implements the RocketMQ remoting protocol and, through the Proxy, the gRPC `MessagingService`, with Apache RocketMQ 5.5.0 as the comparison baseline. Compatibility is defined per surface, not as a blanket guarantee: the Controller runs its own OpenRaft protocol and cannot join a Java Controller quorum, DLedger is not supported, and a Java Broker's data directory is not a drop-in store. See the [protocol and compatibility reference](https://rocketmqrust.com/docs/reference/protocol-compatibility).
  295. </details>
  296. <details>
  297. <summary><b>What's the minimum supported Rust version (MSRV)?</b></summary>
  298. Rust 1.95.0. Every workspace manifest declares it as `rust-version`, and `rust-toolchain.toml` pins the same stable version for builds.
  299. </details>
  300. <details>
  301. <summary><b>How does performance compare to Java RocketMQ?</b></summary>
  302. No head-to-head figures are published, because throughput depends on hardware, storage, message size, and flush and replication policy. The Criterion benchmarks in the crates (`cargo bench -p <package>`) track regressions in individual components. For sizing, measure your own workload and read [capacity and performance](https://rocketmqrust.com/docs/operations/capacity-performance).
  303. </details>
  304. <details>
  305. <summary><b>Can I use it with existing RocketMQ deployments?</b></summary>
  306. Yes, at the client boundary. A Rust application can use `rocketmq-client-rust` against existing NameServers and Brokers over the remoting protocol, and gRPC clients can connect through the Proxy. Verify the operations you depend on against your exact server version, ACL and TLS settings. Rust and Java services do not share Controller quorums or data directories.
  307. </details>
  308. <details>
  309. <summary><b>How can I migrate from Java RocketMQ to RocketMQ-Rust?</b></summary>
  310. Choose the migration boundary first, because each one is a different operation:
  311. 1. Move applications to the Rust client SDK while keeping the existing cluster
  312. 2. Run a separate Rust cluster and shift traffic to it step by step
  313. 3. Replay or bridge historical data explicitly instead of reusing a Java data directory
  314. The Broker can load an existing Java `broker.properties` file and report how each setting was converted. Refer to the [migration guide](https://rocketmqrust.com/docs/migration/java-to-rust) for detailed steps.
  315. </details>
  316. ## ๐Ÿ‘ฅ Community & Support
  317. - **๐Ÿ’ฌ Discussions**: [GitHub Discussions](https://github.com/mxsm/rocketmq-rust/discussions) - Ask questions and share ideas
  318. - **๐Ÿ› Issues**: [GitHub Issues](https://github.com/mxsm/rocketmq-rust/issues) - Report bugs or request features
  319. - **๐Ÿ“ง Contact**: Reach out to [mxsm@apache.org](mailto:mxsm@apache.org)
  320. ### Contributors
  321. Thanks to all our contributors! ๐Ÿ™
  322. <a href="https://github.com/mxsm/rocketmq-rust/graphs/contributors">
  323. <img src="https://contrib.rocks/image?repo=mxsm/rocketmq-rust&anon=1" alt="RocketMQ-Rust contributors"/>
  324. </a>
  325. ## ๐Ÿ“„ License
  326. RocketMQ-Rust is licensed under the **Apache License 2.0**.
  327. See [LICENSE-APACHE](LICENSE-APACHE) and [NOTICE](NOTICE), or http://www.apache.org/licenses/LICENSE-2.0.
  328. ## ๐Ÿ™ Acknowledgments
  329. - **Apache RocketMQ Community** for the original Java implementation and design
  330. - **Rust Community** for excellent tooling and libraries
  331. - **All Contributors** who have helped make this project better
  332. ---
  333. <p align="center">
  334. <sub>Built with โค๏ธ by the RocketMQ-Rust community</sub>
  335. </p>
  336. [codecov-image]: https://codecov.io/gh/mxsm/rocketmq-rust/branch/main/graph/badge.svg
  337. [codecov-url]: https://codecov.io/gh/mxsm/rocketmq-rust

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If itโ€™s helped, pass it on.