kubemq 1.0.0

data/lib/kubemq/transport/message_buffer.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  module Transport
+    # Thread-safe bounded buffer for queuing messages during reconnection.
+    #
+    # When the transport is disconnected, outbound messages are buffered here.
+    # If the buffer reaches capacity, the oldest message is dropped to make
+    # room -- consistent with other KubeMQ SDKs.
+    #
+    # @api private
+    # @note This class is thread-safe. All operations are mutex-protected.
+    #
+    # @see GrpcTransport
+    # @see ReconnectManager
+    class MessageBuffer
+      # Default buffer capacity.
+      DEFAULT_CAPACITY = 1000
+
+      # @return [Integer] maximum number of messages this buffer can hold
+      attr_reader :capacity
+
+      # @param capacity [Integer] maximum buffer size (default: {DEFAULT_CAPACITY})
+      def initialize(capacity: DEFAULT_CAPACITY)
+        @capacity = capacity
+        @queue = Thread::SizedQueue.new(capacity)
+        @mutex = Mutex.new
+      end
+
+      # Adds a message to the buffer. If full, the oldest message is dropped.
+      #
+      # @param message [Object] the message to buffer
+      # @return [void]
+      def push(message)
+        @mutex.synchronize do
+          begin
+            @queue.pop(true) if @queue.size >= @capacity
+          rescue ThreadError
+            # queue was emptied concurrently
+          end
+          begin
+            @queue.push(message, true)
+          rescue ThreadError
+            # queue full; discard
+          end
+        end
+      end
+
+      # Drains all buffered messages. If a block is given, yields each message;
+      # otherwise returns them as an array via {#to_a}.
+      #
+      # @yield [message] each buffered message in FIFO order
+      # @yieldparam message [Object] a buffered message
+      # @return [Array, nil] array of messages if no block given; +nil+ otherwise
+      def drain(&block)
+        return to_a unless block
+
+        loop do
+          msg = @queue.pop(true)
+          block.call(msg)
+        rescue ThreadError
+          break
+        end
+      end
+
+      # Drains all messages and returns them as an array.
+      #
+      # @return [Array<Object>] all buffered messages in FIFO order
+      def to_a
+        messages = []
+        drain { |m| messages << m }
+        messages
+      end
+
+      # Returns the current number of buffered messages.
+      #
+      # @return [Integer] number of messages in the buffer
+      def size
+        @queue.size
+      end
+
+      # Returns whether the buffer is empty.
+      #
+      # @return [Boolean] +true+ if no messages are buffered
+      def empty?
+        @queue.empty?
+      end
+
+      # Returns whether the buffer has reached capacity.
+      #
+      # @return [Boolean] +true+ if {#size} >= {#capacity}
+      def full?
+        @queue.size >= @capacity
+      end
+
+      # Removes all messages from the buffer.
+      #
+      # @return [nil]
+      def clear
+        drain
+        nil
+      end
+    end
+  end
+end

