Repository navigation
v0.1.0 — first tagged release
A multi-tenant MQTT broker built on core NATS. One binary: run it standalone at a customer site, or split it into core and edge roles for a cluster.
Why it exists
Every open-source MQTT broker that does real multi-tenancy asks you to give something up. EMQX adopted the Business Source License in 5.9, so forming a cluster from more than one node needs a paid licence key. BifroMQ has genuine native multi-tenancy but runs on the JVM. VerneMQ's source is Apache 2.0 while its official packages and images are governed by a EULA that charges for commercial use. RabbitMQ gives you vhosts but supports neither QoS 2 nor shared subscriptions. Mosquitto, NanoMQ, FlashMQ and mochi-mqtt do not cluster at all.
mast is the combination that did not otherwise exist: MQTT 5 with shared subscriptions, tenant isolation, free clustering, no JVM, and a single binary.
What works
Verified by end-to-end tests that drive a real MQTT client against a real node, and by a three-process cluster of one core and two edge nodes:
- MQTT 3.1.1 and 5.0, QoS 0 through 2, honoured at the level the subscriber negotiated
- Retained messages, stored cluster-wide in JetStream KV rather than per node
- Persistent sessions — a client reconnecting with
clean_start=falsereceives what it missed while away - Wills, delivered on an ungraceful disconnect and suppressed by a clean
DISCONNECT - Shared subscriptions —
$share/<group>/<filter>maps onto a NATS queue group, and each message reaches exactly one member - Wildcards, including
foo/#matchingfooitself, which NATS's>does not do on its own - Topics containing
., a leading/, empty levels and non-ASCII, all arriving byte-identical
Tenant isolation is structural, not a convention. Every topic is mounted under its tenant before validation, authorization or subscription ever sees it, and unmounted again on the way out. A client never learns the prefix exists, and two tenants publishing to a/b cannot reach each other.
How it is put together
Core NATS moves messages; a key-value store holds keys. Live fan-out rides core NATS, which handles tens of millions of subjects. Sessions, retained messages and offline queues live in a handful of JetStream KV buckets.
What mast deliberately never does is create a JetStream consumer per subscription. Consumers are Raft state machines, a server holds on the order of two thousand of them, and a real fleet would want hundreds of thousands. Durable state has to scale as keys, not as consensus groups.
Replacing EMQX
mast speaks EMQX v5's HTTP auth wire, including is_superuser, so an auth service written for EMQX works unchanged. Topics reach the authorization endpoint unmounted, so existing ACL rules keep working. This release has replaced a live EMQX deployment in a staging environment with no changes to any consumer.
Authentication comes two ways: ask an HTTP service, or verify a signed JWT locally. They compose — authenticate from a token while topic decisions still go to a policy server.
Install
$ docker run --rm -p 1883:1883 ghcr.io/mastmq/mast:0.1.0
$ go install github.com/mastmq/mast/cmd/mast@v0.1.0Helm charts live in mastmq/charts.
$ mast # all-in-one: MQTT and storage, no cluster
$ mast --role=core # Raft and the KV buckets
$ mast --role=edge # MQTT listeners, joins the core as a leaf nodeYou do not need the split until you are big. Up to roughly ten nodes, run every process identical and let them mesh.
Known gaps
Gaps are tracked as issues rather than described as a roadmap. See the parity label for what an MQTT client is entitled to assume and does not yet get.
- Sessions do not survive a broker restart or move between nodes (#8). A session resumes for the lifetime of the node holding it; it is not yet durable across a restart.
- Throughput has not been characterised. The benchmarking so far measured the load generator rather than the broker — the generator saturated while mast sat at 63–115 millicores. Treat the absence of a number here as deliberate; there will be one when it is defensible.
- There is no dashboard and no management API, and no plan for a rule engine or data bridges.
- No connection rate limiting yet.
Apache 2.0.