paho.golang

Eclipse Paho MQTT Go client

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.
  • router - this should work as-is for most users in v0.20, however 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).

Quick Start

We recommend that new users begin with autopaho; this provides a simple client that should be sufficient for most use-cases.

Folder Structure

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).

Installation and Build

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

Reporting bugs

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:

• Which version of the package you are using (tag or commit - this should be in your go.mod file)
• A full, clear, description of the problem (detail what you are expecting vs what actually happens).
• Configuration information (code showing how you connect, please include all references to ClientOption)
• Server details (name and version - e.g. Mosquitto v2.0.18).

If at all possible, please also include:

• Details of your attempts to resolve the issue (what have you tried, what worked, what did not).
• A minimal, reproducible example. Providing an example is the best way to demonstrate the issue you are facing; it is important this includes all relevant information (including server configuration). Docker (see autopaho/examples/docker) makes it relatively simple to provide a working end-to-end example.
• Server logs covering the period the issue occurred.
• Application Logs (enable debug logging in the library) covering the period the issue occurred. Unless you have isolated the root cause of the issue, please include a link to a full log (including data from well before the problem arose).

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:

• Bugs in your code.
• Bugs in this library.
• The server configuration.
• Bugs in the server.
• Issues with whatever you are communicating with.

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).

Contributing

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.

More information

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.

• Stack Overflow is probably the fastest way to get an answer (but is not a discussion forum, so invest the time to ask a good question, and remember to search existing questions first).
• There is an MQTT Google Group for general questions about the MQTT protocol.
• Reddit has a less active MQTT forum but is a good option for open-ended questions.
• #MQTT in the Gophers slack is pretty quiet but questions are generally answered quickly.
• Discussion of the Paho clients takes place on the Eclipse paho-dev mailing list.

There is much more information available via the MQTT community site.

QOS1/QOS2 Implementation

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!).

Known Issues

Queued messages using Aliases

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.

Multiple Servers

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).

SessionExpiryInterval

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.

Inflight Message tracking

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).

ACK() Unpredicatable results if called after connection loss

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.