The Go SDK exposes a single Client type backed by one gRPC connection. Pass context.Context into operations for deadlines and cancellation; use functional options to configure address, TLS, auth, retries, and observability.

Package

import "github.com/kubemq-io/kubemq-go/v2"

Requires Go 1.25+. Compatible with KubeMQ server v2.2+.

Constructor

NewClient

func NewClient(ctx context.Context, op ...Option) (*Client, error)

Creates a connected client. The initial connection honors ctx; ongoing calls use their own contexts. With no options, defaults include localhost:50000, auto-generated client ID, reconnect policy, and connection timeout.

Parameters:

Name	Type	Required	Description
`ctx`	`context.Context`	Yes	Bounds the initial connection attempt
`op`	`...Option`	No	Functional options (see below)

Returns: *Client — connected client; caller must call Close().

Throws: *KubeMQError — validation, timeout, auth, or transient network errors.

Note: The client is safe for concurrent use; share one instance across goroutines rather than creating a client per request.

Lifecycle

Close

func (c *Client) Close() error

Drains in-flight work and closes the gRPC connection. After Close, methods return ErrClientClosed.

Returns: error — transport close errors if any.

Ping

func (c *Client) Ping(ctx context.Context) (*ServerInfo, error)

Health check against the broker; returns server metadata when reachable.

Returns: *ServerInfo — server identity and version fields from the broker.

State

func (c *Client) State() ConnectionState

Returns the current connection state (StateConnecting, StateReady, StateReconnecting, StateClosed).

Common options

Option	Purpose
`WithAddress(host, port)`	Broker host and gRPC port
`WithAuthToken(token)`	Bearer token authentication
`WithCredentialProvider(p)`	Dynamic token / credential refresh
`WithTLSConfig` / `WithCredentials` / `WithCertificate`	TLS client and server validation
`WithClientId(id)`	Stable client identifier
`WithConnectionTimeout(d)`	Initial connection deadline
`WithReconnectPolicy(p)`	Reconnect backoff and max attempts
`WithRetryPolicy(p)`	Unary RPC retry policy
`WithLogger(l)`	Structured logging
`WithWaitForReady(bool)`	Wait for gRPC channel ready

Quick Usage

connect.go

ctx := context.Background()
client, err := kubemq.NewClient(ctx, kubemq.WithAddress("localhost", 50000))
if err != nil {
    log.Fatal(err)
}
defer client.Close()

if _, err := client.Ping(ctx); err != nil {
    log.Fatal(err)
}

Client