fhmq/hmq: Go MQTT broker configuration and cluster limits

Where fhmq/hmq fits in an MQTT deployment

fhmq/hmq solves the central broker-side problem of accepting MQTT connections and routing messages between publishers and subscribers. The README identifies it as a Go implementation of MQTT 3.1.1 and says it is compatible with Eclipse Paho clients and mosquitto-client. That makes it relevant to IoT services, internal telemetry systems, and applications that publish events to named topics through standard MQTT clients.

The supported delivery set is narrower than the full range of modern MQTT capabilities. The feature list explicitly names QoS 0 and QoS 1, retained messages, will messages, WebSocket support, TLS, authentication, access control, caching, and a Kafka bridge. It does not list QoS 2. Applications whose protocol requirements depend on exactly-once QoS 2 delivery therefore need a different broker or an independently verified extension.

The README describes the project as a "High performance MQTT broker" and lists high throughput, high concurrency, and low memory and CPU as goals. It does not publish benchmark results, test conditions, hardware details, or comparison figures. Those statements indicate design intent, not evidence that a particular deployment will meet a stated latency or capacity target. The linked mqtt-stresser and mqtt-benchmark repositories are presented as tools for measurement, but their results are not included here.

fhmq/hmq client paths, workers, and plugin configuration

The documented architecture exposes a conventional MQTT TCP listener and a separate WebSocket listener. Command-line defaults put MQTT clients on port 1883 and bind them to 0.0.0.0. The configuration example adds TLS on port 8883 and WebSocket monitoring on port 1888 at `/ws`. The term "monitoring" is used by the CLI and README, although the feature list describes WebSocket support more generally.

The worker setting controls how many workers process messages. Its help text recommends a value derived from the client count, specifically `(client num)/10`, while showing a default of 1024. The sample configuration instead sets `workerNum` to 4096. This indicates that the operator is expected to tune concurrency for the deployment rather than rely on one universal value.

The repository layout separates the broker, logger, pool, SSL code, and plugins. The configuration selects plugins by name through `auth` and `bridge`; the sample selects `authhttp` and `kafka`. The module dependencies also include Gin, Sarama, Go cache, Paho's Go client, JSON libraries, UUID generation, and Zap. Based on those dependencies, HMQ includes HTTP-facing components and Kafka integration, but the README does not provide the authentication endpoint contract or describe Kafka failure and replay semantics in enough detail to treat those interfaces as stable APIs.

Running HMQ and completing a first MQTT use

The README's shortest launch path uses Go module retrieval, changes into the GOPATH checkout, and runs `main.go`. It then listens with the documented defaults unless a configuration file or command-line option is supplied. This is a developer-oriented startup path rather than a packaged installation procedure.

The following commands are copied from the README. The reader should see the broker start on its configured MQTT listener, which defaults to port 1883.

$ go get github.com/fhmq/hmq
$ cd $GOPATH/github.com/fhmq/hmq
$ go run main.go

A first client exchange can use mosquitto-client, which the README names as compatible. Its shared-subscription example publishes to an ordinary topic while the subscriber addresses that topic through `$share/<group>/topic`. The commands below reproduce the README exactly, including the typographic quote marks.

mosquitto_sub -t ‘$share/<group>/topic’
mosquitto_pub -t ‘topic’

The README explains the shared-subscription syntax but does not supply a complete expected payload sequence. Consequently, the observable first check is limited to subscribing, publishing, and observing delivery with the client tools and replacing `<group>` with a group name. The documentation does not describe client IDs, retained-message creation, authentication credentials, or a required `-m` message argument for the publish command, so those details should not be guessed.

Before trying a production configuration, note that the module declares Go 1.26.6, while the Dockerfile uses `golang:1.18` as its builder. That mismatch can prevent a clean container build or cause an unsuitable toolchain to be selected for local execution. It should be resolved before relying on either documented path.

HMQ TLS, authentication, and Kafka bridge boundaries

