kubemq 1.0.0

data/lib/kubemq/server_info.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  # Information about a KubeMQ broker returned by {BaseClient#ping}.
+  #
+  # @example
+  #   info = client.ping
+  #   puts "Connected to #{info.host} v#{info.version}, up #{info.server_up_time_seconds}s"
+  #
+  # @see BaseClient#ping
+  class ServerInfo
+    # @!attribute [r] host
+    #   @return [String] broker hostname or IP address
+    # @!attribute [r] version
+    #   @return [String] broker software version
+    # @!attribute [r] server_start_time
+    #   @return [Integer] broker start time as a Unix timestamp
+    # @!attribute [r] server_up_time_seconds
+    #   @return [Integer] broker uptime in seconds
+    attr_reader :host, :version, :server_start_time, :server_up_time_seconds
+
+    # Creates a new ServerInfo instance.
+    #
+    # @param host [String] broker hostname or IP address
+    # @param version [String] broker software version
+    # @param server_start_time [Integer] broker start time as a Unix timestamp
+    # @param server_up_time_seconds [Integer] broker uptime in seconds
+    def initialize(host:, version:, server_start_time:, server_up_time_seconds:)
+      @host = host
+      @version = version
+      @server_start_time = server_start_time
+      @server_up_time_seconds = server_up_time_seconds
+    end
+
+    # Constructs a {ServerInfo} from a protobuf ping result.
+    #
+    # @api private
+    # @param ping_result [Kubemq::PingResult] protobuf ping response
+    # @return [ServerInfo]
+    def self.from_proto(ping_result)
+      new(
+        host: ping_result.Host,
+        version: ping_result.Version,
+        server_start_time: ping_result.ServerStartTime,
+        server_up_time_seconds: ping_result.ServerUpTimeSeconds
+      )
+    end
+
+    # Returns a human-readable summary of the server information.
+    #
+    # @return [String]
+    def to_s
+      "ServerInfo(host=#{@host}, version=#{@version}, " \
+        "up_time=#{@server_up_time_seconds}s)"
+    end
+  end
+end

data/lib/kubemq/subscription.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  # Handle for an active subscription running on a background thread.
+  #
+  # Returned by +subscribe_to_*+ methods on {PubSubClient} and {CQClient}.
+  # Use {#cancel} to stop the subscription, {#active?} to check its state,
+  # and {#wait} or {#join} to block until the subscription thread exits.
+  #
+  # @note This class is thread-safe. Status transitions and error state are
+  #   protected by a mutex.
+  #
+  # @example Cancel a subscription gracefully
+  #   subscription = client.subscribe_to_events(sub) { |e| process(e) }
+  #   # ... later ...
+  #   subscription.cancel
+  #   subscription.wait(5) # wait up to 5 seconds for thread to exit
+  #
+  # @see CancellationToken
+  # @see PubSubClient#subscribe_to_events
+  # @see CQClient#subscribe_to_commands
+  class Subscription
+    # @!attribute [r] status
+    #   @return [Symbol] current subscription state — +:active+, +:cancelled+,
+    #     +:error+, or +:closed+
+    # @!attribute [r] last_error
+    #   @return [StandardError, nil] the most recent error, or +nil+ if none
+    attr_reader :status, :last_error
+
+    # Creates a new subscription handle.
+    #
+    # @api private
+    # @param thread [Thread] the background thread running the subscription loop
+    # @param cancellation_token [CancellationToken] token used to signal cancellation
+    def initialize(thread:, cancellation_token:)
+      @thread = thread
+      @cancellation_token = cancellation_token
+      @status = :active
+      @last_error = nil
+      @mutex = Mutex.new
+    end
+
+    # Cancels the subscription, stops the gRPC stream, and waits up to
+    # 5 seconds for the background thread to exit.
+    #
+    # @return [void]
+    def cancel
+      @mutex.synchronize { @status = :cancelled }
+      @cancellation_token.cancel
+      begin; @thread[:grpc_call]&.cancel; rescue StandardError; end
+      @thread.join(5)
+    end
+
+    # Returns whether the subscription is still actively receiving messages.
+    #
+    # @return [Boolean] +true+ if status is +:active+ and the thread is alive
+    def active?
+      @mutex.synchronize { @status == :active } && @thread.alive?
+    end
+
+    # Blocks the calling thread until the subscription thread exits or the
+    # timeout elapses.
+    #
+    # @param timeout [Numeric, nil] maximum seconds to wait (+nil+ for indefinite)
+    # @return [Thread, nil] the subscription thread if it exited, +nil+ on timeout
+    def wait(timeout = nil)
+      @thread.join(timeout)
+    end
+
+    # Alias for {#wait}. Blocks until the subscription thread exits.
+    #
+    # @param timeout [Numeric, nil] maximum seconds to wait (+nil+ for indefinite)
+    # @return [Thread, nil] the subscription thread if it exited, +nil+ on timeout
+    def join(timeout = nil)
+      @thread.join(timeout)
+    end
+
+    # Records an error on this subscription.
+    #
+    # @api private
+    # @param error [StandardError] the error that occurred
+    # @return [void]
+    def mark_error(error)
+      @mutex.synchronize do
+        @status = :error
+        @last_error = error
+      end
+    end
+
+    # Marks this subscription as closed.
+    #
+    # @api private
+    # @return [void]
+    def mark_closed
+      @mutex.synchronize { @status = :closed }
+    end
+  end
+end

