Paho Go

https://pkg.go.dev/github.com/eclipse/paho.golang
Admin
Paho Go is an Eclipse MQTT client library for Go that implements MQTT Version 5.0 specification with...
Tokens:67,072
Snippets:799
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start Docker Environment

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho/examples/docker

Starts the publisher, subscriber, and Mosquitto server in detached mode using Docker Compose. Ensure you are in the 'cmd/docker' directory.

```bash
docker-compose up --build --detach

```

--------------------------------

### Run Test Server

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/internal/basictestserver

Starts the test server to listen for incoming client connections and process MQTT messages.

```go
func (t *TestServer) Run()
```

--------------------------------

### DefaultPinger.Run

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Starts the pinger. This function blocks until the context is cancelled or an error occurs.

```APIDOC
## DefaultPinger.Run

### Description
Starts the pinger; blocks until done (either context cancelled or error encountered).

### Method Signature
```go
func (p *DefaultPinger) Run(ctx context.Context, conn net.Conn, keepAlive uint16) error
```

### Parameters
* **ctx** (context.Context) - The context to control the pinger's lifecycle.
* **conn** (net.Conn) - The network connection to use for pinging.
* **keepAlive** (uint16) - The keep-alive interval in seconds.

### Returns
* (error) - An error if the pinger fails to run.
```

--------------------------------

### Install Eclipse Paho Go Client

Source: https://pkg.go.dev/github.com/eclipse/paho.golang

Use this command to add the library as a dependency when using Go Modules.

```bash
go get github.com/eclipse/paho.golang

```

--------------------------------

### Get UserProperty by Key

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Retrieves the first UserProperty value matching the given key. Returns an empty string if not found.

```go
func (u UserProperties) Get(key string) string
```

--------------------------------

### DefaultPinger Run Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Starts the pinger's operation. This method blocks until the context is cancelled or an error occurs. It manages the keep-alive mechanism.

```go
func (p *DefaultPinger) Run(ctx context.Context, conn net.Conn, keepAlive uint16) error
```

--------------------------------

### Client Configuration and Initialization

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Provides details on how to create and configure a new MQTT client instance using `NewClient`.

```APIDOC
## NewClient

### Description
Initializes and returns a new MQTT client instance with the provided configuration.

### Method
`func NewClient(conf ClientConfig) *Client`

### Parameters
* `conf` (*ClientConfig*) - Required - The configuration settings for the client, including network details and authentication.

### Response
* `*Client` - A pointer to the newly created MQTT client instance.
```

--------------------------------

### Get Packet Subscribe from Paho Subscribe

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Returns a packets library Subscribe from the paho Subscribe on which it is called.

```go
func (s *Subscribe) Packet() *packets.Subscribe
```

--------------------------------

### Basic MQTT v5 Client Connection and Publishing

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho

Demonstrates setting up an MQTT v5 client with automatic reconnection, session management, and message publishing. Use this for general-purpose MQTT client applications requiring robust connection handling.

```go
func main() {
	// App will run until cancelled by user (e.g. ctrl-c)
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	// We will connect to the Eclipse test server (note that you may see messages that other users publish)
	u, err := url.Parse("mqtt://mqtt.eclipseprojects.io:1883")
	if err != nil {
		panic(err)
	}

	cliCfg := autopaho.ClientConfig{
		ServerUrls: []*url.URL{u},
		KeepAlive:  20, // Keepalive message should be sent every 20 seconds
		// CleanStartOnInitialConnection defaults to false. Setting this to true will clear the session on the first connection.
		CleanStartOnInitialConnection: false,
		// SessionExpiryInterval - Seconds that a session will survive after disconnection.
		// It is important to set this because otherwise, any queued messages will be lost if the connection drops and
		// the server will not queue messages while it is down. The specific setting will depend upon your needs
		// (60 = 1 minute, 3600 = 1 hour, 86400 = one day, 0xFFFFFFFE = 136 years, 0xFFFFFFFF = don't expire)
		SessionExpiryInterval: 60,
		OnConnectionUp: func(cm *autopaho.ConnectionManager, connAck *paho.Connack) {
			fmt.Println("mqtt connection up")
			// Subscribing in the OnConnectionUp callback is recommended (ensures the subscription is reestablished if
			// the connection drops)
			if _, err := cm.Subscribe(context.Background(), &paho.Subscribe{
				Subscriptions: []paho.SubscribeOptions{
					{Topic: topic, QoS: 1},
				},
			}); err != nil {
				fmt.Printf("failed to subscribe (%s). This is likely to mean no messages will be received.", err)
			}
			fmt.Println("mqtt subscription made")
		},
		OnConnectError: func(err error) { fmt.Printf("error whilst attempting connection: %s\n", err) },
		// eclipse/paho.golang/paho provides base mqtt functionality, the below config will be passed in for each connection
		ClientConfig: paho.ClientConfig{
			// If you are using QOS 1/2, then it's important to specify a client id (which must be unique)
			ClientID: clientID,
			// OnPublishReceived is a slice of functions that will be called when a message is received.
			// You can write the function(s) yourself or use the supplied Router
			OnPublishReceived: []func(paho.PublishReceived) (bool, error){
				func(pr paho.PublishReceived) (bool, error) {
					fmt.Printf("received message on topic %s; body: %s (retain: %t)\n", pr.Packet.Topic, pr.Packet.Payload, pr.Packet.Retain)
					return true, nil
				}},
			OnClientError: func(err error) { fmt.Printf("client error: %s\n", err) },
			OnServerDisconnect: func(d *paho.Disconnect) {
				if d.Properties != nil {
					fmt.Printf("server requested disconnect: %s\n", d.Properties.ReasonString)
				} else {
					fmt.Printf("server requested disconnect; reason code: %d\n", d.ReasonCode)
				}
			},
		},
	}

	c, err := autopaho.NewConnection(ctx, cliCfg) // starts process; will reconnect until context cancelled
	if err != nil {
		panic(err)
	}
	// Wait for the connection to come up
	if err = c.AwaitConnection(ctx); err != nil {
		panic(err)
	}

	ticker := time.NewTicker(time.Second)
	msgCount := 0
	defer ticker.Stop()
	for {
		select {
		case <-ticker.C:
			msgCount++
			// Publish a test message (use PublishViaQueue if you don't want to wait for a response)
			if _, err = c.Publish(ctx, &paho.Publish{
				QoS:     1,
				Topic:   topic,
				Payload: []byte("TestMessage: " + strconv.Itoa(msgCount)) ,
			}); err != nil {
				if ctx.Err() == nil {
					panic(err) // Publish will exit when context cancelled or if something went wrong
				}
			}
			continue
		case <-ctx.Done():
		}
		break
	}

	fmt.Println("signal caught - exiting")
	<-c.Done() // Wait for clean shutdown (cancelling the context triggered the shutdown)
}

```