The sample `hmq.config` defines a security-oriented listener with `tlsPort` set to 8883 and `tlsHost` set to `0.0.0.0`. Its `tlsInfo` object enables verification and names a CA certificate, server certificate, and private key. The configuration also exposes a plugin selection for HTTP authentication. The README lists authentication checks at connect time, ACLs, and cache support, but it does not document the authentication service's request schema, failure response, cache invalidation rules, or whether ACL evaluation occurs only during CONNECT or also for publish and subscribe operations.

The Kafka bridge is selected with `"bridge": "kafka"`. Its listed delivery modes are action delivery and regular-expression delivery. The IBM Sarama dependency confirms that Kafka support is present in the Go module. However, the README does not specify topic mapping, producer configuration, acknowledgements, ordering, retry behavior, or what happens to MQTT messages when Kafka delivery fails. Those omissions matter more for production adoption than the mere presence of a bridge name.

HMQ can also publish connection state under `$SYS/broker/connection/clients/<clientID>`. Its documented payload contains `clientID`, an `online` boolean, and a timestamp. This gives subscribers a mechanism for online and offline notification. The example timestamp is old, and no compatibility promise is stated, so consumers should not assume that every field beyond the three shown will remain unchanged.

Router-based clustering and the gRPC HMQ alternative

The documented cluster design does not have each HMQ node discover peers by itself. The README directs the operator to start the separate `fhmq/router` project, configure HMQ with the router address, and use the cluster port for communication with other nodes. The relevant startup commands are:

$ go get github.com/fhmq/router
$ cd $GOPATH/github.com/fhmq/router
$ go run main.go

The sample HMQ configuration points to `"router": "127.0.0.1:9888"` and sets the cluster port to 1993. In a deployment with multiple hosts, the documented loopback address is a starting example rather than a complete multi-node address plan. The documentation does not explain router discovery, node identity, leader behavior, partition ownership, replication, rebalancing, or recovery after a node or router failure. Those are material cluster design questions, and the cluster option alone does not answer them.

The README also points to `rhmq` as another cluster implementation based on gRPC. That is a real architectural alternative within the project family: this HMQ version uses the separate router-based cluster approach, while `rhmq` is described as cluster-based on gRPC. The available documentation does not compare their protocols, operating model, feature parity, or migration path, so the choice cannot be reduced to a simple performance claim. Operators would need to inspect `rhmq` separately before selecting it.

HMQ release cadence, upgrade work, and Apache-2.0 implications

The repository is not archived. Its last push was on 2026-08-21, and releases v1.5.9 and v1.5.8 were published on 2026-08-21 and 2026-05-31 respectively. That supports recent project activity, although it does not by itself establish release compatibility or production stability.

The version jump from the Dockerfile's Go 1.18 base to the module directive `go 1.26.6` is a concrete upgrade concern. It affects both container builds and developer workstations. The repository also uses a wide set of direct dependencies, including Sarama, Gin, Paho, cache, JSON, UUID, and Zap packages. Upgrading HMQ may therefore require dependency and plugin regression checks, especially for authentication, Kafka delivery, WebSocket connections, TLS, and shared subscriptions.

HMQ is distributed under Apache License Version 2.0. That license permits broad use and modification subject to its conditions, including preservation of applicable notices and state of changes. This is not legal advice. For a commercial deployment, the relevant questions concern how HMQ is distributed, whether modifications are offered separately, and whether bundled third-party components introduce separate notices or obligations.

Editorial conclusion

Adopt fhmq/hmq when an MQTT 3.1.1 deployment specifically needs its Go codebase, WebSocket access, Kafka bridge, or router-based clustering, and avoid it when QoS 2 or a fully documented production upgrade path is mandatory. Before adoption, reconcile the required Go 1.26.6 module directive with the Docker image's Go 1.18 builder, then verify TLS files, authentication behavior, Kafka delivery, and cluster recovery in the intended environment.

Frequently asked questions

Official sources

1. fhmq/hmq on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases