# README
go-mqtt
go-mqtt is a high performance MQTT broker and client library that aims to be fully compliant with MQTT 3.1.1 specification. This project is a continuation of the no longer maintained and further developed SurgeMQ.
Features
- Supports QOS 0, 1 and 2 messages.
- Supports will messages.
- Supports retained messages (add/remove).
- Pretty much everything in the specification except for the list below.
Limitations
- All features supported are in memory only. Once the server restarts everything is cleared.
- However, all the components are written to be pluggable so one can write plugins based on the Go interfaces defined.
- Message redelivery on reconnect is not currently supported.
- Message offline queueing on disconnect is not supported. Though this is also not a specific requirement for MQTT.
Performance
Current performance benchmark, running all publishers, subscribers and broker on a single 4-core (2.8 Ghz i7) MacBook Pro:
- Over 400,000 MPS in a 1:1 single publisher and single producer configuration.
- Over 450,000 MPS in a 20:1 fan-in configuration.
- Over 750,000 MPS in a 1:20 fan-out configuration.
- Over 700,000 MPS in a full mesh configuration with 20 clients.
Compatibility
In addition, this library has been tested with the following client libraries, and it seems to work:
- libmosquitto 1.3.5 (in C)
- Tested with the bundled test programs msgsps_pub and msgsps_sub.
- Paho MQTT Conformance/Interoperability Testing Suite (in Python). Tested with all 10 test cases, 3 did not pass. They are:
- "offline messages queueing test" which is not supported by go-mqtt.
- "redelivery on reconnect test" which is not yet implemented by go-mqtt.
- "run subscribe failure test" which is not a valid test.
- Paho Go Client Library (in Go)
- Tested with one of the tests in the library, in fact, that tests is now part of the tests for go-mqtt.
- Paho C Client library (in C)
- Tested with most of the test cases and failed the same ones as the conformance test because the features are not yet implemented.
- Actually I think there's a bug in the test suite as it calls the PUBLISH handler function for non-PUBLISH messages.
Server Example
// Create a new server
svr := &service.Server{
KeepAlive: 300, // seconds
ConnectTimeout: 2, // seconds
SessionsProvider: "mem", // keeps sessions in memory
Authenticator: "mockSuccess", // always succeed
TopicsProvider: "mem", // keeps topic subscriptions in memory
}
// Listen and serve connections at localhost:1883
svr.ListenAndServe("tcp://:1883")
Client Example
// Instantiates a new Client
c := &Client{}
// Creates a new MQTT CONNECT message and sets the proper parameters
msg := message.NewConnectMessage()
msg.SetWillQos(1)
msg.SetVersion(4)
msg.SetCleanSession(true)
msg.SetClientId([]byte("go-mqtt"))
msg.SetKeepAlive(10)
msg.SetWillTopic([]byte("will"))
msg.SetWillMessage([]byte("send me home"))
msg.SetUsername([]byte("go-mqtt"))
msg.SetPassword([]byte("verysecret"))
// Connects to the remote server at 127.0.0.1 port 1883
c.Connect("tcp://127.0.0.1:1883", msg)
// Creates a new SUBSCRIBE message to subscribe to topic "abc"
submsg := message.NewSubscribeMessage()
submsg.AddTopic([]byte("abc"), 0)
// Subscribes to the topic by sending the message. The first nil in the function
// call is a OnCompleteFunc that should handle the SUBACK message from the server.
// Nil means we are ignoring the SUBACK messages. The second nil should be a
// OnPublishFunc that handles any messages send to the client because of this
// subscription. Nil means we are ignoring any PUBLISH messages for this topic.
c.Subscribe(submsg, nil, nil)
// Creates a new PUBLISH message with the appropriate contents for publishing
pubmsg := message.NewPublishMessage()
pubmsg.SetPacketId(pktid)
pubmsg.SetTopic([]byte("abc"))
pubmsg.SetPayload(make([]byte, 1024))
pubmsg.SetQoS(qos)
// Publishes to the server by sending the message
c.Publish(pubmsg, nil)
// Disconnects from the server
c.Disconnect()
License
This work is licensed under the Apache License V2.
Authors
The authors are listed in the file AUTHORS.txt.
# Packages
No description provided by the author
No description provided by the author
Package message is an encoder/decoder library for MQTT 3.1 and 3.1.1 messages.
Package service provides the MQTT Server and Client services in a library form.
No description provided by the author
Package topics deals with MQTT topic names, topic filters and subscriptions.