Mochi-MQTT Server
[!NOTE]
This is a detached fork. The original is mochi-mqtt/server by mochi-co and contributors, MIT licensed, and all credit for this library belongs to them. It is republished here under github.com/mastmq/mochi/v2 because upstream stopped merging — main has not moved since 2025-03-01 and 47 pull requests are open — and mast embeds it. See FORK.md for what differs.
English | 简体中文 | 日本語 | Translators Wanted!
🎆 mochi-co/mqtt is now part of the new mochi-mqtt organisation. Read about this announcement here.
Mochi-MQTT is a fully compliant, embeddable high-performance Go MQTT v5 (and v3.1.1) broker/server
Mochi MQTT is an embeddable fully compliant MQTT v5 broker server written in Go, designed for the development of telemetry and internet-of-things projects. The server can be used either as a standalone binary or embedded as a library in your own applications, and has been designed to be as lightweight and fast as possible, with great care taken to ensure the quality and maintainability of the project.
What is MQTT?
MQTT stands for MQ Telemetry Transport. It is a publish/subscribe, extremely simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks (Learn more). Mochi MQTT fully implements version 5.0.0 of the MQTT protocol.
Mochi-MQTT Features
- Full MQTTv5 Feature Compliance, compatibility for MQTT v3.1.1 and v3.0.0:
- User and MQTTv5 Packet Properties
- Topic Aliases
- Shared Subscriptions
- Subscription Options and Subscription Identifiers
- Message Expiry
- Client Session Expiry
- Send and Receive QoS Flow Control Quotas
- Server-side Disconnect and Auth Packets
- Will Delay Intervals
- Plus all the original MQTT features of Mochi MQTT v1, such as Full QoS(0,1,2), $SYS topics, retained messages, etc.
- Developer-centric:
- Most core broker code is now exported and accessible, for total developer control.
- Full-featured and flexible Hook-based interfacing system to provide easy 'plugin' development.
- Direct Packet Injection using special inline client, or masquerade as existing clients.
- Performant and Stable:
- Our classic trie-based Topic-Subscription model.
- Client-specific write buffers to avoid issues with slow-reading or irregular client behaviour.
- Passes all Paho Interoperability Tests for MQTT v5 and MQTT v3.
- Over a thousand carefully considered unit test scenarios.
- TCP, Websocket (including SSL/TLS), and $SYS Dashboard listeners.
- Built-in Redis, Badger, Pebble and Bolt Persistence using Hooks (but you can also make your own).
- Built-in Rule-based Authentication and ACL Ledger using Hooks (also make your own).
Compatibility Notes
Because of the overlap between the v5 specification and previous versions of mqtt, the server can accept both v5 and v3 clients, but note that in cases where both v5 an v3 clients are connected, properties and features provided for v5 clients will be downgraded for v3 clients (such as user properties).
Support for MQTT v3.0.0 and v3.1.1 is considered hybrid-compatibility. Where not specifically restricted in the v3 specification, more modern and safety-first v5 behaviours are used instead - such as expiry for inflight and retained messages, and clients - and quality-of-service flow control limits.
When is this repo updated?
Unless it's a critical issue, new releases typically go out over the weekend.
Roadmap
- Please open an issue to request new features or event hooks!
- Cluster support.
- Enhanced Metrics support.
Quick Start
Running the Broker with Go
Mochi MQTT can be used as a standalone broker. Simply checkout this repository and run the cmd/main.go entrypoint in the cmd folder which will expose tcp (:1883), websocket (:1882), and dashboard (:8080) listeners.
cd cmd
go build -o mqtt && ./mqtt
Using Docker
You can now pull and run the official Mochi MQTT image from our Docker repo:
docker pull mochimqtt/server
or
docker run -v $(pwd)/config.yaml:/config.yaml mochimqtt/server
For most use cases, you can use File Based Configuration to configure the server, by specifying a valid yaml or json config file.
A simple Dockerfile is provided for running the cmd/main.go Websocket, TCP, and Stats server, using the allow-all auth hook.
docker build -t mochi:latest .
docker run -p 1883:1883 -p 1882:1882 -p 8080:8080 -v $(pwd)/config.yaml:/config.yaml mochi:latest
File Based Configuration
You can use File Based Configuration with either the Docker image (described above), or by running the build binary with the --config=config.yaml or --config=config.json parameter.
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
