Module: KubeMQ

Defined in:: lib/kubemq.rb,
lib/kubemq/types.rb,
lib/kubemq/errors.rb,
lib/kubemq/version.rb,
lib/kubemq/cq/client.rb,
lib/kubemq/base_client.rb,
lib/kubemq/error_codes.rb,
lib/kubemq/server_info.rb,
lib/kubemq/channel_info.rb,
lib/kubemq/subscription.rb,
lib/kubemq/configuration.rb,
lib/kubemq/pubsub/client.rb,
lib/kubemq/queues/client.rb,
lib/kubemq/telemetry/otel.rb,
lib/kubemq/cq/query_message.rb,
lib/kubemq/cq/query_received.rb,
lib/kubemq/cq/query_response.rb,
lib/kubemq/telemetry/semconv.rb,
lib/kubemq/cancellation_token.rb,
lib/kubemq/cq/command_message.rb,
lib/kubemq/cq/command_received.rb,
lib/kubemq/cq/command_response.rb,
lib/kubemq/errors/error_mapper.rb,
lib/kubemq/pubsub/event_sender.rb,
lib/kubemq/transport/converter.rb,
lib/kubemq/pubsub/event_message.rb,
lib/kubemq/queues/queue_message.rb,
lib/kubemq/validation/validator.rb,
lib/kubemq/pubsub/event_received.rb,
lib/kubemq/queues/upstream_sender.rb,
lib/kubemq/cq/queries_subscription.rb,
lib/kubemq/transport/state_machine.rb,
lib/kubemq/cq/commands_subscription.rb,
lib/kubemq/pubsub/event_send_result.rb,
lib/kubemq/queues/queue_send_result.rb,
lib/kubemq/transport/grpc_transport.rb,
lib/kubemq/transport/message_buffer.rb,
lib/kubemq/cq/query_response_message.rb,
lib/kubemq/pubsub/event_store_result.rb,
lib/kubemq/pubsub/event_store_sender.rb,
lib/kubemq/queues/queue_poll_request.rb,
lib/kubemq/transport/channel_manager.rb,
lib/kubemq/pubsub/event_store_message.rb,
lib/kubemq/pubsub/events_subscription.rb,
lib/kubemq/queues/downstream_receiver.rb,
lib/kubemq/queues/queue_poll_response.rb,
lib/kubemq/cq/command_response_message.rb,
lib/kubemq/pubsub/event_store_received.rb,
lib/kubemq/transport/reconnect_manager.rb,
lib/kubemq/interceptors/auth_interceptor.rb,
lib/kubemq/queues/queue_message_received.rb,
lib/kubemq/interceptors/retry_interceptor.rb,
lib/kubemq/interceptors/metrics_interceptor.rb,
lib/kubemq/pubsub/events_store_subscription.rb,
lib/kubemq/interceptors/error_mapping_interceptor.rb

Overview

KubeMQ Ruby SDK — official client library for KubeMQ message broker.

Provides pub/sub events, durable events store, message queues (stream and simple APIs), and request/reply commands and queries over gRPC.

Configure globally or pass options directly to client constructors.

Examples:

Global configuration

KubeMQ.configure do |c|
  c.address = "kubemq.example.com:50000"
  c.auth_token = ENV["KUBEMQ_AUTH_TOKEN"]
end

client = KubeMQ::PubSubClient.new

Per-client configuration

client = KubeMQ::QueuesClient.new(address: "localhost:50000", client_id: "worker-1")

Defined Under Namespace

Modules: CQ, ChannelType, ConnectionState, ErrorCategory, ErrorCode, ErrorMapper, Interceptors, PubSub, Queues, RequestType, SubscribeType, Telemetry, Transport, Validator Classes: AuthenticationError, BaseClient, BufferFullError, CQClient, CancellationError, CancellationToken, ChannelError, ChannelInfo, ClientClosedError, Configuration, ConfigurationError, ConnectionError, ConnectionNotReadyError, Error, KeepAliveConfig, MessageError, PubSubClient, QueuesClient, ReconnectPolicy, ServerInfo, StreamBrokenError, Subscription, TLSConfig, TimeoutError, TransactionError, ValidationError

Constant Summary collapse