data/lib/kubemq/transport/reconnect_manager.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  module Transport
+    # Manages automatic reconnection with exponential backoff and jitter.
+    #
+    # Spawns a background thread that repeatedly invokes the reconnect procedure
+    # until the connection succeeds or the maximum number of attempts is reached.
+    # Backoff delay is computed as:
+    #   delay = min(base_interval * multiplier^(attempt-1), max_delay) +/- jitter
+    #
+    # @api private
+    #
+    # @see GrpcTransport
+    # @see ConnectionStateMachine
+    # @see ReconnectPolicy
+    class ReconnectManager
+      # @return [Integer] current reconnect attempt counter (0 before first attempt)
+      attr_reader :attempt
+
+      # @param policy [ReconnectPolicy] backoff and retry settings
+      # @param state_machine [ConnectionStateMachine] tracks connection lifecycle
+      # @param reconnect_proc [Proc] callable that performs the actual reconnection
+      # @param on_reconnected [Proc, nil] optional callback invoked after successful reconnection
+      def initialize(policy:, state_machine:, reconnect_proc:, on_reconnected: nil)
+        @policy = policy
+        @state_machine = state_machine
+        @reconnect_proc = reconnect_proc
+        @on_reconnected = on_reconnected
+        @attempt = 0
+        @mutex = Mutex.new
+        @thread = nil
+        @stop_flag = false
+      end
+
+      # Starts the background reconnect loop. No-op if already running.
+      #
+      # @return [void]
+      def start
+        @mutex.synchronize do
+          return if @thread&.alive?
+
+          @stop_flag = false
+          @attempt = 0
+          @thread = Thread.new { reconnect_loop }
+          @thread.name = 'kubemq-reconnect'
+          @thread.abort_on_exception = false
+        end
+      end
+
+      # Signals the reconnect loop to stop and waits up to 5 seconds for
+      # the background thread to finish.
+      #
+      # @return [void]
+      def stop
+        @mutex.synchronize { @stop_flag = true }
+        @thread&.join(5)
+      end
+
+      private
+
+      def reconnect_loop
+        loop do
+          break if stopped? || @state_machine.closed?
+
+          @mutex.synchronize { @attempt += 1 }
+
+          if @policy.max_attempts.positive? && @attempt > @policy.max_attempts
+            @state_machine.transition!(ConnectionState::CLOSED,
+                                       reason: 'max reconnect attempts exceeded')
+            break
+          end
+
+          delay = compute_delay
+          sleep_with_check(delay)
+          break if stopped? || @state_machine.closed?
+
+          begin
+            @reconnect_proc.call
+            @on_reconnected&.call
+            break
+          rescue StandardError => e
+            Kernel.warn("[kubemq-reconnect] attempt #{@attempt} failed: #{e.message}")
+            next
+          end
+        end
+      end
+
+      def compute_delay
+        base = [@policy.base_interval * (@policy.multiplier**(@attempt - 1)),
+                @policy.max_delay].min
+        jitter = base * @policy.jitter_percent * ((rand * 2) - 1)
+        [base + jitter, 0.1].max
+      end
+
+      def sleep_with_check(seconds)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+        loop do
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          break if remaining <= 0 || stopped? || @state_machine.closed?
+
+          sleep([remaining, 0.5].min)
+        end
+      end
+
+      def stopped?
+        @mutex.synchronize { @stop_flag }
+      end
+    end
+  end
+end

