# Client (/sdks/go/reference/client)



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 [#package]

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

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

## Constructor [#constructor]

### NewClient [#newclient]

```go
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 [#lifecycle]

### Close [#close]

```go
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 [#ping]

```go
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 [#state]

```go
func (c *Client) State() ConnectionState
```

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

## Common options [#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 [#quick-usage]

```go title="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)
}
```

## See Also [#see-also]

* [Connection Examples](/sdks/go/how-to/connection/)
* Concepts
* [Go SDK Getting Started](/sdks/go)