mqttv5

An idiomatic MQTT v5 client for Go with built-in reconnects, typed payloads, durable sessions, and support for multiple brokers.

Requires Go 1.27 or later. Pre-1.0: minor releases may change the API; see stability.

• Standard-library-only core. Persistence, WebSocket transport and payload codecs are optional submodules.
• Built-in supervisor. Reconnects, session resumption, in-flight replay and re-subscription are part of every Client.
• Delivery you control. Channels, bounded queues or callbacks, with manual acknowledgements and per-subscription backpressure.
• Typed payloads and enhanced authentication. JSON or msgpack encoding, custom codecs, rotating credentials and re-authentication.
• Durable publishing. Optional file-backed queues and session stores continue publishing through outages and process restarts.
• Multiple brokers. Failover, parallel sessions and publish pools cover different connection patterns.

See the comparison with Paho, reliability guarantees, and broker conformance suite.

go get github.com/ashtonian/mqttv5

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/ashtonian/mqttv5"
)

func main() {
    ctx := context.Background()

    cli, err := mqttv5.New(
        mqttv5.WithBroker("mqtt://localhost:1883"),
        mqttv5.WithClientID("quickstart"),
    )
    if err != nil {
        log.Fatal(err)
    }
    if err := cli.Connect(ctx); err != nil {
        log.Fatal(err)
    }
    defer cli.Disconnect(ctx)

    // Reconnects, session resumption and re-subscription happen underneath.
    msgs, _, err := cli.Subscribe(ctx, []mqttv5.TopicFilter{{Topic: "sensors/#", QoS: 1}})
    if err != nil {
        log.Fatal(err)
    }

    err = cli.Publish(ctx, mqttv5.PublishOptions{Topic: "sensors/a1", QoS: 1, Payload: []byte("22.5")})
    if err != nil {
        log.Fatal(err)
    }

    m := <-msgs
    fmt.Printf("%s: %s\n", m.Topic, m.Payload)
    _ = m.Ack() // the broker gets its PUBACK once the message is acked
}

Run it against a local broker:

docker run -d -p 1883:1883 eclipse-mosquitto mosquitto -c /mosquitto-no-auth.conf
go -C examples run ./readme/quickstart

The example uses channel delivery: call Ack after processing each message. For a consumer resuming a durable session, subscribe before connecting so queued messages have a handler as soon as they arrive.

These patterns compose. See the multi-broker guide, publish pools, and recipes for bridging, regional HA, quorum writes and sharding.

Allocations per Publish call with a 1 KiB payload, measured against the same pinned mosquitto broker. QoS 0 waits for the packet to be written (PublishWaitForFlush); QoS 1/2 wait for the broker's acknowledgement. autopaho is MQTT 5; paho3 is MQTT 3.1.1.

_{allocs/op: median of 10 runs ±95% CI; recorded 2026-10-09 at 80beb93780a2.}

See the full benchmarks for decoding and delivery allocations, throughput, latency, methodology and reproduction commands.

The documentation index also covers request/response, disconnecting, optional modules and dependencies.

Apache 2.0 — see LICENSE and NOTICE. Independent, clean-room implementation of the MQTT v5.0 specification.