data/lib/kubemq/telemetry/otel.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative 'semconv'
+
+module KubeMQ
+  # OpenTelemetry integration for distributed tracing of KubeMQ operations.
+  #
+  # Provides a thin wrapper around the OpenTelemetry API that degrades
+  # gracefully when the SDK is not loaded. Attribute names follow the
+  # {SemanticConventions} module.
+  #
+  # @see SemanticConventions
+  # @see Interceptors::MetricsInterceptor
+  module Telemetry
+    # OpenTelemetry tracer name registered for this SDK.
+    TRACER_NAME = 'kubemq-ruby'
+
+    # Returns whether the OpenTelemetry API is loaded and configured.
+    #
+    # @return [Boolean] +true+ if +OpenTelemetry.tracer_provider+ is available
+    def self.otel_available?
+      defined?(OpenTelemetry) && OpenTelemetry.respond_to?(:tracer_provider)
+    end
+
+    # Runs +block+ inside an OpenTelemetry span when the API is loaded;
+    # otherwise yields +nil+ once.
+    #
+    # Always sets +messaging.system+ to {SemanticConventions::MESSAGING_SYSTEM}.
+    # Additional attributes are merged and their keys are coerced to strings.
+    #
+    # @param name [String] descriptive span name (e.g., +"kubemq send_event orders"+)
+    # @param kind [Symbol] OpenTelemetry span kind -- +:producer+, +:consumer+,
+    #   or +:client+ (default: {SemanticConventions::SPAN_KIND_CLIENT})
+    # @param attributes [Hash{String, Symbol => String, Numeric, Boolean}]
+    #   extra span attributes
+    # @yield [span] the block to execute inside the span
+    # @yieldparam span [OpenTelemetry::Trace::Span, nil] the active span,
+    #   or +nil+ when OpenTelemetry is not available
+    # @return [Object] the return value of the block
+    # @raise [ArgumentError] if no block is given
+    def self.with_span(name, kind: SemanticConventions::SPAN_KIND_CLIENT, attributes: {}, &block)
+      raise ArgumentError, 'block required' unless block
+
+      return block.call(nil) unless otel_available?
+
+      merged = {
+        SemanticConventions::ATTR_MESSAGING_SYSTEM => SemanticConventions::MESSAGING_SYSTEM
+      }.merge(stringify_attributes(attributes))
+
+      tracer = OpenTelemetry.tracer_provider.tracer(TRACER_NAME)
+      tracer.in_span(name, attributes: merged, kind: kind, &block)
+    end
+
+    # Coerces attribute keys to strings.
+    #
+    # @param attributes [Hash] raw attribute map
+    # @return [Hash{String => Object}] attributes with string keys
+    def self.stringify_attributes(attributes)
+      attributes.to_h.transform_keys(&:to_s)
+    end
+
+    private_class_method :stringify_attributes
+  end
+end

