kubemq 1.0.0

data/lib/kubemq/cq/client.rb

@@ -0,0 +1,446 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module KubeMQ
+  # Client for KubeMQ commands and queries — synchronous request/reply RPC.
+  #
+  # Commands are fire-and-confirm (no response body); queries return data and
+  # support server-side caching. Inherits connection management and channel
+  # CRUD from {BaseClient}.
+  #
+  # @example Send a command and handle the response
+  #   client = KubeMQ::CQClient.new(address: "localhost:50000")
+  #   cmd = KubeMQ::CQ::CommandMessage.new(
+  #     channel: "commands.users",
+  #     body: '{"action": "create"}',
+  #     timeout: 5000
+  #   )
+  #   response = client.send_command(cmd)
+  #   puts "Executed: #{response.executed}"
+  #   client.close
+  #
+  # @see CQ::CommandMessage
+  # @see CQ::QueryMessage
+  # @see CQ::CommandsSubscription
+  # @see CQ::QueriesSubscription
+  class CQClient < BaseClient
+    # --- Commands ---
+
+    # Sends a command to a responder and waits for confirmation.
+    #
+    # @param message [CQ::CommandMessage] command to send
+    #
+    # @return [CQ::CommandResponse] execution confirmation
+    #
+    # @raise [ValidationError] if channel, content, or timeout is invalid
+    # @raise [ClientClosedError] if the client has been closed
+    # @raise [ConnectionError] if unable to reach the broker
+    # @raise [TimeoutError] if no responder replies within the timeout
+    #
+    # @note Timeout is in milliseconds.
+    #
+    # @example
+    #   cmd = KubeMQ::CQ::CommandMessage.new(
+    #     channel: "commands.orders",
+    #     body: '{"action": "cancel", "id": 42}',
+    #     timeout: 10_000
+    #   )
+    #   response = client.send_command(cmd)
+    #   puts "Success" if response.executed
+    #
+    # @see CQ::CommandMessage
+    # @see CQ::CommandResponse
+    def send_command(message)
+      Validator.validate_channel!(message.channel, allow_wildcards: false)
+      Validator.validate_content!(message.metadata, message.body)
+      Validator.validate_timeout!(message.timeout)
+      ensure_connected!
+
+      proto = Transport::Converter.request_to_proto(message, @config.client_id, RequestType::COMMAND)
+      response = @transport.kubemq_client.send_request(proto)
+      hash = Transport::Converter.proto_to_command_response(response)
+      CQ::CommandResponse.new(**hash)
+    end
+
+    # Subscribes to incoming commands on a channel. Runs on a background
+    # thread; incoming commands are delivered to the provided block.
+    #
+    # The block should process the command and send a response via
+    # {#send_response}. The subscription auto-reconnects with exponential
+    # backoff on transient failures.
+    #
+    # @param subscription [CQ::CommandsSubscription] channel and group config
+    # @param cancellation_token [CancellationToken, nil] token for cooperative
+    #   cancellation (auto-created if nil)
+    # @param on_error [Proc, nil] callback receiving {Error} on stream or
+    #   callback failures
+    # @yield [command] called for each received command on a background thread
+    # @yieldparam command [CQ::CommandReceived] the received command
+    #
+    # @return [Subscription] handle to check status, cancel, or join
+    #
+    # @raise [ArgumentError] if no block is given
+    # @raise [ValidationError] if the subscription channel is invalid
+    # @raise [ClientClosedError] if the client has been closed
+    #
+    # @note Wildcard channels are NOT supported for commands.
+    #
+    # @example
+    #   token = KubeMQ::CancellationToken.new
+    #   sub = KubeMQ::CQ::CommandsSubscription.new(channel: "commands.orders")
+    #   client.subscribe_to_commands(sub, cancellation_token: token) do |cmd|
+    #     # process and respond
+    #     client.send_response(
+    #       KubeMQ::CQ::CommandResponseMessage.new(
+    #         request_id: cmd.id,
+    #         reply_channel: cmd.reply_channel,
+    #         executed: true
+    #       )
+    #     )
+    #   end
+    #
+    # @see CQ::CommandsSubscription
+    # @see CQ::CommandReceived
+    # @see #send_response
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- subscription with auto-reconnect loop
+    def subscribe_to_commands(subscription, cancellation_token: nil, on_error: nil, &block)
+      raise ArgumentError, 'Block required for subscribe_to_commands' unless block
+
+      Validator.validate_channel!(subscription.channel, allow_wildcards: false)
+      ensure_connected!
+
+      cancellation_token ||= CancellationToken.new
+      nil
+
+      thread = Thread.new do
+        @transport.register_subscription(Thread.current)
+        Thread.current[:cancellation_token] = cancellation_token
+        reconnect_attempts = 0
+        begin
+          loop do
+            break if cancellation_token.cancelled?
+
+            begin
+              @transport.ensure_connected!
+              proto_sub = Transport::Converter.subscribe_to_proto(subscription, @config.client_id)
+              stream = @transport.kubemq_client.subscribe_to_requests(proto_sub)
+              Thread.current[:grpc_call] = stream
+              reconnect_attempts = 0
+              stream.each do |request|
+                break if cancellation_token.cancelled?
+
+                received = CQ::CommandReceived.new(
+                  id: request.RequestID,
+                  channel: request.Channel,
+                  metadata: request.Metadata,
+                  body: request.Body,
+                  reply_channel: request.ReplyChannel,
+                  tags: request.Tags.to_h,
+                  timeout: request.Timeout,
+                  client_id: request.ClientID
+                )
+                begin
+                  block.call(received)
+                rescue StandardError => e
+                  begin
+                    on_error&.call(Error.new("Callback error: #{e.message}", code: ErrorCode::CALLBACK_ERROR))
+                  rescue StandardError => nested
+                    Kernel.warn("[kubemq] on_error callback raised: #{nested.message}")
+                  end
+                end
+              end
+            rescue CancellationError
+              break
+            rescue GRPC::BadStatus, StandardError => e
+              @transport.on_disconnect! if e.is_a?(GRPC::Unavailable) || e.is_a?(GRPC::DeadlineExceeded)
+              reconnect_attempts += 1
+              begin
+                if e.is_a?(GRPC::BadStatus)
+                  on_error&.call(ErrorMapper.map_grpc_error(e, operation: 'subscribe_commands'))
+                else
+                  on_error&.call(Error.new(e.message, code: ErrorCode::STREAM_BROKEN))
+                end
+              rescue StandardError => cb_err
+                Kernel.warn("[kubemq] on_error callback raised: #{cb_err.message}")
+              end
+              delay = [@config.reconnect_policy.base_interval *
+                (@config.reconnect_policy.multiplier**(reconnect_attempts - 1)),
+                       @config.reconnect_policy.max_delay].min
+              sleep(delay) unless cancellation_token.cancelled?
+            end
+          end
+        rescue StandardError => e
+          Thread.current[:kubemq_subscription]&.mark_error(e)
+        ensure
+          begin; Thread.current[:grpc_call]&.cancel; rescue StandardError; end
+          Thread.current[:kubemq_subscription]&.mark_closed
+          @transport.unregister_subscription(Thread.current)
+        end
+      end
+
+      sub_wrapper = KubeMQ::Subscription.new(thread: thread, cancellation_token: cancellation_token)
+      thread[:kubemq_subscription] = sub_wrapper
+      sub_wrapper
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    # Sends a response to a received command or query.
+    #
+    # Call this from within a {#subscribe_to_commands} or
+    # {#subscribe_to_queries} block to reply to the sender.
+    #
+    # @param response [CQ::CommandResponseMessage, CQ::QueryResponseMessage]
+    #   the response to send
+    #
+    # @return [void]
+    #
+    # @raise [ValidationError] if +request_id+ or +reply_channel+ is missing
+    # @raise [ClientClosedError] if the client has been closed
+    # @raise [ConnectionError] if unable to reach the broker
+    #
+    # @see CQ::CommandResponseMessage
+    # @see CQ::QueryResponseMessage
+    def send_response(response)
+      Validator.validate_response!(response.request_id, response.reply_channel)
+      ensure_connected!
+
+      proto = Transport::Converter.response_message_to_proto(response, @config.client_id)
+      @transport.kubemq_client.send_response(proto)
+      nil
+    end
+
+    # --- Queries ---
+
+    # Sends a query to a responder and waits for a data response.
+    #
+    # Queries support server-side caching via +cache_key+ and +cache_ttl+
+    # on the {CQ::QueryMessage}.
+    #
+    # @param message [CQ::QueryMessage] query to send
+    #
+    # @return [CQ::QueryResponse] response with body, metadata, and cache_hit
+    #
+    # @raise [ValidationError] if channel, content, timeout, or cache params
+    #   are invalid
+    # @raise [ClientClosedError] if the client has been closed
+    # @raise [ConnectionError] if unable to reach the broker
+    # @raise [TimeoutError] if no responder replies within the timeout
+    #
+    # @note Timeout is in milliseconds.
+    #
+    # @example
+    #   query = KubeMQ::CQ::QueryMessage.new(
+    #     channel: "queries.users",
+    #     body: '{"user_id": 42}',
+    #     timeout: 10_000,
+    #     cache_key: "user-42",
+    #     cache_ttl: 60_000
+    #   )
+    #   response = client.send_query(query)
+    #   puts "Data: #{response.body} (cache_hit=#{response.cache_hit})"
+    #
+    # @see CQ::QueryMessage
+    # @see CQ::QueryResponse
+    def send_query(message)
+      Validator.validate_channel!(message.channel, allow_wildcards: false)
+      Validator.validate_content!(message.metadata, message.body)
+      Validator.validate_timeout!(message.timeout)
+      Validator.validate_cache!(message.cache_key, message.cache_ttl) if message.cache_key
+      ensure_connected!
+
+      proto = Transport::Converter.request_to_proto(message, @config.client_id, RequestType::QUERY)
+      response = @transport.kubemq_client.send_request(proto)
+      hash = Transport::Converter.proto_to_query_response(response)
+      CQ::QueryResponse.new(**hash)
+    end
+
+    # Subscribes to incoming queries on a channel. Runs on a background
+    # thread; incoming queries are delivered to the provided block.
+    #
+    # The block should process the query and send a response via
+    # {#send_response}. The subscription auto-reconnects with exponential
+    # backoff on transient failures.
+    #
+    # @param subscription [CQ::QueriesSubscription] channel and group config
+    # @param cancellation_token [CancellationToken, nil] token for cooperative
+    #   cancellation (auto-created if nil)
+    # @param on_error [Proc, nil] callback receiving {Error} on stream or
+    #   callback failures
+    # @yield [query] called for each received query on a background thread
+    # @yieldparam query [CQ::QueryReceived] the received query
+    #
+    # @return [Subscription] handle to check status, cancel, or join
+    #
+    # @raise [ArgumentError] if no block is given
+    # @raise [ValidationError] if the subscription channel is invalid
+    # @raise [ClientClosedError] if the client has been closed
+    #
+    # @note Wildcard channels are NOT supported for queries.
+    #
+    # @example
+    #   token = KubeMQ::CancellationToken.new
+    #   sub = KubeMQ::CQ::QueriesSubscription.new(channel: "queries.users")
+    #   client.subscribe_to_queries(sub, cancellation_token: token) do |query|
+    #     client.send_response(
+    #       KubeMQ::CQ::QueryResponseMessage.new(
+    #         request_id: query.id,
+    #         reply_channel: query.reply_channel,
+    #         body: '{"name": "Alice"}',
+    #         executed: true
+    #       )
+    #     )
+    #   end
+    #
+    # @see CQ::QueriesSubscription
+    # @see CQ::QueryReceived
+    # @see #send_response
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- subscription with auto-reconnect loop
+    def subscribe_to_queries(subscription, cancellation_token: nil, on_error: nil, &block)
+      raise ArgumentError, 'Block required for subscribe_to_queries' unless block
+
+      Validator.validate_channel!(subscription.channel, allow_wildcards: false)
+      ensure_connected!
+
+      cancellation_token ||= CancellationToken.new
+      nil
+
+      thread = Thread.new do
+        @transport.register_subscription(Thread.current)
+        Thread.current[:cancellation_token] = cancellation_token
+        reconnect_attempts = 0
+        begin
+          loop do
+            break if cancellation_token.cancelled?
+
+            begin
+              @transport.ensure_connected!
+              proto_sub = Transport::Converter.subscribe_to_proto(subscription, @config.client_id)
+              stream = @transport.kubemq_client.subscribe_to_requests(proto_sub)
+              Thread.current[:grpc_call] = stream
+              reconnect_attempts = 0
+              stream.each do |request|
+                break if cancellation_token.cancelled?
+
+                received = CQ::QueryReceived.new(
+                  id: request.RequestID,
+                  channel: request.Channel,
+                  metadata: request.Metadata,
+                  body: request.Body,
+                  reply_channel: request.ReplyChannel,
+                  tags: request.Tags.to_h,
+                  timeout: request.Timeout,
+                  client_id: request.ClientID
+                )
+                begin
+                  block.call(received)
+                rescue StandardError => e
+                  begin
+                    on_error&.call(Error.new("Callback error: #{e.message}", code: ErrorCode::CALLBACK_ERROR))
+                  rescue StandardError => nested
+                    Kernel.warn("[kubemq] on_error callback raised: #{nested.message}")
+                  end
+                end
+              end
+            rescue CancellationError
+              break
+            rescue GRPC::BadStatus, StandardError => e
+              @transport.on_disconnect! if e.is_a?(GRPC::Unavailable) || e.is_a?(GRPC::DeadlineExceeded)
+              reconnect_attempts += 1
+              begin
+                if e.is_a?(GRPC::BadStatus)
+                  on_error&.call(ErrorMapper.map_grpc_error(e, operation: 'subscribe_queries'))
+                else
+                  on_error&.call(Error.new(e.message, code: ErrorCode::STREAM_BROKEN))
+                end
+              rescue StandardError => cb_err
+                Kernel.warn("[kubemq] on_error callback raised: #{cb_err.message}")
+              end
+              delay = [@config.reconnect_policy.base_interval *
+                (@config.reconnect_policy.multiplier**(reconnect_attempts - 1)),
+                       @config.reconnect_policy.max_delay].min
+              sleep(delay) unless cancellation_token.cancelled?
+            end
+          end
+        rescue StandardError => e
+          Thread.current[:kubemq_subscription]&.mark_error(e)
+        ensure
+          begin; Thread.current[:grpc_call]&.cancel; rescue StandardError; end
+          Thread.current[:kubemq_subscription]&.mark_closed
+          @transport.unregister_subscription(Thread.current)
+        end
+      end
+
+      sub_wrapper = KubeMQ::Subscription.new(thread: thread, cancellation_token: cancellation_token)
+      thread[:kubemq_subscription] = sub_wrapper
+      sub_wrapper
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    # --- Channel Management Convenience ---
+
+    # Creates a commands channel on the broker.
+    #
+    # @param channel_name [String] name for the new channel
+    # @return [Boolean] +true+ on success
+    # @raise [ClientClosedError] if the client has been closed
+    # @raise [ChannelError] if the broker rejects the operation
+    # @see BaseClient#create_channel
+    def create_commands_channel(channel_name:)
+      create_channel(channel_name: channel_name, channel_type: ChannelType::COMMANDS)
+    end
+
+    # Creates a queries channel on the broker.
+    #
+    # @param channel_name [String] name for the new channel
+    # @return [Boolean] +true+ on success
+    # @raise [ClientClosedError] if the client has been closed
+    # @raise [ChannelError] if the broker rejects the operation
+    # @see BaseClient#create_channel
+    def create_queries_channel(channel_name:)
+      create_channel(channel_name: channel_name, channel_type: ChannelType::QUERIES)
+    end
+
+    # Deletes a commands channel from the broker.
+    #
+    # @param channel_name [String] name of the channel to delete
+    # @return [Boolean] +true+ on success
+    # @raise [ClientClosedError] if the client has been closed
+    # @raise [ChannelError] if the broker rejects the operation
+    # @see BaseClient#delete_channel
+    def delete_commands_channel(channel_name:)
+      delete_channel(channel_name: channel_name, channel_type: ChannelType::COMMANDS)
+    end
+
+    # Deletes a queries channel from the broker.
+    #
+    # @param channel_name [String] name of the channel to delete
+    # @return [Boolean] +true+ on success
+    # @raise [ClientClosedError] if the client has been closed
+    # @raise [ChannelError] if the broker rejects the operation
+    # @see BaseClient#delete_channel
+    def delete_queries_channel(channel_name:)
+      delete_channel(channel_name: channel_name, channel_type: ChannelType::QUERIES)
+    end
+
+    # Lists commands channels, with optional name filtering.
+    #
+    # @param search [String, nil] substring filter for channel names
+    # @return [Array<ChannelInfo>] matching channels with metadata
+    # @raise [ClientClosedError] if the client has been closed
+    # @see BaseClient#list_channels
+    def list_commands_channels(search: nil)
+      list_channels(channel_type: ChannelType::COMMANDS, search: search)
+    end
+
+    # Lists queries channels, with optional name filtering.
+    #
+    # @param search [String, nil] substring filter for channel names
+    # @return [Array<ChannelInfo>] matching channels with metadata
+    # @raise [ClientClosedError] if the client has been closed
+    # @see BaseClient#list_channels
+    def list_queries_channels(search: nil)
+      list_channels(channel_type: ChannelType::QUERIES, search: search)
+    end
+  end
+end

