An embeddable high-performance MQTT broker server written in Golang

supporting distributed cluster, and compliant with the MQTT v3.0 and v3.1.1 and v5.0 specifications for the development of IoT and smarthome projects. The server can be used either as a standalone binary or embedded as a library in your own projects. CoMQTT message throughput is comparable with everyone’s favorites, such as Mosquitto, Mosca, and VerneMQ.

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

Co MQTT Features

• Paho MQTT 3.0 / 3.1.1 / 5.0 compatible.
• Full MQTT Feature-set (QoS, Retained, $SYS).
• Interfaces for Client Authentication and Topic access control. Auth&ACL based on Redis/HTTP/Mysql is already supported.
• Trie-based Subscription model.
• Ring Buffer packet codec.
• TCP, Websocket, (including SSL/TLS) and Dashboard listeners.
• Bolt persistence and storage interfaces (see examples folder).
• Directly Publishing from embedding service (s.Publish(topic, message, retain)).
• Basic Event Hooks (OnMessage, onSubscribe, onUnsubscribe, OnConnect, OnDisconnect, onProcessMessage, OnError, OnStorage).
• ARM32 Compatible.
• Distributed Cluster.

Roadmap

• Auth plugin
• Rule engine
• Bridge
• CoAP

Using the Golang MQTT Broker

CoMQTT can be used as a standalone broker. Simply checkout this repository and run the main.go entry point in the cmd folder which will expose tcp (:1883), websocket (:1882), and dashboard (:8080) listeners. A docker image is coming soon.

cd cmd
go build -o commqtt && ./comqtt

Using Docker

A simple Dockerfile is provided for running the cmd/single/main.go Websocket, TCP, and Stats server:

docker build -t comqtt:latest .
docker run -p 1883:1883 -p 1882:1882 -p 8080:8080 comqtt:latest

Quick Start with Golang

import (
  mqtt "github.com/wind-c/comqtt/server"
)

func main() {
    // Create the new MQTT Server.
    server := mqtt.NewServer(nil)
	
    // Create a TCP listener on a standard port.
    tcp := listeners.NewTCP("t1", ":1883")
	
    // Add the listener to the server with default options (nil).
    err := server.AddListener(tcp, nil)
    if err != nil {
        log.Fatal(err)
    }
	
    // Start the broker. Serve() is blocking - see examples folder 
    // for usage ideas.
    err = server.Serve()
    if err != nil {
        log.Fatal(err)
    }
}

Examples of running the broker with various configurations can be found in the examples folder.

Network Listeners

The server comes with a variety of pre-packaged network listeners which allow the broker to accept connections on different protocols. The current listeners are:

• listeners.NewTCP(id, address string) – A TCP Listener, taking a unique ID and a network address to bind.
• listeners.NewWebsocket(id, address string) A Websocket Listener
• listeners.NewHTTPStats() An HTTP $SYS info dashboard

Configuring Network Listeners

When a listener is added to the server using server.AddListener, a *listeners.Config may be passed as the second argument.

Authentication and ACL

Authentication and ACL may be configured on a per-listener basis by providing an Auth Controller to the listener configuration. Custom Auth Controllers should satisfy the auth.Controller interface found in listeners/auth. Two default controllers are provided, auth.Allow, which allows all traffic, and auth.Disallow, which denies all traffic.

err := server.AddListener(tcp, &listeners.Config{
	Auth: new(auth.Allow),
})

If no auth controller is provided in the listener configuration, the server will default to Disallowing all traffic to prevent unintentional security issues.

SSL

SSL may be configured on both the TCP and Websocket listeners by providing a public-private PEM key pair to the listener configuration as []byte slices.

err := server.AddListener(tcp, &listeners.Config{
    Auth: new(auth.Allow),
    TLS: &listeners.TLS{
        Certificate: publicCertificate, 
        PrivateKey:  privateKey,
    },
})

Note the mandatory inclusion of the Auth Controller!

Event Hooks with Golang based MQTT Server

Some basic Event Hooks have been added, allowing you to call your own functions when certain events occur. The execution of the functions are blocking – if necessary, please handle goroutines within the embedding service.

Working examples can be found in the examples/events folder. Please open an issue if there is a particular event hook you are interested in!