# Send Your First Message (/sdks/ruby/tutorials/first-message)



This is your first hands-on lesson with the Ruby SDK: create a client, send an event, and receive it. Make sure you have the SDK installed (see the [Ruby SDK overview](/sdks/ruby)).

## Create a Client [#create-a-client]

The SDK provides three client classes, each targeting a different messaging pattern:

```ruby title="main.rb"
require 'kubemq'

# Pub/Sub client — events and events store
pubsub = KubeMQ::PubSubClient.new(
  address: "localhost:50000",
  client_id: "my-app"
)

# Queues client — guaranteed delivery
queues = KubeMQ::QueuesClient.new(
  address: "localhost:50000",
  client_id: "my-app"
)

# CQ client — commands and queries (RPC)
cq = KubeMQ::CQClient.new(
  address: "localhost:50000",
  client_id: "my-app"
)

info = pubsub.ping
puts "Connected to KubeMQ v#{info.version}"
```

## Send Your First Event [#send-your-first-event]

```ruby title="send_event.rb"
require 'kubemq'

client = KubeMQ::PubSubClient.new(
  address: "localhost:50000",
  client_id: "my-publisher"
)

msg = KubeMQ::PubSub::EventMessage.new(
  channel: "notifications",
  body: "hello kubemq"
)
client.send_event(msg)
puts "Event sent successfully"

client.close
```

## Receive Events [#receive-events]

```ruby title="receive_events.rb"
require 'kubemq'

client = KubeMQ::PubSubClient.new(
  address: "localhost:50000",
  client_id: "my-subscriber"
)

token = KubeMQ::CancellationToken.new
sub = KubeMQ::PubSub::EventsSubscription.new(channel: "notifications")

client.subscribe_to_events(sub, cancellation_token: token) do |event|
  puts "Received: #{event.body}"
end

sleep 30
token.cancel
client.close
```

## Configuration Options [#configuration-options]

| Option             | Default                 | Description                                      |
| ------------------ | ----------------------- | ------------------------------------------------ |
| `address`          | `localhost:50000`       | KubeMQ server host:port                          |
| `client_id`        | Auto-generated          | Unique client identifier                         |
| `auth_token`       | `nil`                   | Bearer token for authentication                  |
| `tls`              | Disabled                | `TLSConfig` for TLS/mTLS                         |
| `keepalive`        | Enabled (10s ping)      | `KeepAliveConfig` for gRPC keepalive             |
| `reconnect_policy` | Enabled (1–30s backoff) | `ReconnectPolicy` for auto-reconnect             |
| `max_send_size`    | 100 MB                  | Maximum outbound message size                    |
| `max_receive_size` | 100 MB                  | Maximum inbound message size                     |
| `log_level`        | `:warn`                 | Log level (`:debug`, `:info`, `:warn`, `:error`) |
| `default_timeout`  | 30s                     | Default gRPC deadline                            |

### Global Configuration [#global-configuration]

```ruby title="config.rb"
KubeMQ.configure do |c|
  c.address = "broker.example.com:50000"
  c.auth_token = ENV["KUBEMQ_AUTH_TOKEN"]
  c.reconnect_policy.max_delay = 60.0
end

client = KubeMQ::PubSubClient.new
```

## Error Handling [#error-handling]

All SDK operations raise subclasses of `KubeMQ::Error` with structured context:

```ruby
begin
  client.send_event(msg)
rescue KubeMQ::TimeoutError => e
  retry if e.retryable?
rescue KubeMQ::ValidationError => e
  puts "Invalid input: #{e.message} — #{e.suggestion}"
rescue KubeMQ::ConnectionError => e
  puts "Connection lost: #{e.message}"
rescue KubeMQ::Error => e
  puts "#{e.class}: #{e.message} (code=#{e.code})"
end
```

## Next Steps [#next-steps]

* [Ruby SDK Reference](/sdks/ruby/reference) — full API documentation
* [Ruby SDK Examples](/sdks/ruby/how-to) — complete examples for all patterns
* [GitHub Repository](https://github.com/kubemq-io/kubemq-ruby) — source code and issues