data/lib/kubemq/transport/state_machine.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  module Transport
+    # Finite state machine governing the gRPC connection lifecycle.
+    #
+    # Tracks transitions between {ConnectionState} values and fires registered
+    # callbacks on state changes. Invalid transitions raise {Error}.
+    #
+    # Valid transition graph:
+    #   IDLE -> CONNECTING, CLOSED
+    #   CONNECTING -> READY, CLOSED, RECONNECTING, IDLE
+    #   READY -> RECONNECTING, CLOSED
+    #   RECONNECTING -> CONNECTING, READY, CLOSED
+    #   CLOSED -> (terminal)
+    #
+    # @api private
+    # @note This class is thread-safe. All state reads and transitions are
+    #   mutex-protected.
+    #
+    # @see GrpcTransport
+    # @see ReconnectManager
+    # @see ConnectionState
+    class ConnectionStateMachine
+      # Map of each state to its permitted successor states.
+      VALID_TRANSITIONS = {
+        ConnectionState::IDLE => [ConnectionState::CONNECTING, ConnectionState::CLOSED],
+        ConnectionState::CONNECTING => [ConnectionState::READY, ConnectionState::CLOSED,
+                                        ConnectionState::RECONNECTING, ConnectionState::IDLE],
+        ConnectionState::READY => [ConnectionState::RECONNECTING, ConnectionState::CLOSED],
+        ConnectionState::RECONNECTING => [ConnectionState::CONNECTING, ConnectionState::READY,
+                                          ConnectionState::CLOSED],
+        ConnectionState::CLOSED => []
+      }.freeze
+
+      # @return [Integer] the current {ConnectionState} value
+      attr_reader :state
+
+      # Creates a new state machine starting in {ConnectionState::IDLE}.
+      def initialize
+        @state = ConnectionState::IDLE
+        @mutex = Mutex.new
+        @callbacks = {
+          on_connected: nil,
+          on_disconnected: nil,
+          on_reconnecting: nil,
+          on_error: nil
+        }
+      end
+
+      # Registers a callback invoked when the connection reaches READY.
+      #
+      # @yield [server_info] called with the broker's {ServerInfo}
+      # @yieldparam server_info [ServerInfo, nil] broker information
+      # @return [void]
+      def on_connected(&block)
+        @mutex.synchronize { @callbacks[:on_connected] = block }
+      end
+
+      # Registers a callback invoked when the connection reaches CLOSED.
+      #
+      # @yield [reason] called with a human-readable close reason
+      # @yieldparam reason [String] reason for disconnection
+      # @return [void]
+      def on_disconnected(&block)
+        @mutex.synchronize { @callbacks[:on_disconnected] = block }
+      end
+
+      # Registers a callback invoked when the connection enters RECONNECTING.
+      #
+      # @yield [attempt] called with the current reconnect attempt number
+      # @yieldparam attempt [Integer] attempt counter
+      # @return [void]
+      def on_reconnecting(&block)
+        @mutex.synchronize { @callbacks[:on_reconnecting] = block }
+      end
+
+      # Registers a callback invoked on invalid state transitions.
+      #
+      # @yield [error] called with the {Error} describing the invalid transition
+      # @yieldparam error [Error] the transition error
+      # @return [void]
+      def on_error(&block)
+        @mutex.synchronize { @callbacks[:on_error] = block }
+      end
+
+      # Transitions to a new state, firing the appropriate callback.
+      #
+      # @param new_state [Integer] the target {ConnectionState} value
+      # @param context [Hash] optional context passed to the callback
+      #   (+:server_info+, +:attempt+, or +:reason+)
+      # @return [void]
+      # @raise [Error] if the transition is invalid per {VALID_TRANSITIONS}
+      def transition!(new_state, **context)
+        callback = nil
+        @mutex.synchronize do
+          valid = VALID_TRANSITIONS.fetch(@state, [])
+          unless valid.include?(new_state)
+            error = KubeMQ::Error.new("Invalid state transition from #{@state} to #{new_state}")
+            err_cb = @callbacks[:on_error]
+            err_cb&.call(error)
+            raise error
+          end
+
+          old_state = @state
+          @state = new_state
+          callback = resolve_callback(new_state, old_state, context)
+        end
+        callback&.call
+      end
+
+      # Returns the current state with mutex synchronization.
+      #
+      # @return [Integer] the current {ConnectionState} value
+      def current_state
+        @mutex.synchronize { @state }
+      end
+
+      # Returns whether the connection is in the READY state.
+      #
+      # @return [Boolean] +true+ if connected and operational
+      def ready?
+        current_state == ConnectionState::READY
+      end
+
+      # Returns whether the connection has been permanently closed.
+      #
+      # @return [Boolean] +true+ if in the terminal CLOSED state
+      def closed?
+        current_state == ConnectionState::CLOSED
+      end
+
+      private
+
+      def resolve_callback(new_state, _old_state, context)
+        case new_state
+        when ConnectionState::READY
+          cb = @callbacks[:on_connected]
+          cb ? -> { cb.call(context[:server_info]) } : nil
+        when ConnectionState::RECONNECTING
+          cb = @callbacks[:on_reconnecting]
+          cb ? -> { cb.call(context[:attempt] || 0) } : nil
+        when ConnectionState::CLOSED
+          cb = @callbacks[:on_disconnected]
+          cb ? -> { cb.call(context[:reason] || 'closed') } : nil
+        end
+      end
+    end
+  end
+end

data/lib/kubemq/types.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  # Transport connection lifecycle states.
+  #
+  # Used by the internal {Transport::ConnectionStateMachine} to track
+  # the gRPC channel state. Inspect via {BaseClient} diagnostics.
+  #
+  # @see Transport::ConnectionStateMachine
+  module ConnectionState
+    # Initial state before any connection attempt.
+    IDLE = :idle
+    # A connection attempt is in progress.
+    CONNECTING = :connecting
+    # Connected and ready to send/receive messages.
+    READY = :ready
+    # Disconnected and attempting to reconnect.
+    RECONNECTING = :reconnecting
+    # Permanently closed; no further operations are possible.
+    CLOSED = :closed
+  end
+
+  # Numeric subscription type identifiers sent over the wire.
+  #
+  # Mapped to the protobuf +Subscribe.SubscribeTypeData+ enum.
+  # Application code typically does not use these directly — pass
+  # subscription objects to +subscribe_to_*+ methods instead.
+  #
+  # @api private
+  module SubscribeType
+    # Unspecified subscription type.
+    UNDEFINED = 0
+    # Real-time fire-and-forget events.
+    EVENTS = 1
+    # Durable events with replay capability.
+    EVENTS_STORE = 2
+    # Request/reply commands.
+    COMMANDS = 3
+    # Request/reply queries.
+    QUERIES = 4
+  end
+
+  # Numeric request type identifiers for the CQ (commands/queries) pattern.
+  #
+  # Mapped to the protobuf +Request.RequestTypeData+ enum.
+  #
+  # @api private
+  module RequestType
+    # Unspecified request type.
+    UNKNOWN = 0
+    # A command (fire-and-confirm) request.
+    COMMAND = 1
+    # A query (request/response with data) request.
+    QUERY = 2
+  end
+
+  # String channel type identifiers used by channel management operations.
+  #
+  # Pass these constants to {BaseClient#create_channel},
+  # {BaseClient#delete_channel}, and {BaseClient#list_channels}.
+  #
+  # @example
+  #   client.list_channels(channel_type: KubeMQ::ChannelType::EVENTS)
+  #
+  # @see BaseClient#create_channel
+  # @see BaseClient#delete_channel
+  # @see BaseClient#list_channels
+  module ChannelType
+    # Pub/sub fire-and-forget events.
+    EVENTS = 'events'
+    # Durable events with persistence and replay.
+    EVENTS_STORE = 'events_store'
+    # Request/reply commands.
+    COMMANDS = 'commands'
+    # Request/reply queries.
+    QUERIES = 'queries'
+    # Message queues with acknowledgement.
+    QUEUES = 'queues'
+  end
+end