--------------------------------

### Create a Standard Router

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho/examples/router

Initializes a new standard router instance. This is the first step in setting up message routing.

```go
router := paho.NewStandardRouter()

```

--------------------------------

### Get Packet Suback from Paho Suback

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Returns a packets library Suback from the paho Suback on which it is called.

```go
func (s *Suback) Packet() *packets.Suback
```

--------------------------------

### Get

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho/store/file

Retrieves a packet from the store using its packet ID. The caller is responsible for closing the returned io.ReadCloser.

```APIDOC
## Get

### Description

Retrieves the packet data corresponding to the specified packet ID. The caller must close the returned `io.ReadCloser` to release resources.

### Method Signature

```go
func (s *Store) Get(packetID uint16) (io.ReadCloser, error)
```

### Parameters

*   **packetID** (uint16) - The ID of the packet to retrieve.

### Returns

*   **io.ReadCloser** - An interface for reading the packet data. Must be closed by the caller.
*   **error** - An error if the packet cannot be retrieved.
```

--------------------------------

### Get Reader for Queue Entry

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho/queue/memory

Implements the Entry.Reader method, providing an io.Reader for the first item in the queue.

```go
func (q *Queue) Reader() (io.Reader, error)
```

--------------------------------

### Connect Method Signature

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/internal/testserver

Establishes a connection to the test server. Returns a net.Conn, a channel that closes on shutdown, and an error if connection fails.

```go
func (i *Instance) Connect(ctx context.Context) (net.Conn, chan struct{}, error)
```

--------------------------------

### Instantiate StandardRouter

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Instantiates and returns a new StandardRouter.

```go
func NewStandardRouter() *StandardRouter
```

--------------------------------

### Connect Client to Server

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Connects the client to a server using a pre-prepared Connect packet. Initiates the rest of the client if successful, otherwise returns connection failure details.

```go
func (c *Client) Connect(ctx context.Context, cp *Connect) (*Connack, error)
```

--------------------------------

### Get Client Connection

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/internal/basictestserver

ClientConn returns a net.Conn connection that can be used when creating a Paho Client instance for testing.

```go
func (t *TestServer) ClientConn() net.Conn
```

--------------------------------

### Client Creation

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Creates a new MQTT client instance with the provided configuration. Ensure the network connection is established before calling Connect().

```APIDOC
## NewClient

### Description
Creates a new default instance of an MQTT client. Returns a pointer to the new client instance.

### Method
```go
func NewClient(conf ClientConfig) *Client
```

### Parameters
* **conf** (*ClientConfig*) - The client configuration to use.
```

--------------------------------

### Get Client Shutdown Notification Channel

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Returns a channel that is closed when the client has shut down. This is only valid after a successful Connect call.

```go
func (c *Client) Done() <-chan struct{}
```

--------------------------------

### New Memory Store Constructor

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho/store/memory

Creates and returns a new instance of the `memory.Store`. This is the entry point for using the in-memory store.

```go
func New() *Store
```

--------------------------------

### Create New File Store

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho/store/file

Initializes a new file store. It performs a test write, read, and delete operation to ensure the path is usable. Note potential issues with message ordering if intervals are less than filesystem ModTime resolution.

```go
func New(path string, prefix string, extension string) (*Store, error)
```

--------------------------------

### Get Received Pubacks

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/internal/basictestserver

ReceivedPubacks returns a slice of all received MQTT PUBACK packets. This is useful for verifying acknowledgments in tests.

```go
func (t *TestServer) ReceivedPubacks() []packets.Puback
```

--------------------------------

### Create New MQTT Client

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Creates a new default MQTT client instance. The default client uses provided PingHandler, MessageID, StandardRouter, and a noop Persistence. These should be replaced before connecting.

