Module: KubeMQ::Validator Private

Defined in:
lib/kubemq/validation/validator.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

Input validation helpers used by client methods before sending requests.

All methods raise ValidationError on invalid input with an actionable suggestion field. Called internally -- not typically used in application code.

rubocop:disable Metrics/ModuleLength -- validation helpers per message type

See Also:

Constant Summary collapse

CHANNEL_NAME_REGEX =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Permitted characters for channel names (alphanumeric, dots, hyphens, underscores, slashes, and wildcard tokens).

%r{\A[a-zA-Z0-9._\-/>*]+\z}

Class Method Summary collapse

Class Method Details

.validate_cache!(cache_key, cache_ttl) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validates cache parameters for query messages.

Parameters:

  • cache_key (String, nil) —

    the cache key (validation only applies when set)

  • cache_ttl (Numeric, nil) —

    the cache TTL in seconds

Raises:



104
105
106
107
108
109
110
 
# File 'lib/kubemq/validation/validator.rb', line 104

def validate_cache!(cache_key, cache_ttl)
  return if cache_key.nil? || cache_key.empty?
  return if cache_ttl.is_a?(Numeric) && cache_ttl.positive?

  raise ValidationError.new('cache_ttl must be > 0 when cache_key is set',
                            suggestion: 'Provide a positive cache_ttl value in seconds.')
end

.validate_channel!(channel, allow_wildcards: false) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validates a channel name for format and optional wildcard support.

Parameters:

  • channel (String) —

    the channel name to validate

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

    whether * and > are permitted

Raises:

  • (ValidationError) —

    if the channel is nil, empty, contains invalid characters, ends with a dot, or uses wildcards when disallowed



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/kubemq/validation/validator.rb', line 28

def validate_channel!(channel, allow_wildcards: false)
  if channel.nil? || channel.to_s.strip.empty?
    raise ValidationError.new('Channel name is required',
                              suggestion: 'Provide a non-empty channel name.')
  end

  channel = channel.to_s

  unless channel.match?(CHANNEL_NAME_REGEX)
    raise ValidationError.new(
      "Channel name contains invalid characters: #{channel}",
      suggestion: 'Use only alphanumeric characters, dots, hyphens, underscores, and slashes.'
    )
  end

  if channel.end_with?('.')
    raise ValidationError.new("Channel name must not end with a dot: #{channel}",
                              suggestion: 'Remove the trailing dot from the channel name.')
  end

  return if allow_wildcards

  return unless channel.include?('*') || channel.include?('>')

  raise ValidationError.new(
    "Wildcards are not allowed for this channel: #{channel}",
    suggestion: 'Use an exact channel name without wildcard characters.'
  )
end

.validate_client_id!(client_id) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validates that a client ID is present and non-empty.

Parameters:

  • client_id (String, nil) —

    the client identifier to validate

Raises:



78
79
80
81
82
83
 
# File 'lib/kubemq/validation/validator.rb', line 78

def validate_client_id!(client_id)
  return unless client_id.nil? || client_id.to_s.strip.empty?

  raise ValidationError.new('Client ID is required',
                            suggestion: 'Provide a non-empty client ID.')
end

.validate_content!(metadata, body) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validates that at least one of metadata or body is non-empty.

Parameters:

  • metadata (String, nil) —

    message metadata

  • body (String, nil) —

    message body

Raises:



64
65
66
67
68
69
70
71
 
# File 'lib/kubemq/validation/validator.rb', line 64

def validate_content!(metadata, body)
  metadata_empty = metadata.nil? || (metadata.is_a?(String) && metadata.empty?)
  body_empty = body.nil? || (body.is_a?(String) && body.empty?)
  return unless metadata_empty && body_empty

  raise ValidationError.new('Message must have non-empty metadata or body',
                            suggestion: 'Provide either metadata or body content.')
end

.validate_events_store_subscription!(start_position, start_position_value) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validates events store subscription start position and its associated value.

Parameters:

  • start_position (Integer, nil) —

    one of the EventStoreStartPosition constants

  • start_position_value (Numeric, nil) —

    sequence number, Unix timestamp, or delta seconds depending on the start position type

Raises:

  • (ValidationError) —

    if the start position is missing or the value is invalid for the chosen position type



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/kubemq/validation/validator.rb', line 138

