Exception: KubeMQ::Error

Inherits:
StandardError
  • Object
show all
Defined in:
lib/kubemq/errors.rb

Overview

Base exception class for all KubeMQ SDK errors.

Provides structured error context including an error code, retryable flag, originating operation, channel name, and an actionable suggestion. Rescue KubeMQ::Error for generic handling or specific subclasses for targeted recovery logic.

Examples:

Generic error handling

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

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(message, code: nil, details: nil, cause: nil, operation: '', channel: nil, request_id: '', suggestion: nil, retryable: false) ⇒ Error

Creates a new KubeMQ error.

Parameters:

  • message (String) —

    human-readable error description

  • code (String, nil) (defaults to: nil) —

    error code from KubeMQ::ErrorCode

  • details (Hash, nil) (defaults to: nil) —

    additional context (default: {})

  • cause (Exception, nil) (defaults to: nil) —

    original exception that triggered this error

  • operation (String) (defaults to: '') —

    the SDK operation that failed (default: "")

  • channel (String, nil) (defaults to: nil) —

    the channel name involved

  • request_id (String) (defaults to: '') —

    request ID for correlation (default: "")

  • suggestion (String, nil) (defaults to: nil) —

    actionable suggestion for resolution

  • retryable (Boolean) (defaults to: false) —

    whether the operation may succeed on retry (default: false)



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/kubemq/errors.rb', line 50

def initialize(message, code: nil, details: nil, cause: nil, operation: '', channel: nil,
               request_id: '', suggestion: nil, retryable: false)
  super(message)
  @error_message = message
  @code = code
  @details = details || {}
  @original_error = cause
  @operation = operation
  @channel = channel
  @request_id = request_id
  @suggestion = suggestion
  @retryable = retryable
end

Instance Attribute Details

#channel ⇒ String? (readonly)

Returns the channel name involved, if applicable.

Returns:

  • (String, nil) —

    the channel name involved, if applicable



37
 
# File 'lib/kubemq/errors.rb', line 37

attr_reader :code, :details, :operation, :channel, :request_id, :suggestion

#code ⇒ String? (readonly)

Returns SDK error code from KubeMQ::ErrorCode constants.

Returns:



37
38
39
 
# File 'lib/kubemq/errors.rb', line 37

def code
  @code
end

#details ⇒ Hash (readonly)

Returns additional error context details.

Returns:

  • (Hash) —

    additional error context details



37
 
# File 'lib/kubemq/errors.rb', line 37

attr_reader :code, :details, :operation, :channel, :request_id, :suggestion

#operation ⇒ String (readonly)

Returns the operation that failed (e.g., "send_event").

Returns:

  • (String) —

    the operation that failed (e.g., "send_event")



37
 
# File 'lib/kubemq/errors.rb', line 37

attr_reader :code, :details, :operation, :channel, :request_id, :suggestion

#request_id ⇒ String (readonly)

Returns the request ID involved, if applicable.

Returns:

  • (String) —

    the request ID involved, if applicable



37
 
# File 'lib/kubemq/errors.rb', line 37

attr_reader :code, :details, :operation, :channel, :request_id, :suggestion

#suggestion ⇒ Object (readonly)

Returns the value of attribute suggestion.



37
 
# File 'lib/kubemq/errors.rb', line 37

attr_reader :code, :details, :operation, :channel, :request_id, :suggestion

Instance Method Details

#cause ⇒ Exception?

Returns the original exception that caused this error.

Returns:

  • (Exception, nil) —

    the underlying cause



67
68
69
 
# File 'lib/kubemq/errors.rb', line 67

def cause
  @original_error || super
end

#retryable? ⇒ Boolean

Returns whether this error is transient and the operation may succeed on retry.

Returns:

  • (Boolean) 


74
75
76
 
# File 'lib/kubemq/errors.rb', line 74

def retryable?
  @retryable
end

#to_s ⇒ String

Formats the error as a human-readable string including operation, channel, and suggestion when available.

Returns:

  • (String) —

    formatted error message



82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/kubemq/errors.rb', line 82

def to_s
  parts = []
  parts << if !@operation.to_s.empty? && @channel
             "#{@operation} failed on channel \"#{@channel}\": #{@error_message}"
           elsif !@operation.to_s.empty?
             "#{@operation} failed: #{@error_message}"
           else
             @error_message
           end
  parts << "  Suggestion: #{@suggestion}" if @suggestion
  parts.join("\n")
end