VERSION = Current version of the kubemq-ruby SDK, following Semantic Versioning.

'1.0.0'

ERROR_CLASSIFICATION = Maps each ErrorCode to its ErrorCategory and retryable flag. Each entry is [category, retryable] where category is an ErrorCategory constant and retryable is a Boolean. Returns: (Hash{String => Array(String, Boolean)}) See Also: ErrorCode ErrorCategory

{
  ErrorCode::UNAVAILABLE => [ErrorCategory::TRANSIENT, true],
  ErrorCode::ABORTED => [ErrorCategory::TRANSIENT, true],
  ErrorCode::CONNECTION_TIMEOUT => [ErrorCategory::TIMEOUT, true],
  ErrorCode::RESOURCE_EXHAUSTED => [ErrorCategory::THROTTLING, true],
  ErrorCode::AUTH_FAILED => [ErrorCategory::AUTHENTICATION, false],
  ErrorCode::PERMISSION_DENIED => [ErrorCategory::AUTHORIZATION, false],
  ErrorCode::VALIDATION_ERROR => [ErrorCategory::VALIDATION, false],
  ErrorCode::ALREADY_EXISTS => [ErrorCategory::VALIDATION, false],
  ErrorCode::OUT_OF_RANGE => [ErrorCategory::VALIDATION, false],
  ErrorCode::NOT_FOUND => [ErrorCategory::NOT_FOUND, false],
  ErrorCode::INTERNAL => [ErrorCategory::FATAL, false],
  ErrorCode::UNKNOWN => [ErrorCategory::TRANSIENT, true],
  ErrorCode::UNIMPLEMENTED => [ErrorCategory::FATAL, false],
  ErrorCode::DATA_LOSS => [ErrorCategory::FATAL, false],
  ErrorCode::CANCELLED => [ErrorCategory::CANCELLATION, false],
  ErrorCode::BUFFER_FULL => [ErrorCategory::BACKPRESSURE, false],
  ErrorCode::STREAM_BROKEN => [ErrorCategory::TRANSIENT, true],
  ErrorCode::CLIENT_CLOSED => [ErrorCategory::FATAL, false],
  ErrorCode::CONNECTION_NOT_READY => [ErrorCategory::TRANSIENT, true],
  ErrorCode::CONFIGURATION_ERROR => [ErrorCategory::VALIDATION, false],
  ErrorCode::CALLBACK_ERROR => [ErrorCategory::RUNTIME, false]
}.freeze

ERROR_SUGGESTIONS = Maps each ErrorCode to a human-readable recovery suggestion. Used by ErrorMapper to populate KubeMQ::Error#suggestion and by suggestion_for for programmatic lookup. Returns: (Hash{String => String}) See Also: KubeMQ::Error#suggestion

{
  ErrorCode::UNAVAILABLE => 'Check server connectivity and firewall rules.',
  ErrorCode::AUTH_FAILED => 'Verify auth token is valid and not expired.',
  ErrorCode::PERMISSION_DENIED => 'Verify credentials have required permissions.',
  ErrorCode::NOT_FOUND => 'Verify channel/queue exists or create it first.',
  ErrorCode::VALIDATION_ERROR => 'Check request parameters.',
  ErrorCode::ALREADY_EXISTS => 'Resource already exists.',
  ErrorCode::CONNECTION_TIMEOUT => 'Increase timeout or check server load.',
  ErrorCode::RESOURCE_EXHAUSTED => 'Reduce send rate or increase server capacity.',
  ErrorCode::BUFFER_FULL => 'Wait for connection to recover or increase buffer_size.',
  ErrorCode::STREAM_BROKEN => 'Subscriptions will attempt to reconnect automatically. Stream senders must be recreated.',
  ErrorCode::CLIENT_CLOSED => 'The client has been closed. Create a new client instance.',
  ErrorCode::INTERNAL => 'Internal server error. Check server logs.',
  ErrorCode::UNKNOWN => 'An unknown error occurred. Check server logs.',
  ErrorCode::CONFIGURATION_ERROR => 'Check client configuration: address, TLS settings, credentials.',
  ErrorCode::CANCELLED => 'The operation was cancelled.',
  ErrorCode::UNIMPLEMENTED => 'Operation not supported. Check server version.',
  ErrorCode::DATA_LOSS => 'Unrecoverable data loss. Check server storage.',
  ErrorCode::OUT_OF_RANGE => 'Check pagination parameters or sequence numbers.',
  ErrorCode::ABORTED => 'Operation aborted due to conflict. Retry may succeed.',
  ErrorCode::CONNECTION_NOT_READY => 'Wait for the client to connect or check server availability.',
  ErrorCode::CALLBACK_ERROR => 'A user callback raised an exception. Fix the callback code.'
}.freeze

