This repository contains the source code for the Eclipse Paho MQTT V5 Go client library.
Warning breaking change - Release 0.12 contains a breaking change; see the release notes.
Release v0.20 includes major changes (some breaking), much of this is due to the introduction of full QOS1/2 support. We do expect that most code will run as-is, or with minor changes; known breaking changes are noted below (but due to the extensive changes between releases 0.12 and 0.20 this list is probably incomplete):
paho
paho.Publish
when publishing at QOS1/2 the packet identifier (if acquired) was released if the context expired
regardless of whether the message had been sent (potentially leading to reuse of the ID and in breach of the spec).
This has been changed such that once transmitted, the message will be acknowledged regardless of the publish context
(but the Publish function will only block until the context expires). The Errors returned now better indicate what
occurred.ClientConfig.Router
will be removed in a future
release. Please replace ClientConfig.Router
with ClientConfig.OnPublishReceived
(which is more flexible; note that
you can still use StandardRouter
- see autopaho/examples/router
).ClientConfig
is now private (accessing this led to race conditions).Pinger
interface has changed (and DefaultPinger
has been rewritten).ClientOptions.MIDs
has been removed.autopaho
autopaho
CleanSession flag. Previously CleanSession
was hardcoded to true
; this is no longer the case and
the default is false
. Whilst his is potentially a breaking change, SessionExpiryInterval
will default to 0 meaning
the session will be removed when the connection drops. As a result this change should have no impact on most users; it
may be a problem if another application has connected with SessionExpiryInterval>0
meaning a session exists.ConnectPacketBuilder
arguments have changed to func(*paho.Connect, *url.URL) *paho.Connect
.There is also a v3 client available (note that this is an older project, and its API is very different to this one).
We recommend that new users begin with autopaho
; this
provides a simple client that should be sufficient for most use-cases.
The main library is in the paho
folder (so for general usage import "github.com/eclipse/paho.golang/paho"
). There are
examples off this folder in paho/cmd
and extensions in paho/extensions
.
autopaho
(import "github.com/eclipse/paho.golang/autopaho"
) is a fairly simple wrapper that automates the connection
process and will automatically reconnect should the connection drop. For many users this package will provide a simple
way to connect and publish/subscribe as well as demonstrating how to use the paho.golang/paho
.
autopaho/examples/docker
provides a full example using docker to run a publisher and subscriber (connecting to
mosquitto).
This client is designed to work with the standard Go tools. When using Go Modules import one of the packages
(e.g. import "github.com/eclipse/paho.golang/autopaho"
) and run go mod tidy
. If you wish to manually add
the library as a dependency run:
go get github.com/eclipse/paho.golang
Please report bugs by raising issues for this project in GitHub https://github.com/eclipse/paho.golang/issues.
A limited number of contributors monitor the issues section so, if you have a general question, please see the resources in the more information section for help.
We welcome bug reports, but it is important they are actionable. If we cannot replicate the problem, then it is unlikely we will be able to fix it. The information required will vary from issue to issue, but almost all bug reports would be expected to include:
go.mod
file)ClientOption
)If at all possible, please also include:
autopaho/examples/docker
) makes it relatively simple to provide a
working end-to-end example.It is important to remember that this library does not stand alone; it communicates with a server and any issues you are seeing may be due to:
When submitting an issue, please ensure that you provide sufficient details to enable us to eliminate causes outside of
this library (e.g. show that a tool like mosquitto_pub
works).
We welcome pull requests, but before your contribution can be accepted by the project, you need to create and electronically sign the Eclipse Contributor Agreement (ECA) and sign off on the Eclipse Foundation Certificate of Origin. More information is available in the Eclipse Development Resources.
Please raise an issue prior to implementing any major changes; it's better to check that the change is likely to be accepted, and discuss the design, before investing your time in it.
This client aims to implement the MQTT Version 5.,0 Specification; so, if you have questions about the protocol itself, then the spec is a good place to start.
#MQTT
in the Gophers slack is
pretty quiet but questions are generally answered quickly.There is much more information available via the MQTT community site.
The major feature missing from this library, as at release 0.12, was support for session persistence; the library effectively operated at QOS0 (QOS1/2 appeared to work, but the delivery guarantees were not honored).
This has now been rectified (as of v0.20); a major change (which, despite testing, is likely to introduce issues!).
Topic aliases are not part of the session state. This means that if messages using a topic alias are queued when the connection drops and then sent when it comes up will not have the desired impact. Possible workaround would be to detect these and cancel them all when the connection drops.
If a Client may connect to more than one server, or the same server with different ClientIDs, then the user will need to carefully manage the store (because each store is specific to one server/ClientID).
autopaho accepts a slice of servers; if using CleanStart=false
then these servers MUST be part of a cluster with shared
session state (otherwise messages will be lost).
The client effectively ignores the Session Expiry Interval
when it comes to managing state. This is unlikely to be a problem for most users because the servers CONNACK
will
include the Session Present flag, which will inform us if the session has expired (and local state will be removed at
that time).
Users may wish to clear session information to save on storage, but this is not something the library currently supports.
MQTT v5 allows both the client and server to specify how many simultaneous inflight messages they permit. This is an excellent addition to the protocol because it improves in-order delivery and can help avoid saturating network links.
This client does not enforce the Receive Maximum for messages being received from the server. This is unlikely to be an issue for most users because most servers should honour the limit (if we were checking for this situation, we would need to drop the connection if it was detected).
The client does honor the Receive Maximum received from the server (indicating how many inflight publishes the client can initiate to the server).
Calling Client.Ack()
after the connection is closed may have unpredictable results (particularly if the sessionState
is being accessed by a new connection). See issue #160.