data/lib/kubemq/cq/command_message.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module KubeMQ
+  module CQ
+    # Outbound command message for the request/reply (fire-and-confirm) pattern.
+    #
+    # Construct a +CommandMessage+ and pass it to {CQClient#send_command}.
+    # The broker forwards the command to a subscriber and returns a
+    # {CommandResponse} indicating whether it was executed.
+    #
+    # @example
+    #   cmd = KubeMQ::CQ::CommandMessage.new(
+    #     channel: "commands.user.create",
+    #     timeout: 5000,
+    #     metadata: "create-user",
+    #     body: '{"name": "Alice"}',
+    #     tags: { "source" => "api" }
+    #   )
+    #   response = client.send_command(cmd)
+    #   puts "Executed: #{response.executed}"
+    #
+    # @see CQClient#send_command
+    # @see CommandResponse
+    class CommandMessage
+      # @!attribute [rw] id
+      #   @return [String] unique message identifier (auto-generated UUID if not provided)
+      # @!attribute [rw] channel
+      #   @return [String] target channel name
+      # @!attribute [rw] metadata
+      #   @return [String, nil] arbitrary metadata string
+      # @!attribute [rw] body
+      #   @return [String, nil] message payload (binary-safe)
+      # @!attribute [rw] tags
+      #   @return [Hash{String => String}] user-defined key-value tags
+      # @!attribute [rw] timeout
+      #   @return [Integer] maximum time to wait for a response
+      #   @note Timeout is in milliseconds
+      attr_accessor :id, :channel, :metadata, :body, :tags, :timeout
+
+      # @param channel [String] target channel name (required)
+      # @param timeout [Integer] response timeout in milliseconds (required)
+      # @param metadata [String, nil] arbitrary metadata
+      # @param body [String, nil] message payload
+      # @param tags [Hash{String => String}, nil] key-value tags (default: +{}+)
+      # @param id [String, nil] message ID (default: auto-generated UUID)
+      # @note +timeout+ is in milliseconds
+      def initialize(channel:, timeout:, metadata: nil, body: nil, tags: nil, id: nil)
+        @id = id || SecureRandom.uuid
+        @channel = channel
+        @timeout = timeout
+        @metadata = metadata
+        @body = body
+        @tags = tags || {}
+      end
+    end
+  end
+end