```go
func NewClient(conf ClientConfig) *Client
```

--------------------------------

### Get Packet from Memory Store

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho/store/memory

Retrieves a packet from the memory store using its `packetID`. Returns an `io.ReadCloser` for the packet data and an error if not found.

```go
func (m *Store) Get(packetID uint16) (io.ReadCloser, error)
```

--------------------------------

### Instance Methods

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/internal/testserver

Provides methods for interacting with the test server instance, including connection, state checking, and callback configuration.

```APIDOC
## func New(logger Logger) *Instance

### Description
Creates a new instance of the test server with the provided logger.

### Parameters
#### Path Parameters
- **logger** (Logger) - Required - The logger to use for the instance.

### Response
#### Success Response (Instance)
- **Instance** (*Instance) - A pointer to the newly created Instance.

## func (i *Instance) Connect(ctx context.Context) (net.Conn, chan struct{}, error)

### Description
Establishes a connection to the test server.

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - The context for the connection attempt.

### Response
#### Success Response (net.Conn, chan struct{}, error)
- **net.Conn** - The network connection.
- **chan struct{}** - A channel that is closed when the connection is closed.
- **error** - An error if the connection fails.

## func (i *Instance) Connected() bool

### Description
Checks if the instance is currently connected.

### Response
#### Success Response (bool)
- **bool** - True if connected, false otherwise.

## func (i *Instance) SetConnectCallback(callback func(cp *packets.Connect, cap *packets.Connack))

### Description
Sets a callback function to be executed when a connection is established.

### Parameters
#### Path Parameters
- **callback** (func(cp *packets.Connect, cap *packets.Connack)) - Required - The callback function.

## func (i *Instance) SetPacketReceivedCallback(callback func(publish *packets.ControlPacket) error)

### Description
Sets a callback function to be executed when a packet is received.

### Parameters
#### Path Parameters
- **callback** (func(publish *packets.ControlPacket) error) - Required - The callback function.
```

--------------------------------

### Get Received Pubrecs

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/internal/basictestserver

ReceivedPubrecs returns a slice of all received MQTT PUBREC packets. This is useful for verifying QoS 2 message acknowledgments in tests.

```go
func (t *TestServer) ReceivedPubrecs() []packets.Pubrec
```

--------------------------------

### ClientConfig Struct

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Defines user-configurable options for the MQTT client. Defaults are provided for several options, but some must be set.

```go
type ClientConfig struct {
	ClientID string
	// Conn is the connection to broker.
	// BEWARE that most wrapped net.Conn implementations like tls.Conn are
	// not thread safe for writing. To fix, use packets.NewThreadSafeConn
	// wrapper or extend the custom net.Conn struct with sync.Locker.
	Conn net.Conn

	Session session.SessionManager

	AuthHandler Auther
	PingHandler Pinger

	// Router - new inbound messages will be passed to the `Route(*packets.Publish)` function.
	//
	// Depreciated: If a router is provided, it will now be added to the end of the OnPublishReceived
	// slice (which provides a more flexible approach to handling incoming messages).
	Router Router

	// OnPublishReceived provides a slice of callbacks; additional handlers may be added after the client has been
	// created via the AddOnPublishReceived function (Client holds a copy of the slice; OnPublishReceived will not change).
	// When a `PUBLISH` is received, the callbacks will be called in order. If a callback processes the message,
	// then it should return true. This boolean, and any errors, will be passed to subsequent handlers.
	OnPublishReceived []func(PublishReceived) (bool, error)

	PacketTimeout time.Duration
	// OnServerDisconnect is called only when a packets.DISCONNECT is received from server
	OnServerDisconnect func(*Disconnect)
	// OnClientError is for example called on net.Error. Note that this may be called multiple times and may be
	// called following a successful `Disconnect`. See autopaho.errorHandler for an example.
	OnClientError func(error)
	// PublishHook allows a user provided function to be called before
	// a Publish packet is sent allowing it to inspect or modify the
	// Publish, an example of the utility of this is provided in the
	// Topic Alias Handler extension which will automatically assign
	// and use topic alias values rather than topic strings.
	PublishHook func(*Publish)
	// EnableManualAcknowledgment is used to control the acknowledgment of packets manually.
	// BEWARE that the MQTT specs require clients to send acknowledgments in the order in which the corresponding
	// PUBLISH packets were received.
	// Consider the following scenario: the client receives packets 1,2,3,4
	// If you acknowledge 3 first, no ack is actually sent to the server but it's buffered until also 1 and 2
	// are acknowledged.
	EnableManualAcknowledgment bool
	// SendAcksInterval is used only when EnableManualAcknowledgment is true
	// it determines how often the client tries to send a batch of acknowledgments in the right order to the server.
	SendAcksInterval time.Duration
	// contains filtered or unexported fields
}
```

--------------------------------

### Get Connection Handler Shutdown Channel

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho

Returns a channel that is closed when the connection handler has shut down cleanly. Note: Does not indicate when the MQTT client itself has fully shut down.

```go
func (c *ConnectionManager) Done() <-chan struct{}
```

--------------------------------

### Connect InitWillProperties Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Initializes the Will properties of a Connect packet using a lower-level Properties struct. This is used to configure the Will message properties within a Connect packet.

```go
func (c *Connect) InitWillProperties(p *packets.Properties)
```

