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).

Create a Client

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

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_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.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

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

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

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

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

Ruby SDK Reference — full API documentation
Ruby SDK Examples — complete examples for all patterns
GitHub Repository — source code and issues

Send Your First Message