Error Hierarchy

All SDK errors inherit from KubeMQ::Error, which extends StandardError. Each error carries structured context for targeted recovery.

KubeMQ::Error
├── KubeMQ::ConnectionError
│   └── KubeMQ::AuthenticationError
├── KubeMQ::TimeoutError
├── KubeMQ::ValidationError
├── KubeMQ::ConfigurationError
├── KubeMQ::ChannelError
├── KubeMQ::MessageError
├── KubeMQ::TransactionError
├── KubeMQ::ClientClosedError
├── KubeMQ::ConnectionNotReadyError
├── KubeMQ::StreamBrokenError
├── KubeMQ::BufferFullError
└── KubeMQ::CancellationError

KubeMQ::Error

Base exception class with structured context.

Attribute	Type	Description
`code`	`String`	SDK error code
`details`	`Hash`	Additional error context
`operation`	`String`	The operation that failed
`channel`	`String`	Channel name involved
`request_id`	`String`	Request ID for correlation
`suggestion`	`String`	Actionable suggestion for resolution
`retryable?`	`Boolean`	Whether the operation may succeed on retry
`cause`	`Exception`	Original exception that triggered this error

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

Error Types

Error Class	Retryable	Description
`ConnectionError`	Varies	gRPC connection failed or lost
`AuthenticationError`	No	Invalid or expired auth token
`TimeoutError`	Yes	Operation exceeded deadline
`ValidationError`	No	Invalid request parameters
`ConfigurationError`	No	Invalid client configuration
`ChannelError`	Varies	Channel operation failed at broker
`MessageError`	Varies	Message send/receive failed
`TransactionError`	Varies	Queue ack/nack/requeue failed
`ClientClosedError`	No	Operation on a closed client
`ConnectionNotReadyError`	No	Transport not yet connected
`StreamBrokenError`	Yes	gRPC bidirectional stream broke
`BufferFullError`	No	Reconnect message buffer at capacity
`CancellationError`	No	Operation cancelled via `CancellationToken`

CancellationToken

Cooperative cancellation for subscriptions and long-running operations.

token = KubeMQ::CancellationToken.new

client.subscribe_to_events(sub, cancellation_token: token) do |event|
  puts event.body
end

token.cancel
token.cancelled? # => true

Method	Description
`cancel`	Signal cancellation
`cancelled?`	Check if cancelled
`wait`	Block until cancelled

ServerInfo

Returned from client.ping.

Attribute	Type	Description
`host`	`String`	Broker hostname
`version`	`String`	Broker version
`server_up_time_seconds`	`Integer`	Server uptime in seconds

ChannelInfo

Returned from client.list_channels.

Attribute	Type	Description
`name`	`String`	Channel name
`type`	`String`	Channel type
`active?`	`Boolean`	Whether the channel has active connections

Configuration Classes

TLSConfig

tls = KubeMQ::TLSConfig.new(
  enabled: true,
  cert_file: "/certs/client.pem",
  key_file: "/certs/client-key.pem",
  ca_file: "/certs/ca.pem",
  insecure_skip_verify: false
)

KeepAliveConfig

keepalive = KubeMQ::KeepAliveConfig.new(
  enabled: true,
  ping_interval_seconds: 10,
  ping_timeout_seconds: 5,
  permit_without_calls: true
)

ReconnectPolicy

policy = KubeMQ::ReconnectPolicy.new(
  enabled: true,
  base_interval: 1.0,
  multiplier: 2.0,
  max_delay: 30.0,
  jitter_percent: 0.25,
  max_attempts: 0
)

ChannelType Constants

Constant	Description
`KubeMQ::ChannelType::EVENTS`	Events channels
`KubeMQ::ChannelType::EVENTS_STORE`	Events store channels
`KubeMQ::ChannelType::QUEUES`	Queue channels
`KubeMQ::ChannelType::COMMANDS`	Command channels
`KubeMQ::ChannelType::QUERIES`	Query channels

Types & Errors