def validate_events_store_subscription!(start_position, start_position_value)
  if start_position.nil? || start_position.zero?
    raise ValidationError.new(
      'Events Store subscription requires a start position',
      suggestion: 'Set start_position to one of: StartNewOnly(1), StartFromFirst(2), ' \
                  'StartFromLast(3), StartAtSequence(4), StartAtTime(5), StartAtTimeDelta(6).'
    )
  end

  case start_position
  when 4 # StartAtSequence
    unless start_position_value.is_a?(Numeric) && start_position_value.positive?
      raise ValidationError.new(
        "StartAtSequence requires a positive sequence value, got: #{start_position_value.inspect}",
        suggestion: 'Provide a positive sequence number.'
      )
    end
  when 5 # StartAtTime
    unless start_position_value.is_a?(Numeric) && start_position_value.positive?
      raise ValidationError.new(
        "StartAtTime requires a positive Unix timestamp, got: #{start_position_value.inspect}",
        suggestion: 'Provide a Unix timestamp in nanoseconds.'
      )
    end
  when 6 # StartAtTimeDelta
    unless start_position_value.is_a?(Numeric) && start_position_value.positive?
      raise ValidationError.new(
        "StartAtTimeDelta requires a positive delta in seconds, got: #{start_position_value.inspect}",
        suggestion: 'Provide a positive number of seconds to look back.'
      )
    end
  end
end

.validate_queue_poll!(max_items, wait_timeout) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validates queue poll request parameters.

Parameters:

  • max_items (Integer) —

    maximum number of messages to poll (must be >= 1)

  • wait_timeout (Numeric) —

    wait timeout in seconds (0..3600)

Raises:



178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/kubemq/validation/validator.rb', line 178

def validate_queue_poll!(max_items, wait_timeout)
  if !max_items.is_a?(Integer) || max_items < 1
    raise ValidationError.new("max_items must be >= 1, got: #{max_items.inspect}",
                              suggestion: 'Provide a positive integer for max_items.')
  end

  return if wait_timeout.is_a?(Numeric) && wait_timeout >= 0 && wait_timeout <= 3600

  raise ValidationError.new(
    "wait_timeout must be between 0 and 3600 seconds, got: #{wait_timeout.inspect}",
    suggestion: 'Provide a wait_timeout between 0 and 3600 seconds.'
  )
end

.validate_queue_receive!(max_messages, wait_timeout_seconds) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validates queue receive request parameters (simple API).

Parameters:

  • max_messages (Integer) —

    maximum messages to receive (1..1024)

  • wait_timeout_seconds (Numeric) —

    wait timeout in seconds (0..3600)

Raises:

  • (ValidationError) —

    if max_messages is out of range or wait_timeout_seconds is out of range



199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/kubemq/validation/validator.rb', line 199

def validate_queue_receive!(max_messages, wait_timeout_seconds)
  if !max_messages.is_a?(Integer) || max_messages < 1 || max_messages > 1024
    raise ValidationError.new(
      "max_messages must be between 1 and 1024, got: #{max_messages.inspect}",
      suggestion: 'Provide max_messages between 1 and 1024.'
    )
  end

  return if wait_timeout_seconds.is_a?(Numeric) && wait_timeout_seconds >= 0 && wait_timeout_seconds <= 3600

  raise ValidationError.new(
    "wait_timeout_seconds must be between 0 and 3600, got: #{wait_timeout_seconds.inspect}",
    suggestion: 'Provide wait_timeout_seconds between 0 and 3600.'
  )
end

.validate_response!(request_id, reply_channel) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validates that a command/query response has required fields.

Parameters:

  • request_id (String, nil) —

    the originating request ID

  • reply_channel (String, nil) —

    the reply channel from the request

Raises:



118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/kubemq/validation/validator.rb', line 118

def validate_response!(request_id, reply_channel)
  if request_id.nil? || request_id.to_s.strip.empty?
    raise ValidationError.new('request_id is required for response',
                              suggestion: 'Use the request_id from the received request.')
  end

  return unless reply_channel.nil? || reply_channel.to_s.strip.empty?

  raise ValidationError.new('reply_channel is required for response',
                            suggestion: 'Use the reply_channel from the received request.')
end

.validate_timeout!(timeout) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validates that a timeout value is a positive number.

Parameters:

  • timeout (Numeric) —

    the timeout value to validate (in milliseconds for commands/queries)

Raises:



91
92
93
94
95
96
 
# File 'lib/kubemq/validation/validator.rb', line 91

def validate_timeout!(timeout)
  return if timeout.is_a?(Numeric) && timeout.positive?

  raise ValidationError.new("Timeout must be greater than 0, got: #{timeout.inspect}",
                            suggestion: 'Provide a positive timeout value in milliseconds.')
end