data/lib/kubemq/cq/command_received.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  module CQ
+    # A command received by a subscriber via {CQClient#subscribe_to_commands}.
+    #
+    # After processing, use the {#reply_channel} and {#id} to construct a
+    # {CommandResponseMessage} and send it back via {CQClient#send_response}.
+    #
+    # @see CQClient#subscribe_to_commands
+    # @see CommandResponseMessage
+    # @see CQClient#send_response
+    class CommandReceived
+      # @!attribute [r] id
+      #   @return [String] request identifier (use as +request_id+ in the response)
+      # @!attribute [r] channel
+      #   @return [String] the channel the command was sent to
+      # @!attribute [r] metadata
+      #   @return [String] command metadata
+      # @!attribute [r] body
+      #   @return [String] command payload (binary)
+      # @!attribute [r] reply_channel
+      #   @return [String] channel to send the response back on
+      # @!attribute [r] tags
+      #   @return [Hash{String => String}] user-defined key-value tags
+      # @!attribute [r] timeout
+      #   @return [Integer] original timeout from the sender (milliseconds)
+      # @!attribute [r] client_id
+      #   @return [String, nil] the sender's client identifier
+      attr_reader :id, :channel, :metadata, :body, :reply_channel, :tags, :timeout, :client_id
+
+      # @param id [String] request identifier
+      # @param channel [String] source channel name
+      # @param metadata [String] command metadata
+      # @param body [String] command payload
+      # @param reply_channel [String] response channel
+      # @param tags [Hash{String => String}, nil] key-value tags
+      # @param timeout [Integer] sender timeout in milliseconds (default: +0+)
+      # @param client_id [String, nil] sender's client ID
+      def initialize(id:, channel:, metadata:, body:, reply_channel:, tags:, timeout: 0, client_id: nil, **_)
+        @id = id
+        @channel = channel
+        @metadata = metadata
+        @body = body
+        @reply_channel = reply_channel
+        @tags = tags || {}
+        @timeout = timeout
+        @client_id = client_id
+      end
+    end
+  end
+end

