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



The Ruby SDK provides three client classes that inherit shared connection management from `BaseClient`.

## Client Classes [#client-classes]

| Class                  | Purpose                              |
| ---------------------- | ------------------------------------ |
| `KubeMQ::PubSubClient` | Events and events store (pub/sub)    |
| `KubeMQ::QueuesClient` | Message queues (guaranteed delivery) |
| `KubeMQ::CQClient`     | Commands and queries (RPC)           |

## Constructor [#constructor]

All three clients share the same constructor signature inherited from `BaseClient`:

```ruby
client = KubeMQ::PubSubClient.new(
  address: "localhost:50000",
  client_id: "my-app",
  auth_token: nil,
  config: nil
)
```

### Parameters [#parameters]

| Parameter    | Type            | Default             | Description                                                   |
| ------------ | --------------- | ------------------- | ------------------------------------------------------------- |
| `address`    | `String`        | `"localhost:50000"` | Broker host:port                                              |
| `client_id`  | `String`        | Auto-generated UUID | Unique client identifier                                      |
| `auth_token` | `String`        | `nil`               | Bearer token for authentication                               |
| `config`     | `Configuration` | `nil`               | Pre-built configuration object (overrides individual options) |

## Lifecycle Methods [#lifecycle-methods]

### `ping` [#ping]

Pings the KubeMQ broker and returns server information.

```ruby
info = client.ping
puts "Host: #{info.host}, Version: #{info.version}"
```

**Returns:** `ServerInfo` with `host`, `version`, and `server_up_time_seconds` attributes.

**Raises:** `ClientClosedError`, `ConnectionError`

### `close` [#close]

Closes the client and releases all resources. Idempotent — safe to call multiple times.

```ruby
client.close
puts client.closed? # => true
```

### `closed?` [#closed]

Returns whether the client has been closed.

```ruby
client.closed? # => true | false
```

## Channel Management [#channel-management]

All clients inherit these channel management methods from `BaseClient`:

### `create_channel(channel_name:, channel_type:)` [#create_channelchannel_name-channel_type]

Creates a channel on the broker.

```ruby
client.create_channel(
  channel_name: "my-channel",
  channel_type: KubeMQ::ChannelType::EVENTS
)
```

### `delete_channel(channel_name:, channel_type:)` [#delete_channelchannel_name-channel_type]

Deletes a channel from the broker.

### `list_channels(channel_type:, search: nil)` [#list_channelschannel_type-search-nil]

Lists channels of the specified type with optional name filtering.

```ruby
channels = client.list_channels(
  channel_type: KubeMQ::ChannelType::EVENTS
)
channels.each { |ch| puts ch.name }
```

**Returns:** `Array<ChannelInfo>`

### `purge_queue_channel(channel_name:)` [#purge_queue_channelchannel_name]

Purges all messages from a queue channel.

```ruby
client.purge_queue_channel(channel_name: "tasks")
```

## Convenience Methods [#convenience-methods]

Each client provides type-specific convenience methods:

### PubSubClient [#pubsubclient]

| Method                                       | Description                    |
| -------------------------------------------- | ------------------------------ |
| `create_events_channel(channel_name:)`       | Create an events channel       |
| `create_events_store_channel(channel_name:)` | Create an events store channel |
| `delete_events_channel(channel_name:)`       | Delete an events channel       |
| `delete_events_store_channel(channel_name:)` | Delete an events store channel |
| `list_events_channels(search: nil)`          | List events channels           |
| `list_events_store_channels(search: nil)`    | List events store channels     |

### QueuesClient [#queuesclient]

| Method                                 | Description             |
| -------------------------------------- | ----------------------- |
| `create_queues_channel(channel_name:)` | Create a queues channel |
| `delete_queues_channel(channel_name:)` | Delete a queues channel |
| `list_queues_channels(search: nil)`    | List queues channels    |

### CQClient [#cqclient]

| Method                                   | Description               |
| ---------------------------------------- | ------------------------- |
| `create_commands_channel(channel_name:)` | Create a commands channel |
| `create_queries_channel(channel_name:)`  | Create a queries channel  |
| `delete_commands_channel(channel_name:)` | Delete a commands channel |
| `delete_queries_channel(channel_name:)`  | Delete a queries channel  |
| `list_commands_channels(search: nil)`    | List commands channels    |
| `list_queries_channels(search: nil)`     | List queries channels     |

## Configuration [#configuration]

Use `KubeMQ::Configuration` for full control:

```ruby
config = KubeMQ::Configuration.new(
  address: "broker.example.com:50000",
  client_id: "order-service",
  auth_token: ENV["KUBEMQ_AUTH_TOKEN"],
  tls: KubeMQ::TLSConfig.new(enabled: true, ca_file: "/certs/ca.pem"),
  log_level: :info
)
client = KubeMQ::PubSubClient.new(config: config)
```

Configuration is resolved in precedence order:

1. Constructor keyword arguments
2. Global `KubeMQ.configure` block
3. Environment variables (`KUBEMQ_ADDRESS`, `KUBEMQ_AUTH_TOKEN`)
4. Built-in defaults