Modern MQTT v3.1.1/5.0 library in pure Go, for Go, C/C++, Java
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
benchmark add full example, update readme Nov 1, 2018
c update c options Dec 13, 2018
cmd/libmqtt update readme, fix java package name, bump go version to 1.10.x May 22, 2018
examples add full example, update readme Nov 1, 2018
extension pass fuzz test for mqtt 3.1.1 and 5 Jan 23, 2018
java update readme, fix java package name, bump go version to 1.10.x May 22, 2018
testdata client implemention Dec 6, 2017
vendor update vendor for ci test Dec 13, 2018
.gitignore add go.mod and vendor for travis ci test Oct 5, 2018
.travis.yml more efficient and tested packet id generation, simplify ci test recipe Dec 13, 2018
LICENSE update license, use goiiot.org Jan 19, 2018
Makefile more efficient and tested packet id generation, simplify ci test recipe Dec 13, 2018
README.md update readme Dec 1, 2018
client_async.go more efficient and tested packet id generation, simplify ci test recipe Dec 13, 2018
client_conn.go more efficient and tested packet id generation, simplify ci test recipe Dec 13, 2018
client_options.go update c options Dec 13, 2018
client_reconn_test.go remove Client interface, add type alias for backwords compatibility Dec 1, 2018
client_test.go more efficient and tested packet id generation, simplify ci test recipe Dec 13, 2018
decoder.go remove redundant params Nov 1, 2018
decoder_test.go prepare mqtt v5.0 test Jul 9, 2018
encoder.go embed encoder into packet Aug 27, 2018
encoder_test.go bundle ProtoVersion into packet Jan 21, 2018
fuzz.go pass fuzz test for mqtt 3.1.1 and 5 Jan 23, 2018
go.mod update vendor for ci test Dec 13, 2018
handler.go Add an 's' to handler.go Oct 17, 2018
libmqtt.go embed encoder into packet Aug 27, 2018
libmqtt_test.go embed encoder into packet Aug 27, 2018
log.go fix auto reconnect issue, add auto reconnect test, should fix #13 Oct 5, 2018
log_test.go update license, use goiiot.org Jan 19, 2018
msg.go update client handler api, use byte instead of FooCode Jan 21, 2018
msg_test.go prepare mqtt v5.0 test Jul 9, 2018
persist.go bundle ProtoVersion into packet Jan 21, 2018
persist_test.go bundle ProtoVersion into packet Jan 21, 2018
pkt_auth.go rename packet files Dec 1, 2018
pkt_auth_test.go rename packet files Dec 1, 2018
pkt_conn.go rename packet files Dec 1, 2018
pkt_conn_test.go rename packet files Dec 1, 2018
pkt_ping.go rename packet files Dec 1, 2018
pkt_ping_test.go rename packet files Dec 1, 2018
pkt_pub.go rename packet files Dec 1, 2018
pkt_pub_test.go rename packet files Dec 1, 2018
pkt_sub.go rename packet files Dec 1, 2018
pkt_sub_test.go rename packet files Dec 1, 2018
router.go update license, use goiiot.org Jan 19, 2018
router_test.go update client handler api, use byte instead of FooCode Jan 21, 2018
util.go more efficient and tested packet id generation, simplify ci test recipe Dec 13, 2018
util_test.go more efficient and tested packet id generation, simplify ci test recipe Dec 13, 2018

README.md

libmqtt

Build Status GoDoc GoReportCard codecov

Feature rich modern MQTT library in pure Go, for Go, C/C++, Java

Table of contents

Features

  1. MQTT v3.1.1/v5.0 client support (async only)
  2. High performance and less memory footprint (see Benchmark)
  3. Customizable topic routing (see Topic Routing)
  4. Multiple Builtin session persist methods (see Session Persist)
  5. C/C++ lib, Java lib, Command line client support
  6. Idiomatic Go

Usage

This package can be used as

As a Go lib

Prerequisite

  • Go 1.9+

Steps

TL;DR: You can find a full example at examples/client.go

1.Go get this project

go get github.com/goiiot/libmqtt

2.Import this package in your project file

import "github.com/goiiot/libmqtt"

3.Create a custom client

// Create a client and enable auto reconnect when connection lost
// We primarily use `RegexRouter` for client
client, err := libmqtt.NewClient(
    // server address(es)
    libmqtt.WithServer("localhost:1883"),
    // enable keepalive (10s interval) with 20% tolerance
    libmqtt.WithKeepalive(10, 1.2),
    // enable auto reconnect and set backoff strategy
    libmqtt.WithAutoReconnect(true),
    libmqtt.WithBackoffStrategy(time.Second, 5*time.Second, 1.2),
    // use RegexRouter for topic routing if not specified
    // will use TextRouter, which will match full text
    libmqtt.WithRouter(libmqtt.NewRegexRouter()),
)