data/lib/kubemq/cq/command_response.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  module CQ
+    # Response returned by {CQClient#send_command} after a subscriber
+    # processes the command.
+    #
+    # Check {#executed} to confirm the command was handled successfully.
+    # If +executed+ is +false+, inspect {#error} for the reason.
+    #
+    # @see CQClient#send_command
+    # @see CommandMessage
+    class CommandResponse
+      # @!attribute [r] client_id
+      #   @return [String] the responder's client identifier
+      # @!attribute [r] request_id
+      #   @return [String] the original command request identifier
+      # @!attribute [r] executed
+      #   @return [Boolean] +true+ if the command was executed successfully
+      # @!attribute [r] error
+      #   @return [String, nil] error description if execution failed
+      # @!attribute [r] timestamp
+      #   @return [Integer] broker-assigned response timestamp (Unix nanoseconds)
+      # @!attribute [r] tags
+      #   @return [Hash{String => String}] user-defined key-value tags
+      attr_reader :client_id, :request_id, :executed, :error, :timestamp, :tags
+
+      # @param client_id [String] responder's client ID
+      # @param request_id [String] original request ID
+      # @param executed [Boolean] whether the command was executed
+      # @param error [String, nil] error description on failure
+      # @param timestamp [Integer] response timestamp (default: +0+)
+      # @param tags [Hash{String => String}, nil] key-value tags
+      def initialize(client_id:, request_id:, executed:, error: nil, timestamp: 0, tags: nil)
+        @client_id = client_id
+        @request_id = request_id
+        @executed = executed
+        @error = error
+        @timestamp = timestamp
+        @tags = tags || {}
+      end
+    end
+  end
+end