data/lib/kubemq/validation/validator.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  # 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.
+  #
+  # @api private
+  #
+  # @see ValidationError
+  # @see BaseClient
+  # rubocop:disable Metrics/ModuleLength -- validation helpers per message type
+  module Validator
+    # Permitted characters for channel names (alphanumeric, dots, hyphens,
+    # underscores, slashes, and wildcard tokens).
+    CHANNEL_NAME_REGEX = %r{\A[a-zA-Z0-9._\-/>*]+\z}
+
+    module_function
+
+    # Validates a channel name for format and optional wildcard support.
+    #
+    # @param channel [String] the channel name to validate
+    # @param allow_wildcards [Boolean] whether +*+ and +>+ are permitted
+    # @return [void]
+    # @raise [ValidationError] if the channel is nil, empty, contains invalid
+    #   characters, ends with a dot, or uses wildcards when disallowed
+    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
+
+    # Validates that at least one of metadata or body is non-empty.
+    #
+    # @param metadata [String, nil] message metadata
+    # @param body [String, nil] message body
+    # @return [void]
+    # @raise [ValidationError] if both metadata and body are nil or empty
+    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
+
+    # Validates that a client ID is present and non-empty.
+    #
+    # @param client_id [String, nil] the client identifier to validate
+    # @return [void]
+    # @raise [ValidationError] if the client ID is nil or blank
+    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
+
+    # Validates that a timeout value is a positive number.
+    #
+    # @param timeout [Numeric] the timeout value to validate (in milliseconds
+    #   for commands/queries)
+    # @return [void]
+    # @raise [ValidationError] if the timeout is not a positive number
+    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
+
+    # Validates cache parameters for query messages.
+    #
+    # @param cache_key [String, nil] the cache key (validation only applies when set)
+    # @param cache_ttl [Numeric, nil] the cache TTL in seconds
+    # @return [void]
+    # @raise [ValidationError] if +cache_key+ is set but +cache_ttl+ is not positive
+    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
+
+    # Validates that a command/query response has required fields.
+    #
+    # @param request_id [String, nil] the originating request ID
+    # @param reply_channel [String, nil] the reply channel from the request
+    # @return [void]
+    # @raise [ValidationError] if +request_id+ or +reply_channel+ is nil or blank
+    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
+
+    # Validates events store subscription start position and its associated value.
+    #
+    # @param start_position [Integer, nil] one of the EventStoreStartPosition constants
+    # @param start_position_value [Numeric, nil] sequence number, Unix timestamp,
+    #   or delta seconds depending on the start position type
+    # @return [void]
+    # @raise [ValidationError] if the start position is missing or the value is
+    #   invalid for the chosen position type
+    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
+
+    # Validates queue poll request parameters.
+    #
+    # @param max_items [Integer] maximum number of messages to poll (must be >= 1)
+    # @param wait_timeout [Numeric] wait timeout in seconds (0..3600)
+    # @return [void]
+    # @raise [ValidationError] if +max_items+ < 1 or +wait_timeout+ is out of range
+    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
+
+    # Validates queue receive request parameters (simple API).
+    #
+    # @param max_messages [Integer] maximum messages to receive (1..1024)
+    # @param wait_timeout_seconds [Numeric] wait timeout in seconds (0..3600)
+    # @return [void]
+    # @raise [ValidationError] if +max_messages+ is out of range or
+    #   +wait_timeout_seconds+ is out of range
+    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
+  end
+  # rubocop:enable Metrics/ModuleLength
+end

data/lib/kubemq/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  # Current version of the kubemq-ruby SDK, following {https://semver.org Semantic Versioning}.
+  VERSION = '1.0.0'
+end