data/lib/kubemq/telemetry/semconv.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  module Telemetry
+    # OpenTelemetry messaging semantic convention constants.
+    #
+    # Provides stable attribute names and span-kind symbols aligned with the
+    # OpenTelemetry Semantic Conventions for Messaging (semconv v1.27+).
+    # Used by {Telemetry.with_span} and {Interceptors::MetricsInterceptor}
+    # to emit consistent telemetry data.
+    #
+    # @see Telemetry.with_span
+    # @see Interceptors::MetricsInterceptor
+    module SemanticConventions
+      # Value for the +messaging.system+ attribute when talking to KubeMQ.
+      MESSAGING_SYSTEM = 'kubemq'
+
+      # @!group Attribute Keys
+
+      # Identifies the messaging system (always {MESSAGING_SYSTEM} for KubeMQ).
+      ATTR_MESSAGING_SYSTEM = 'messaging.system'
+
+      # Name of the messaging operation (e.g., +"send"+, +"receive"+, +"process"+).
+      ATTR_MESSAGING_OPERATION_NAME = 'messaging.operation.name'
+
+      # Logical name of the destination channel or queue.
+      ATTR_MESSAGING_DESTINATION_NAME = 'messaging.destination.name'
+
+      # Unique identifier of the message being traced.
+      ATTR_MESSAGING_MESSAGE_ID = 'messaging.message.id'
+
+      # Identifier of the client that produced or consumed the message.
+      ATTR_MESSAGING_CLIENT_ID = 'messaging.client.id'
+
+      # @!endgroup
+
+      # @!group Span Kinds
+
+      # Span kind for message-producing operations (e.g., send, publish).
+      SPAN_KIND_PRODUCER = :producer
+
+      # Span kind for message-consuming operations (e.g., subscribe, poll).
+      SPAN_KIND_CONSUMER = :consumer
+
+      # Span kind for synchronous client operations (e.g., ping, create_channel).
+      SPAN_KIND_CLIENT = :client
+
+      # @!endgroup
+    end
+  end
+end