if err != nil {
    // handle client creation error
    panic("create mqtt client failed")
}

Notice: If you would like to explore all the options available, please refer to GoDoc#Option

4.Register the handlers and Connect, then you are ready to pub/sub with server

Optional, but we recommend to register handlers for pub, sub, unsub, net error and persist error, and you can gain more controllability of the lifecycle of the client

client.HandlePub(PubHandler) // register handler for pub success/fail (optional, but recommended)
client.HandleSub(SubHandler) // register handler for sub success/fail (optional, but recommended)
client.HandleUnSub(UnSubHandler) // register handler for unsub success/fail (optional, but recommended)
client.HandleNet(NetHandler) // register handler for net error (optional, but recommended)
client.HandlePersist(PersistHandler) // register handler for persist error (optional, but recommended)

// define your topic handlers like a golang http server client.Handle("foo", func(topic string, qos libmqtt.QosLevel, msg []byte) { // handle the topic message })

client.Handle("bar", func(topic string, qos libmqtt.QosLevel, msg []byte) { // handle the topic message })

// connect to server
client.Connect(func(server string, code byte, err error) {
    if err != nil {
        // failed
        panic(err)
    }

    if code != libmqtt.CodeSuccess {
        // server rejected or in error
        panic(code)
    }

    // success
    // you are now connected to the `server`
    // (the `server` is one of your provided `servers` when create the client)
    // start your business logic here or send a signal to your logic to start

    // subscribe some topic(s)
    client.Subscribe([]*libmqtt.Topic{
        {Name: "foo"},
        {Name: "bar", Qos: libmqtt.Qos1},
    }...)

    // publish some topic message(s)
    client.Publish([]*libmqtt.PublishPacket{
        {TopicName: "foo", Payload: []byte("bar"), Qos: libmqtt.Qos0},
        {TopicName: "bar", Payload: []byte("foo"), Qos: libmqtt.Qos1},
    }...)
})

5.Unsubscribe topic(s)

client.UnSubscribe("foo", "bar")

6.Destroy the client when you would like to

// use true for a immediate disconnect to server
// use false to send a DisConn packet to server before disconnect
client.Destroy(true)

As a C/C++ lib

Please refer to c - README.md

As a Java lib

Please refer to java - README.md

As a command line client

Please refer to cmd/libmqtt - README.md

As MQTT infrastructure

This package can also be used as MQTT packet encoder and decoder

// decode one mqtt 3.1.1 packet from reader
packet, err := libmqtt.Decode(libmqtt.V311, reader)
// ...

// encode one mqtt packet to buffered writer
err := libmqtt.Encode(packet, bufferWriter)
// ...

Topic Routing

Routing topics is one of the most important thing when it comes to business logic, we currently have built two TopicRouters which is ready to use, they are TextRouter and RegexRouter

  • TextRouter will match the exact same topic which was registered to client by Handle method. (this is the default router in a client)
  • RegexRouter will go through all the registered topic handlers, and use regular expression to test whether that is matched and should dispatch to the handler

If you would like to apply other routing strategy to the client, you can provide this option when creating the client

client, err := libmqtt.NewClient(
    // ...
    // e.g. use `RegexRouter`
    libmqtt.WithRouter(libmqtt.NewRegexRouter()),
    // ...
)

Session Persist

Per MQTT Specification, session state should be persisted and be recovered when next time connected to server without clean session flag set, currently we provide persist method as following:

  1. NonePersist - no session persist
  2. memPersist - in memory session persist
  3. filePersist - files session persist (with write barrier)
  4. redisPersist - redis session persist (available inside github.com/goiiot/libmqtt/extension package)

Note: Use RedisPersist if possible.

Benchmark

The procedure of the benchmark is:

  1. Create the client
  2. Connect to server
  3. Publish N times to topic foo
  4. Unsubscribe topic (just ensure all pub message has been sent)
  5. Destroy client (without disconnect packet)

The benchmark result listed below was taken on a MacBook Pro 13' (Early 2015, macOS 10.13.2), statistics inside which is the value of ten times average

Bench Name Pub Count ns/op B/op allocs/op
BenchmarkLibmqttClient-4 (this project) 100000 20187 176 6
BenchmarkPahoClient-4 (eclipse paho) 100000 25072 816 15

You can make the benchmark using source code from benchmark

Extensions

Helpful extensions for libmqtt (see extension)

LICENSE

GitHub license

Copyright Go-IIoT (https://github.com/goiiot)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.