Class Method Summary collapse

.classify_error(error) ⇒ Array(String, Boolean)
Classifies an error by its ErrorCode into a category and retryable flag.
.configuration ⇒ Configuration
Returns the global Configuration singleton, creating it on first access.
.configure {|config| ... } ⇒ void
Yields the global Configuration instance for modification.
.reset_configuration! ⇒ Configuration
Resets the global configuration to a fresh Configuration with defaults.
.suggestion_for(code) ⇒ String^?
Returns the recovery suggestion for a given error code.

Class Method Details

.classify_error(error) ⇒ `Array(String, Boolean)`

Classifies an error by its ErrorCode into a category and retryable flag.

Examples:

category, retryable = KubeMQ.classify_error(error)
retry if retryable

Parameters:

error (Error) —
an error with a code attribute

Returns:

(Array(String, Boolean)) —
[category, retryable] from ERROR_CLASSIFICATION; defaults to [ErrorCategory::FATAL, false] for unknown codes

# File 'lib/kubemq/error_codes.rb', line 163

def self.classify_error(error)
  return [ErrorCategory::FATAL, false] unless error.respond_to?(:code) && error.code

  ERROR_CLASSIFICATION.fetch(error.code, [ErrorCategory::FATAL, false])
end

.configuration ⇒ `Configuration`

Returns the global Configuration singleton, creating it on first access.

Returns:

(Configuration) —
the current global configuration



108
109
110

# File 'lib/kubemq.rb', line 108

def self.configuration
  @configuration ||= Configuration.new
end

.configure {|config| ... } ⇒ `void`

This method returns an undefined value.

Yields the global Configuration instance for modification.

Settings applied here act as defaults for any client created without explicit constructor arguments. Constructor arguments take precedence.

Examples:

KubeMQ.configure do |c|
  c.address = "broker.example.com:50000"
  c.reconnect_policy.max_delay = 60.0
end

Yields:

(config) —
the global configuration instance

Yield Parameters:

config (Configuration) —
mutable configuration object



101
102
103

# File 'lib/kubemq.rb', line 101

def self.configure
  yield(configuration)
end

.reset_configuration! ⇒ `Configuration`

Resets the global configuration to a fresh Configuration with defaults.

Returns:

(Configuration) —
the new default configuration



115
116
117

# File 'lib/kubemq.rb', line 115

def self.reset_configuration!
  @configuration = Configuration.new
end

.suggestion_for(code) ⇒ `String`^?

Returns the recovery suggestion for a given error code.

Examples:

KubeMQ.suggestion_for(KubeMQ::ErrorCode::UNAVAILABLE)
# => "Check server connectivity and firewall rules."

Parameters:

code (String) —
an ErrorCode constant value

Returns:

(String, nil) —
actionable suggestion, or nil if the code is unknown



178
179
180

# File 'lib/kubemq/error_codes.rb', line 178

def self.suggestion_for(code)
  ERROR_SUGGESTIONS[code]
end

Module: KubeMQ

Overview

Examples:

Global configuration

Per-client configuration

Defined Under Namespace

Constant Summary collapse

Class Method Summary collapse

Class Method Details

.classify_error(error) ⇒ Array(String, Boolean)

Examples:

.configuration ⇒ Configuration

.configure {|config| ... } ⇒ void

Examples:

.reset_configuration! ⇒ Configuration

.suggestion_for(code) ⇒ String?

Examples:

.classify_error(error) ⇒ `Array(String, Boolean)`

.configuration ⇒ `Configuration`

.configure {|config| ... } ⇒ `void`

.reset_configuration! ⇒ `Configuration`

.suggestion_for(code) ⇒ `String`^?