--------------------------------

### Packet Interface Definition in Paho Go

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho/session

Defines the `Packet` interface for MQTT packets, including methods to set and get the packet identifier and write the packet to a writer.

```go
type Packet interface {
	SetIdentifier(uint16) // Sets the packet identifier
	Type() byte           // Gets the packet type
	WriteTo(io.Writer) (int64, error)
}
```

--------------------------------

### ConnectionManager.Authenticate

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho

Initiates a reauthentication of credentials with the server. It sends the initial Auth packet to start the reauthentication and relies on the client AuthHandler for further requests until a successful Auth packet or a Disconnect is received.

```APIDOC
## Authenticate

### Description
Initiates a reauthentication of credentials with the server. This function sends the initial Auth packet to start the reauthentication then relies on the client AuthHandler managing any further requests from the server until either a successful Auth packet is passed back, or a Disconnect is received.

### Method
*Not specified, likely internal to ConnectionManager*

### Endpoint
*Not applicable*

### Parameters
*Not applicable*

### Request Example
*Not applicable*

### Response
*Not applicable*
```

--------------------------------

### Register and Unregister Routes

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho/examples/router

Demonstrates how to register a default handler for unmatched topics and a specific handler for a topic pattern. It also shows how to unregister a previously registered handler.

```go
router.DefaultHandler(func(p *paho.Publish) { fmt.Printf("defaulthandler received message with topic: %s\n", p.Topic) })
router.RegisterHandler("test/test/#", func(p *paho.Publish) { fmt.Printf("test/test/# received message with topic: %s\n", p.Topic) })
router.UnregisterHandler("test/test/#")

```

--------------------------------

### Connect InitProperties Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Initializes the properties of a Connect packet using a lower-level Properties struct. This function helps in setting up Connect packet properties from external sources.

```go
func (c *Connect) InitProperties(p *packets.Properties)
```

--------------------------------

### Backoff Type Definition

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho

Defines a function type for computing backoff durations based on the connection attempt number. The attempt count starts at 0 for the delay before the first connection attempt.

```go
type Backoff func(attempt int) time.Duration
```

--------------------------------

### New TestServer Constructor

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/internal/basictestserver

Creates and returns a new instance of TestServer, requiring a Logger implementation for its operations.

```go
func New(logger Logger) *TestServer
```

--------------------------------

### New Exponential Backoff Function

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho

Creates a backoff strategy that generates a random duration within a range. The range starts from a minimum delay and extends up to a maximum delay that increases exponentially with each attempt, capped by a global maximum.

```go
func NewExponentialBackoff(
	minDelay time.Duration,
	maxDelay time.Duration,
	initialMaxDelay time.Duration,
	factor float32,
) Backoff
```

--------------------------------

### Authenticate

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Initiates a reauthentication of credentials with the server. This function sends the initial Auth packet to start the reauthentication then relies on the client AuthHandler managing any further requests from the server until either a successful Auth packet is passed back, or a Disconnect is received.

```APIDOC
## Authenticate

### Description
Initiates a reauthentication of credentials with the server. This function sends the initial Auth packet to start the reauthentication then relies on the client AuthHandler managing any further requests from the server until either a successful Auth packet is passed back, or a Disconnect is received.

### Method
`func (*Client) Authenticate(ctx context.Context, a *Auth) (*AuthResponse, error)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```

--------------------------------

### New Function Signature

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/internal/testserver

Creates a new instance of the simulator. Requires a Logger implementation.

```go
func New(logger Logger) *Instance
```

--------------------------------

### Publish.InitProperties Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Initializes the properties of a Publish struct using a lower-level Properties struct.

```go
func (p *Publish) InitProperties(prop *packets.Properties)

```

--------------------------------

### New

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho/store/file

Creates a new file-based store. It performs a test write, read, and delete operation to ensure the provided path is usable. Note that message order is maintained using file modification times, which might cause issues if messages are sent faster than the file system's modification time resolution.

```APIDOC
## New

### Description

Creates a new file store. A test write, read, and delete operation is performed to verify the usability of the provided path. The order of messages is maintained using file modification times, which may lead to issues if the interval between messages is less than the file system's modification time resolution.

### Function Signature

```go
func New(path string, prefix string, extension string) (*Store, error)
```

### Parameters

*   **path** (string) - The directory path where the store files will be created.
*   **prefix** (string) - A prefix for the temporary files used by the store.
*   **extension** (string) - The file extension for the store files.

### Returns

*   **(*Store, error)** - A pointer to the newly created Store object and an error if the store could not be created.
```

--------------------------------

### New Queue Constructor

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho/queue/file

Creates a new file-based queue. It performs a test write/read/delete to ensure the path is usable. Note that file system ModTime resolution might cause issues if messages are enqueued too rapidly.

```go
func New(path string, prefix string, extension string) (*Queue, error)
```

--------------------------------

### Publish.String Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Provides a string representation of the Publish struct.

```go
func (p *Publish) String() string

```

--------------------------------

### SubOptions Pack Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/packets

Implements the Pack method for SubOptions. Note that this does not pack the topic.

```go
func (s *SubOptions) Pack() byte
```

--------------------------------

### SubOptions

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/packets

Handles MQTT subscription options, including packing and unpacking.

```APIDOC
## SubOptions