data/lib/kubemq/transport/channel_manager.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'json'
+require_relative '../proto/kubemq_pb'
+
+module KubeMQ
+  module Transport
+    # Channel lifecycle operations (create, delete, list, purge) sent as
+    # internal queries over the KubeMQ cluster management channel.
+    #
+    # All methods are module-level (+module_function+) and delegate the
+    # underlying gRPC call to the provided {GrpcTransport} instance.
+    #
+    # @api private
+    #
+    # @see GrpcTransport
+    # @see BaseClient
+    # rubocop:disable Metrics/ModuleLength -- internal channel CRUD + list helpers
+    module ChannelManager
+      # Cluster-internal channel used for management requests.
+      INTERNAL_CHANNEL = 'kubemq.cluster.internal.requests'
+
+      # Default timeout (in milliseconds) for management requests.
+      INTERNAL_TIMEOUT = 10_000
+
+      module_function
+
+      # Creates a channel on the KubeMQ broker.
+      #
+      # @param transport [GrpcTransport] the active transport instance
+      # @param client_id [String] the client identifier
+      # @param channel_name [String] name for the new channel
+      # @param channel_type [String] one of {ChannelType} constants
+      # @return [Boolean] +true+ on success
+      # @raise [ChannelError] if the broker rejects the operation
+      #
+      # @see BaseClient#create_channel
+      # rubocop:disable Naming/PredicateMethod -- command-style API returns true on success
+      def create_channel(transport, client_id, channel_name, channel_type)
+        request = build_request(
+          client_id: client_id,
+          metadata: 'create-channel',
+          tags: {
+            'channel_type' => channel_type,
+            'channel' => channel_name,
+            'client_id' => client_id
+          }
+        )
+
+        response = transport.kubemq_client.send_request(request)
+        check_response_error!(response, 'create_channel', channel_name)
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # Deletes a channel from the KubeMQ broker.
+      #
+      # @param transport [GrpcTransport] the active transport instance
+      # @param client_id [String] the client identifier
+      # @param channel_name [String] name of the channel to delete
+      # @param channel_type [String] one of {ChannelType} constants
+      # @return [Boolean] +true+ on success
+      # @raise [ChannelError] if the broker rejects the operation
+      #
+      # @see BaseClient#delete_channel
+      # rubocop:disable Naming/PredicateMethod -- command-style API returns true on success
+      def delete_channel(transport, client_id, channel_name, channel_type)
+        request = build_request(
+          client_id: client_id,
+          metadata: 'delete-channel',
+          tags: {
+            'channel_type' => channel_type,
+            'channel' => channel_name
+          }
+        )
+
+        response = transport.kubemq_client.send_request(request)
+        check_response_error!(response, 'delete_channel', channel_name)
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # Lists channels of the specified type, with optional name filtering.
+      #
+      # Retries up to 3 times when the cluster snapshot is not ready.
+      #
+      # @param transport [GrpcTransport] the active transport instance
+      # @param client_id [String] the client identifier
+      # @param channel_type [String] one of {ChannelType} constants
+      # @param search [String, nil] substring filter for channel names
+      # @return [Array<ChannelInfo>] matching channels with metadata
+      # @raise [ChannelError] if the broker rejects the operation after retries
+      #
+      # @see BaseClient#list_channels
+      def list_channels(transport, client_id, channel_type, search = nil)
+        tags = { 'channel_type' => channel_type }
+        tags['channel_search'] = search if search && !search.empty?
+
+        request = build_request(
+          client_id: client_id,
+          metadata: 'list-channels',
+          tags: tags
+        )
+
+        max_retries = 3
+        response = nil
+        max_retries.times do |attempt|
+          response = transport.kubemq_client.send_request(request)
+
+          raise StandardError, response.Error if response.Error&.include?('cluster snapshot not ready')
+
+          break
+        rescue StandardError => e
+          if e.message.include?('cluster snapshot not ready') && attempt < max_retries - 1
+            sleep(1)
+            next
+          end
+          raise ChannelError.new(
+            "list_channels failed after #{attempt + 1} attempts: #{e.message}",
+            operation: 'list_channels'
+          )
+        end
+
+        check_response_error!(response, 'list_channels')
+        parse_channel_list(response.Body, channel_type)
+      end
+
+      # Purges all pending messages from a queue channel.
+      #
+      # @param transport [GrpcTransport] the active transport instance
+      # @param client_id [String] the client identifier
+      # @param channel_name [String] queue channel to purge
+      # @return [Hash{Symbol => Integer}] +{ affected_messages: Integer }+
+      # @raise [ChannelError] if the broker rejects the operation
+      #
+      # @see BaseClient#purge_queue_channel
+      def purge_queue(transport, client_id, channel_name)
+        request = ::Kubemq::AckAllQueueMessagesRequest.new(
+          RequestID: SecureRandom.uuid,
+          ClientID: client_id,
+          Channel: channel_name,
+          WaitTimeSeconds: 5
+        )
+
+        response = transport.kubemq_client.ack_all_queue_messages(request)
+        if response.IsError && !response.Error.empty?
+          raise ChannelError.new(
+            "Failed to purge queue '#{channel_name}': #{response.Error}",
+            code: ErrorCode::INTERNAL,
+            operation: 'purge_queue',
+            channel: channel_name
+          )
+        end
+
+        { affected_messages: response.AffectedMessages }
+      end
+
+      # Builds a protobuf management request targeting the internal channel.
+      #
+      # @param client_id [String] the client identifier
+      # @param metadata [String] management operation name
+      # @param tags [Hash{String => String}] operation parameters as tags
+      # @return [Kubemq::Request] protobuf request
+      def build_request(client_id:, metadata:, tags:)
+        ::Kubemq::Request.new(
+          RequestID: SecureRandom.uuid,
+          RequestTypeData: RequestType::QUERY,
+          ClientID: client_id,
+          Channel: INTERNAL_CHANNEL,
+          Metadata: metadata,
+          Timeout: INTERNAL_TIMEOUT,
+          Tags: tags
+        )
+      end
+
+      # Raises {ChannelError} if the response contains a non-empty error string.
+      #
+      # @param response [Kubemq::Response] protobuf response to check
+      # @param operation [String] the operation name for error context
+      # @param channel [String, nil] the channel name for error context
+      # @return [void]
+      # @raise [ChannelError] if the response indicates failure
+      def check_response_error!(response, operation, channel = nil)
+        return if response.Error.nil? || response.Error.empty?
+
+        raise ChannelError.new(
+          "#{operation} failed: #{response.Error}",
+          code: ErrorCode::INTERNAL,
+          operation: operation,
+          channel: channel
+        )
+      end
+
+      # Parses a JSON channel list response body into {ChannelInfo} objects.
+      #
+      # @param body [String, nil] JSON response body
+      # @param channel_type [String] channel type to assign to each entry
+      # @return [Array<ChannelInfo>] parsed channel info objects
+      def parse_channel_list(body, channel_type)
+        return [] if body.nil? || body.empty?
+
+        data = JSON.parse(body.dup.force_encoding('UTF-8'))
+        channels = data.is_a?(Array) ? data : (data['channels'] || data['items'] || [data])
+        channels.compact.map { |ch| ChannelInfo.from_json(ch.merge('type' => channel_type)) }
+      rescue JSON::ParserError
+        []
+      end
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end