data/lib/kubemq/cq/command_response_message.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  module CQ
+    # Outbound response to a received command, sent via {CQClient#send_response}.
+    #
+    # Construct from the fields of a {CommandReceived} — copy +id+ to
+    # +request_id+ and +reply_channel+ — then set {#executed} and
+    # optionally {#error}.
+    #
+    # @example Respond to a command
+    #   response_msg = KubeMQ::CQ::CommandResponseMessage.new(
+    #     request_id: received_cmd.id,
+    #     reply_channel: received_cmd.reply_channel,
+    #     executed: true
+    #   )
+    #   client.send_response(response_msg)
+    #
+    # @see CQClient#send_response
+    # @see CommandReceived
+    class CommandResponseMessage
+      # @!attribute [rw] request_id
+      #   @return [String] the original command's request identifier
+      # @!attribute [rw] reply_channel
+      #   @return [String] the channel to send the response on
+      # @!attribute [rw] client_id
+      #   @return [String, nil] responder's client identifier
+      # @!attribute [rw] executed
+      #   @return [Boolean] whether the command was executed successfully
+      # @!attribute [rw] error
+      #   @return [String, nil] error description if execution failed
+      # @!attribute [rw] metadata
+      #   @return [String, nil] response metadata
+      # @!attribute [rw] tags
+      #   @return [Hash{String => String}] user-defined key-value tags
+      attr_accessor :request_id, :reply_channel, :client_id, :executed,
+                    :error, :metadata, :tags
+
+      # @param request_id [String] the original command's request ID (required)
+      # @param reply_channel [String] response channel from {CommandReceived#reply_channel} (required)
+      # @param executed [Boolean] whether the command was executed (required)
+      # @param error [String, nil] error description on failure
+      # @param metadata [String, nil] response metadata
+      # @param tags [Hash{String => String}, nil] key-value tags
+      # @param client_id [String, nil] responder's client ID
+      def initialize(request_id:, reply_channel:, executed:, error: nil, metadata: nil, tags: nil,
+                     client_id: nil)
+        @request_id = request_id
+        @reply_channel = reply_channel
+        @executed = executed
+        @error = error
+        @metadata = metadata
+        @tags = tags || {}
+        @client_id = client_id
+      end
+    end
+  end
+end