### Description
Represents and handles MQTT subscription options, such as QoS.

### Methods

*   **Pack() byte**: Packs the subscription options into a byte.
*   **Unpack(r *bytes.Buffer) error**: Unpacks subscription options from a bytes.Buffer.

```

--------------------------------

### Puback Reason Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/packets

Returns a string representation of the Puback's ReasonCode.

```go
func (p *Puback) Reason() string
```

--------------------------------

### Instantiate StandardRouter with Default Handler

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Instantiates a StandardRouter with a default handler set for convenience.

```go
func NewStandardRouterWithDefault(h MessageHandler) *StandardRouter
```

--------------------------------

### Client Connection

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Details the process of establishing a connection to an MQTT broker using the `Connect` method.

```APIDOC
## Connect

### Description
Establishes a connection to the MQTT broker as defined in the client's configuration. This method should be called before any other client operations that require an active connection.

### Method
`func (c *Client) Connect(ctx context.Context, cp *Connect) (*Connack, error)`

### Parameters
* `ctx` (*context.Context*) - Required - The context for the connection attempt, allowing for cancellation and timeouts.
* `cp` (*Connect*) - Required - The `Connect` struct containing connection details and options.

### Response
* `*Connack` - A pointer to the `Connack` struct, which contains information about the connection acknowledgment from the broker.
* `error` - An error if the connection fails.
```

--------------------------------

### Connect String Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/packets

Provides a string representation for the Connect struct.

```go
func (c *Connect) String() string
```

--------------------------------

### Connect PackFlags Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/packets

Packs the Connect flags into a single byte representation for MQTT wire format.

```go
func (c *Connect) PackFlags() (f byte)
```

--------------------------------

### Auth.String Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/packets

Returns a string representation of the Auth packet.

```go
func (a *Auth) String() string
```

--------------------------------

### Pubcomp Reason Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/packets

Returns a string representation of the Pubcomp's ReasonCode.

```go
func (p *Pubcomp) Reason() string
```

--------------------------------

### Create New Handler

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho/extensions/rpc

Instantiates a new Handler for the Paho MQTT v5 client. Requires a context and a Paho client instance.

```go
func NewHandler(ctx context.Context, c *paho.Client) (*Handler, error)
```

--------------------------------

### Client Configuration Structure

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho

Defines the configuration for an MQTT client, including server URLs, TLS settings, keep-alive intervals, session management, and reconnection strategies. This structure is central to setting up and customizing client behavior.

```go
type ClientConfig struct {
	ServerUrls                    []*url.URL  // URL(s) for the MQTT server (schemes supported include 'mqtt' and 'tls')
	TlsCfg                        *tls.Config // Configuration used when connecting using TLS
	KeepAlive                     uint16      // Keepalive period in seconds (the maximum time interval that is permitted to elapse between the point at which the Client finishes transmitting one MQTT Control Packet and the point it starts sending the next)
	CleanStartOnInitialConnection bool        //  Clean Start flag, if true, existing session information will be cleared on the first connection (it will be false for subsequent connections)
	SessionExpiryInterval         uint32      // Session Expiry Interval in seconds (if 0 the Session ends when the Network Connection is closed)

	// Deprecated: ConnectRetryDelay is deprecated and its functionality is replaced by ReconnectBackoff.
	ConnectRetryDelay time.Duration           // How long to wait between connection attempts (defaults to 10s)
	ReconnectBackoff  func(int) time.Duration // How long to wait after failed connection attempt N (defaults to 10s)
	ConnectTimeout    time.Duration           // How long to wait for the connection process to complete (defaults to 10s)
	WebSocketCfg      *WebSocketConfig        // Enables customisation of the websocket connection

	Queue queue.Queue // Used to queue up publish messages (if nil an error will be returned if publish could not be transmitted)

	// Depreciated: Use ServerUrls instead (this will be used if ServerUrls is empty). Will be removed in a future release.
	BrokerUrls []*url.URL

	// AttemptConnection, if provided, will be called to establish a network connection.
	// The returned `conn` must support thread safe writing; most wrapped net.Conn implementations like tls.Conn
	// are not thread safe for writing.
	// To fix, use packets.NewThreadSafeConn wrapper or extend the custom net.Conn struct with sync.Locker.
	AttemptConnection func(context.Context, ClientConfig, *url.URL) (net.Conn, error)

	OnConnectionUp   func(*ConnectionManager, *paho.Connack) // Called when a connection is made (including reconnection). Connection Manager passed to simplify subscriptions. Supplied function must not block.
	OnConnectionDown func() bool                             // Only called after the connection that resulted in OnConnectionUp is dropped. Returning false will cause autopaho to cease attempting to connect. Supplied function must not block.
	OnConnectError   func(error)                             // Called (within a goroutine) whenever a connection attempt fails. Will wrap autopaho.ConnackError on server deny.

```

--------------------------------

### Connect

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Connects the client to a server. It presumes that the Client instance already has a working network connection. The function takes a pre-prepared Connect packet, and uses that to establish an MQTT connection. Assuming the connection completes successfully, the rest of the client is initiated and the Connack returned. Otherwise, the failure Connack (if there is one) is returned along with an error indicating the reason for the failure to connect.

```APIDOC
## Connect

### Description
Connects the client to a server. It presumes that the Client instance already has a working network connection. The function takes a pre-prepared Connect packet, and uses that to establish an MQTT connection. Assuming the connection completes successfully, the rest of the client is initiated and the Connack returned. Otherwise, the failure Connack (if there is one) is returned along with an error indicating the reason for the failure to connect.

### Method
`func (*Client) Connect(ctx context.Context, cp *Connect) (*Connack, error)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```

--------------------------------

### Connect.InitWillProperties

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Initializes the Will properties of a Connect struct using a lower-level Properties struct.

```APIDOC
## Connect.InitWillProperties

### Description
Initializes the Will properties of a Connect struct using a lower-level Properties struct.

### Method Signature
```go
func (c *Connect) InitWillProperties(p *packets.Properties)
```

### Parameters
* **p** (*packets.Properties) - The lower-level Properties struct to use for initialization.
```

--------------------------------

### Subscribing to Topics

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Details how to subscribe to topics to receive messages from the MQTT broker using the `Subscribe` method.

```APIDOC
## Subscribe

### Description
Subscribes the client to one or more topics on the MQTT broker. This allows the client to receive messages published to those topics.

### Method
`func (c *Client) Subscribe(ctx context.Context, s *Subscribe) (*Suback, error)`

### Parameters
* `ctx` (*context.Context*) - Required - The context for the subscribe operation, allowing for cancellation.
* `s` (*Subscribe*) - Required - The `Subscribe` struct containing the topics to subscribe to and their desired QoS levels.

### Response
* `*Suback` - A pointer to the `Suback` struct, which contains the results of the subscription request for each topic.
* `error` - An error if the subscribe operation fails.
```

--------------------------------

### NewConnection Function

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho

Creates a connection manager and begins the connection process. It will retry until the provided context is cancelled.

```go
func NewConnection(ctx context.Context, cfg ClientConfig) (*ConnectionManager, error) {
	// Implementation omitted for brevity
	return nil, nil
}
```

--------------------------------

### ControlPacket String Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/packets

Implements fmt.Stringer for debugging purposes.

```go
func (c *ControlPacket) String() string
```

--------------------------------

### TestLog Printf Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho/log

Formats and records log messages using fmt.Printf semantics. Output is associated with the test and only shown on failure.

```go
func (t *TestLog) Printf(format string, v ...interface{})
```

--------------------------------

### MQTT Authentication Reason Codes

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/packets

Constants for authentication success and continuation.

```go
const (
	AuthSuccess                = 0x00
	AuthContinueAuthentication = 0x18
	AuthReauthenticate         = 0x19
)
```

--------------------------------

### Store Methods

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho/store/memory

This section details the methods available on the memory store.

```APIDOC
## func New() *Store

### Description
Creates a new in-memory store.

### Signature
```go
func New() *Store
```

## func (m *Store) Delete(id uint16) error

### Description
Removes the message with the specified store ID from the memory store.

### Signature
```go
func (m *Store) Delete(id uint16) error
```

## func (m *Store) Get(packetID uint16) (io.ReadCloser, error)

### Description
Retrieves a packet from the memory store using its packet ID.

### Signature
```go
func (m *Store) Get(packetID uint16) (io.ReadCloser, error)
```

## func (m *Store) List() ([]uint16, error)

### Description
Returns a list of all packet IDs currently stored in the memory store, in the order they were added.

### Signature
```go
func (m *Store) List() ([]uint16, error)
```

## func (m *Store) Put(packetID uint16, packetType byte, w io.WriterTo) error

### Description
Stores a packet in the memory store. It takes the packet ID, packet type, and a writer for the packet content.

### Signature
```go
func (m *Store) Put(packetID uint16, packetType byte, w io.WriterTo) error
```

## func (m *Store) Quarantine(id uint16) error

### Description
Marks a packet as quarantined. This is typically called when a corrupt packet is detected. The packet will be deleted from the store.

### Signature
```go
func (m *Store) Quarantine(id uint16) error
```

## func (m *Store) Reset() error

### Description
Clears the entire memory store, removing all stored messages.

### Signature
```go
func (m *Store) Reset() error
```

## func (m *Store) String() string

### Description
Returns a string representation of the memory store's content, primarily for debugging purposes.

### Signature
```go
func (m *Store) String() string
```
```

--------------------------------

### ConnectionManager.NewConnection

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho

Initializes a new MQTT connection manager with the provided client configuration and context. It returns a pointer to the ConnectionManager and an error if the connection fails.

```APIDOC
## NewConnection

### Description
Initializes a new MQTT connection manager with the provided client configuration and context. It returns a pointer to the ConnectionManager and an error if the connection fails.

### Method
`NewConnection`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **ctx** (context.Context) - Required - The context for the connection.
* **cfg** (ClientConfig) - Required - The client configuration for the connection.

### Request Example
```go
conn, err := NewConnection(context.Background(), clientConfig)
```

### Response
#### Success Response (200)
* **ConnectionManager** (*ConnectionManager) - A pointer to the initialized ConnectionManager.
* **error** (error) - An error if the connection could not be established.

#### Response Example
```go
// Successful connection
connManager, err := NewConnection(ctx, cfg)

// Failed connection
connManager, err := NewConnection(ctx, cfg)
if err != nil {
    // handle error
}
```
```

--------------------------------

### PublishWithOptions

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Sends a publication to the MQTT server with options to customize its behavior. It is passed a pre-prepared Publish packet and, by default, blocks waiting for the appropriate response, or for the timeout to fire. A PublishResponse is returned, which is relevant for QOS1+. For QOS0, a default success response is returned. Note that a message may still be delivered even if Publish times out (once the message is part of the session state, it may even be delivered following an application restart). Warning: Publish may outlive the connection when QOS1+ (managed in `session_state`).

```APIDOC
## PublishWithOptions

### Description
Sends a publication to the MQTT server (with options to customise its behaviour). It is passed a pre-prepared Publish packet and, by default, blocks waiting for the appropriate response, or for the timeout to fire. A PublishResponse is returned, which is relevant for QOS1+. For QOS0, a default success response is returned. Note that a message may still be delivered even if Publish times out (once the message is part of the session state, it may even be delivered following an application restart). Warning: Publish may outlive the connection when QOS1+ (managed in `session_state`).

### Method
`func (*Client) PublishWithOptions(ctx context.Context, p *Publish, o PublishOptions) (*PublishResponse, error)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```

--------------------------------

### Subscribe to MQTT Topics

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho

Sends a Subscription request to the MQTT server, blocking until a Suback response is received or a timeout occurs.

```go
func (c *ConnectionManager) Subscribe(ctx context.Context, s *paho.Subscribe) (*paho.Suback, error)
```

--------------------------------

### Instance Struct Definition

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/internal/testserver

Defines the structure for the test server instance. Note that many variables are not mutex protected as they are private and only accessed from one goroutine.

```go
type Instance struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### MQTT Client Structure

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Represents an MQTT client instance. Note that client.Conn must be set to a connected net.Conn before calling Connect().

```go
type Client struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### TestLog Println Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho/log

Prints a line of arguments to the test log. Output is associated with the test and only shown on failure.

```go
func (t *TestLog) Println(v ...interface{})
```

--------------------------------

### NewDefaultPinger Constructor

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Creates and returns a new instance of the DefaultPinger. This is the entry point for using the default pinger implementation.

```go
func NewDefaultPinger() *DefaultPinger
```

--------------------------------

### NewConnection

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho

Creates a connection manager and begins the connection process. It will retry until the context is cancelled.

```APIDOC
## NewConnection

### Description
Creates a connection manager and begins the connection process (will retry until the context is cancelled).

### Method
func NewConnection(ctx context.Context, cfg ClientConfig) (*ConnectionManager, error)
```

--------------------------------

### StateInfo Constructor

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/internal/testserver

Provides a constructor for creating a new StateInfo object.

```APIDOC
## func NewStateInfo(sent *packets.ControlPacket, qos byte, topic string, payload []byte) *StateInfo

### Description
Creates a new StateInfo object.

### Parameters
#### Path Parameters
- **sent** (*packets.ControlPacket) - Required - The control packet that was sent.
- **qos** (byte) - Required - The quality of service level.
- **topic** (string) - Required - The topic of the message.
- **payload** ([]byte) - Required - The payload of the message.

### Response
#### Success Response (StateInfo)
- **StateInfo** (*StateInfo) - A pointer to the newly created StateInfo object.
```

--------------------------------

### Create New State with Storers

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho/session/state

New creates a new state manager that persists session information using the provided client and server storers.

```go
func New(client storer, server storer) *State
```

--------------------------------

### NewHandler

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho/extensions/rpc

Creates and initializes a new RPC Handler.

```APIDOC
## NewHandler

### Description
Creates and initializes a new RPC Handler with the provided options. This function is used to set up the RPC request/response mechanism for the MQTT client.

### Method
func NewHandler(ctx context.Context, opts HandlerOpts) (*Handler, error)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **opts** (HandlerOpts) - Required - Configuration options for the handler, including connection manager, router, response topic format, and client ID.
  * **Conn** (*autopaho.ConnectionManager) - Required - The MQTT connection manager.
  * **Router** (paho.Router) - Required - The MQTT message router.
  * **ResponseTopicFmt** (string) - Required - A format string for constructing response topics.
  * **ClientID** (string) - Required - The client identifier.

### Request Example
```go
// Assuming 'connManager' is an initialized *autopaho.ConnectionManager and 'router' is a paho.Router
options := rpc.HandlerOpts{
    Conn:             connManager,
    Router:           router,
    ResponseTopicFmt: "rpc/response/%s",
    ClientID:         "my-rpc-client",
}

handler, err := rpc.NewHandler(ctx, options)
if err != nil {
    // Handle error
}
// Use the initialized 'handler'
```

### Response
#### Success Response
* **Handler** (*Handler) - A pointer to the newly created RPC Handler.

#### Response Example
```go
// A pointer to an initialized Handler struct
// Example: &rpc.Handler{...}
```

#### Error Response
* **err** (error) - An error encountered during handler initialization.
```

--------------------------------

### HandlerOpts Struct Definition

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho/extensions/rpc

Defines the options for configuring an RPC Handler. Includes connection manager, router, response topic format, and client ID.

```go
type HandlerOpts struct {
	Conn             *autopaho.ConnectionManager
	Router           paho.Router
	ResponseTopicFmt string
	ClientID         string
}
```

--------------------------------

### GetAll UserProperties by Key

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Retrieves all UserProperty values matching the given key. Returns a nil slice if none were found.

```go
func (u UserProperties) GetAll(key string) []string
```

--------------------------------

### Helper Function: Uint32

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Returns a pointer to a uint32 with the given uint32 value.

```go
func Uint32(u uint32) *uint32
```

--------------------------------

### Properties

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/packets

Handles MQTT properties, including packing, unpacking, and string representation.

```APIDOC
## Properties

### Description
Represents and handles MQTT properties, which can be included in various control packets.

### Methods

*   **Pack(p byte) []byte**: Packs properties into a byte slice.
*   **PackBuf(p byte) *bytes.Buffer**: Packs properties into a bytes.Buffer.
*   **String() string**: Returns a string representation of the properties.
*   **Unpack(r *bytes.Buffer, p byte) error**: Unpacks properties from a bytes.Buffer.

```

--------------------------------

### Pubrec Reason Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/packets

Returns a string representation of the Pubrec's ReasonCode.

```go
func (p *Pubrec) Reason() string
```

--------------------------------

### Publish Message with Options

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Sends a publication to the MQTT server with customizable options. By default, it blocks waiting for a response or timeout. Messages may still be delivered after timeout or connection loss.

```go
func (c *Client) PublishWithOptions(ctx context.Context, p *Publish, o PublishOptions) (*PublishResponse, error)
```

--------------------------------

### Define File Store Structure

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho/store/file

Defines the structure for the file store, including mutex for synchronization and internal fields.

```go
type Store struct {
	// server store - holds packets where the message ID was generated on the server
	sync.Mutex // Is this needed?
	// contains filtered or unexported fields
}
```

--------------------------------

### Await MQTT Connection

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho

Waits for the MQTT connection to be established or the context to be cancelled. Returns an error only if the context is cancelled.

```go
func (c *ConnectionManager) AwaitConnection(ctx context.Context) error
```

--------------------------------

### UserProperties.Get

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Returns the first entry in UserProperties matching the key, or an empty string if not found.

```APIDOC
## UserProperties.Get

### Description
Get returns the first entry in the UserProperties that matches key, or an empty string if the key is not found. Note that it is permitted to have multiple entries with the same key, use GetAll if it is expected to have multiple matches.

### Method Signature
```go
func (u UserProperties) Get(key string) string
```
```

--------------------------------

### Helper Functions

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Utility functions for converting basic data types to pointers, useful for setting optional fields in MQTT packets.

```APIDOC
## BoolToByte

### Description
Converts a boolean value to a pointer to a byte (1 for true, 0 for false).

### Method
```go
func BoolToByte(b bool) *byte
```

### Parameters
* **b** (*bool*) - The boolean value to convert.
```

```APIDOC
## Byte

### Description
Returns a pointer to a byte with the given value.

### Method
```go
func Byte(b byte) *byte
```

### Parameters
* **b** (*byte*) - The byte value.
```

```APIDOC
## Uint16

### Description
Returns a pointer to a uint16 with the given value.

### Method
```go
func Uint16(u uint16) *uint16
```

### Parameters
* **u** (*uint16*) - The uint16 value to convert.
```

```APIDOC
## Uint32

### Description
Returns a pointer to a uint32 with the given value.

### Method
```go
func Uint32(u uint32) *uint32
```

### Parameters
* **u** (*uint32*) - The uint32 value to convert.
```

--------------------------------

### SubOptions Unpack Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/packets

Implements the Unpack method for SubOptions. Note that this does not unpack the topic.

```go
func (s *SubOptions) Unpack(r *bytes.Buffer) error
```

--------------------------------

### Publish MQTT Message via Queue

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho

Sends a publication to the MQTT server using a queue (defaulting to memory-based). Suitable for unreliable network conditions, with background delivery and no status updates.

```go
func (c *ConnectionManager) PublishViaQueue(ctx context.Context, p *QueuePublish) error
```

--------------------------------

### Auth Packet InitProperties

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Initializes the properties of an Auth packet using a lower-level Properties struct.

```go
func (a *Auth) InitProperties(p *packets.Properties)
```

--------------------------------

### Helper Function: Byte

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Returns a pointer to a byte with the given byte value.

```go
func Byte(b byte) *byte
```

--------------------------------

### New Memory Queue

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/autopaho/queue/memory

Creates and returns a new instance of a memory-based queue.

```go
func New() *Queue
```

--------------------------------

### Connect.InitProperties

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/paho

Initializes the properties of a Connect struct using a lower-level Properties struct.

```APIDOC
## Connect.InitProperties

### Description
Initializes the properties of a Connect struct using a lower-level Properties struct.

### Method Signature
```go
func (c *Connect) InitProperties(p *packets.Properties)
```

### Parameters
* **p** (*packets.Properties) - The lower-level Properties struct to use for initialization.
```

--------------------------------

### SubOptions Struct Definition

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/packets

Represents the options for a subscription, including topic, QoS, and retain settings.

```go
type SubOptions struct {
	Topic             string
	QoS               byte
	RetainHandling    byte
	NoLocal           bool
	RetainAsPublished bool
}
```

--------------------------------

### Publish ToControlPacket Method

Source: https://pkg.go.dev/github.com/eclipse/paho.golang/packets

Converts a Publish packet to a ControlPacket type.

```go
func (p *Publish) ToControlPacket() *ControlPacket
```
Tokens:
Raw