kubemq 1.0.0

data/lib/kubemq/cq/commands_subscription.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  module CQ
+    # Configuration for subscribing to command requests.
+    #
+    # Pass to {CQClient#subscribe_to_commands} along with a block to
+    # receive {CommandReceived} messages. Use {#group} for load-balanced
+    # delivery across multiple responders.
+    #
+    # @example
+    #   sub = KubeMQ::CQ::CommandsSubscription.new(
+    #     channel: "commands.user.create",
+    #     group: "user-service"
+    #   )
+    #   client.subscribe_to_commands(sub) do |cmd|
+    #     # process and respond
+    #   end
+    #
+    # @see CQClient#subscribe_to_commands
+    # @see CommandReceived
+    class CommandsSubscription
+      # @!attribute [rw] channel
+      #   @return [String] channel name to subscribe to
+      # @!attribute [rw] group
+      #   @return [String, nil] consumer group for load-balanced delivery
+      attr_accessor :channel, :group
+
+      # @param channel [String] channel name (required)
+      # @param group [String, nil] consumer group name (default: +nil+)
+      def initialize(channel:, group: nil)
+        @channel = channel
+        @group = group
+      end
+
+      # Returns the subscribe type constant for the transport layer.
+      #
+      # @return [Integer] {SubscribeType::COMMANDS}
+      # @api private
+      def subscribe_type
+        SubscribeType::COMMANDS
+      end
+    end
+  end
+end

data/lib/kubemq/cq/queries_subscription.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  module CQ
+    # Configuration for subscribing to query requests.
+    #
+    # Pass to {CQClient#subscribe_to_queries} along with a block to
+    # receive {QueryReceived} messages. Use {#group} for load-balanced
+    # delivery across multiple responders.
+    #
+    # @example
+    #   sub = KubeMQ::CQ::QueriesSubscription.new(
+    #     channel: "queries.user.get",
+    #     group: "user-service"
+    #   )
+    #   client.subscribe_to_queries(sub) do |query|
+    #     # process and respond
+    #   end
+    #
+    # @see CQClient#subscribe_to_queries
+    # @see QueryReceived
+    class QueriesSubscription
+      # @!attribute [rw] channel
+      #   @return [String] channel name to subscribe to
+      # @!attribute [rw] group
+      #   @return [String, nil] consumer group for load-balanced delivery
+      attr_accessor :channel, :group
+
+      # @param channel [String] channel name (required)
+      # @param group [String, nil] consumer group name (default: +nil+)
+      def initialize(channel:, group: nil)
+        @channel = channel
+        @group = group
+      end
+
+      # Returns the subscribe type constant for the transport layer.
+      #
+      # @return [Integer] {SubscribeType::QUERIES}
+      # @api private
+      def subscribe_type
+        SubscribeType::QUERIES
+      end
+    end
+  end
+end

data/lib/kubemq/cq/query_message.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module KubeMQ
+  module CQ
+    # Outbound query message for the request/reply (with data) pattern.
+    #
+    # Construct a +QueryMessage+ and pass it to {CQClient#send_query}.
+    # The broker forwards the query to a subscriber and returns a
+    # {QueryResponse} containing the response data. Optionally set
+    # {#cache_key} and {#cache_ttl} for server-side response caching.
+    #
+    # @example
+    #   query = KubeMQ::CQ::QueryMessage.new(
+    #     channel: "queries.user.get",
+    #     timeout: 10_000,
+    #     metadata: "get-user",
+    #     body: '{"user_id": 42}',
+    #     cache_key: "user:42",
+    #     cache_ttl: 60
+    #   )
+    #   response = client.send_query(query)
+    #   puts "Result: #{response.body}, cached: #{response.cache_hit}"
+    #
+    # @see CQClient#send_query
+    # @see QueryResponse
+    class QueryMessage
+      # @!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
+      # @!attribute [rw] cache_key
+      #   @return [String, nil] cache key for server-side response caching
+      # @!attribute [rw] cache_ttl
+      #   @return [Integer, nil] cache TTL in seconds
+      attr_accessor :id, :channel, :metadata, :body, :tags, :timeout, :cache_key, :cache_ttl
+
+      # @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)
+      # @param cache_key [String, nil] server-side cache key
+      # @param cache_ttl [Integer, nil] cache TTL in seconds
+      # @note +timeout+ is in milliseconds
+      def initialize(channel:, timeout:, metadata: nil, body: nil, tags: nil, id: nil,
+                     cache_key: nil, cache_ttl: nil)
+        @id = id || SecureRandom.uuid
+        @channel = channel
+        @timeout = timeout
+        @metadata = metadata
+        @body = body
+        @tags = tags || {}
+        @cache_key = cache_key
+        @cache_ttl = cache_ttl
+      end
+    end
+  end
+end

data/lib/kubemq/cq/query_received.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  module CQ
+    # A query received by a subscriber via {CQClient#subscribe_to_queries}.
+    #
+    # After processing, use the {#reply_channel} and {#id} to construct a
+    # {QueryResponseMessage} and send it back via {CQClient#send_response}.
+    #
+    # @see CQClient#subscribe_to_queries
+    # @see QueryResponseMessage
+    # @see CQClient#send_response
+    class QueryReceived
+      # @!attribute [r] id
+      #   @return [String] request identifier (use as +request_id+ in the response)
+      # @!attribute [r] channel
+      #   @return [String] the channel the query was sent to
+      # @!attribute [r] metadata
+      #   @return [String] query metadata
+      # @!attribute [r] body
+      #   @return [String] query 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] query metadata
+      # @param body [String] query 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/query_response.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  module CQ
+    # Response returned by {CQClient#send_query} after a subscriber
+    # processes the query.
+    #
+    # Contains the response {#body} and {#metadata}, plus a {#cache_hit}
+    # flag indicating whether the response was served from the broker's
+    # server-side cache.
+    #
+    # @see CQClient#send_query
+    # @see QueryMessage
+    class QueryResponse
+      # @!attribute [r] client_id
+      #   @return [String] the responder's client identifier
+      # @!attribute [r] request_id
+      #   @return [String] the original query request identifier
+      # @!attribute [r] executed
+      #   @return [Boolean] +true+ if the query 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
+      # @!attribute [r] body
+      #   @return [String, nil] response payload
+      # @!attribute [r] metadata
+      #   @return [String, nil] response metadata
+      # @!attribute [r] cache_hit
+      #   @return [Boolean] +true+ if the response was served from cache
+      attr_reader :client_id, :request_id, :executed, :error, :timestamp,
+                  :tags, :body, :metadata, :cache_hit
+
+      # @param client_id [String] responder's client ID
+      # @param request_id [String] original request ID
+      # @param executed [Boolean] whether the query 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
+      # @param body [String, nil] response payload
+      # @param metadata [String, nil] response metadata
+      # @param cache_hit [Boolean] whether served from cache (default: +false+)
+      def initialize(client_id:, request_id:, executed:, error: nil, timestamp: 0,
+                     tags: nil, body: nil, metadata: nil, cache_hit: false)
+        @client_id = client_id
+        @request_id = request_id
+        @executed = executed
+        @error = error
+        @timestamp = timestamp
+        @tags = tags || {}
+        @body = body
+        @metadata = metadata
+        @cache_hit = cache_hit
+      end
+    end
+  end
+end

data/lib/kubemq/cq/query_response_message.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  module CQ
+    # Outbound response to a received query, sent via {CQClient#send_response}.
+    #
+    # Construct from the fields of a {QueryReceived} — copy +id+ to
+    # +request_id+ and +reply_channel+ — then set {#executed}, {#body},
+    # and optionally {#cache_hit}.
+    #
+    # @example Respond to a query
+    #   response_msg = KubeMQ::CQ::QueryResponseMessage.new(
+    #     request_id: received_query.id,
+    #     reply_channel: received_query.reply_channel,
+    #     executed: true,
+    #     body: '{"name": "Alice", "age": 30}'
+    #   )
+    #   client.send_response(response_msg)
+    #
+    # @see CQClient#send_response
+    # @see QueryReceived
+    class QueryResponseMessage
+      # @!attribute [rw] request_id
+      #   @return [String] the original query'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 query was executed successfully
+      # @!attribute [rw] error
+      #   @return [String, nil] error description if execution failed
+      # @!attribute [rw] body
+      #   @return [String, nil] response payload
+      # @!attribute [rw] metadata
+      #   @return [String, nil] response metadata
+      # @!attribute [rw] tags
+      #   @return [Hash{String => String}] user-defined key-value tags
+      # @!attribute [rw] cache_hit
+      #   @return [Boolean] whether this response should be cached
+      attr_accessor :request_id, :reply_channel, :client_id, :executed,
+                    :error, :body, :metadata, :tags, :cache_hit
+
+      # @param request_id [String] the original query's request ID (required)
+      # @param reply_channel [String] response channel from {QueryReceived#reply_channel} (required)
+      # @param executed [Boolean] whether the query was executed (required)
+      # @param error [String, nil] error description on failure
+      # @param body [String, nil] response payload
+      # @param metadata [String, nil] response metadata
+      # @param tags [Hash{String => String}, nil] key-value tags
+      # @param client_id [String, nil] responder's client ID
+      # @param cache_hit [Boolean] whether this response is from cache (default: +false+)
+      def initialize(request_id:, reply_channel:, executed:, error: nil, body: nil,
+                     metadata: nil, tags: nil, client_id: nil, cache_hit: false)
+        @request_id = request_id
+        @reply_channel = reply_channel
+        @executed = executed
+        @error = error
+        @body = body
+        @metadata = metadata
+        @tags = tags || {}
+        @client_id = client_id
+        @cache_hit = cache_hit
+      end
+    end
+  end
+end

data/lib/kubemq/error_codes.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module KubeMQ
+  # Enumeration of SDK error codes used in {Error#code}.
+  #
+  # Each code maps to an {ErrorCategory} and retryable flag via {ERROR_CLASSIFICATION},
+  # and to an actionable suggestion via {ERROR_SUGGESTIONS}.
+  #
+  # @see Error
+  # @see ErrorCategory
+  # @see ERROR_CLASSIFICATION
+  module ErrorCode
+    # gRPC connection timed out or deadline exceeded.
+    CONNECTION_TIMEOUT = 'CONNECTION_TIMEOUT'
+    # Broker is unreachable — network, DNS, or firewall issue.
+    UNAVAILABLE = 'UNAVAILABLE'
+    # Transport exists but is not in the READY state.
+    CONNECTION_NOT_READY = 'CONNECTION_NOT_READY'
+    # Authentication token is invalid, expired, or missing.
+    AUTH_FAILED = 'AUTH_FAILED'
+    # Authenticated but lacking required permissions.
+    PERMISSION_DENIED = 'PERMISSION_DENIED'
+    # Request parameters failed validation.
+    VALIDATION_ERROR = 'VALIDATION_ERROR'
+    # Resource (channel, queue) already exists.
+    ALREADY_EXISTS = 'ALREADY_EXISTS'
+    # Sequence number or offset is out of valid range.
+    OUT_OF_RANGE = 'OUT_OF_RANGE'
+    # Requested channel or resource does not exist.
+    NOT_FOUND = 'NOT_FOUND'
+    # Broker rate limit or resource quota exceeded.
+    RESOURCE_EXHAUSTED = 'RESOURCE_EXHAUSTED'
+    # Operation aborted due to a conflict (e.g., transaction contention).
+    ABORTED = 'ABORTED'
+    # Internal broker error — check server logs.
+    INTERNAL = 'INTERNAL'
+    # Unknown error — check server logs.
+    UNKNOWN = 'UNKNOWN'
+    # Operation not supported by the broker version.
+    UNIMPLEMENTED = 'UNIMPLEMENTED'
+    # Unrecoverable data loss at the broker.
+    DATA_LOSS = 'DATA_LOSS'
+    # Operation was cooperatively cancelled via {CancellationToken}.
+    CANCELLED = 'CANCELLED'
+    # Reconnect message buffer is full; oldest messages dropped.
+    BUFFER_FULL = 'BUFFER_FULL'
+    # A bidirectional gRPC stream broke unexpectedly.
+    STREAM_BROKEN = 'STREAM_BROKEN'
+    # Client has been closed; create a new instance.
+    CLIENT_CLOSED = 'CLIENT_CLOSED'
+    # Invalid client configuration (address, TLS, etc.).
+    CONFIGURATION_ERROR = 'CONFIGURATION_ERROR'
+    # A user-provided callback raised an exception.
+    CALLBACK_ERROR = 'CALLBACK_ERROR'
+  end
+
+  # Categories for classifying {ErrorCode} values by failure domain.
+  #
+  # Used by {KubeMQ.classify_error} to determine error handling strategy.
+  #
+  # @see ERROR_CLASSIFICATION
+  # @see KubeMQ.classify_error
+  module ErrorCategory
+    # Temporary failure that may resolve on retry (e.g., network blip).
+    TRANSIENT = 'TRANSIENT'
+    # Operation exceeded its deadline.
+    TIMEOUT = 'TIMEOUT'
+    # Rate limit or resource quota exceeded.
+    THROTTLING = 'THROTTLING'
+    # Invalid or missing authentication credentials.
+    AUTHENTICATION = 'AUTHENTICATION'
+    # Valid credentials but insufficient permissions.
+    AUTHORIZATION = 'AUTHORIZATION'
+    # Invalid request parameters or preconditions not met.
+    VALIDATION = 'VALIDATION'
+    # Requested resource does not exist.
+    NOT_FOUND = 'NOT_FOUND'
+    # Unrecoverable error — requires operator intervention.
+    FATAL = 'FATAL'
+    # Operation was intentionally cancelled.
+    CANCELLATION = 'CANCELLATION'
+    # Client-side buffer overflow during disconnection.
+    BACKPRESSURE = 'BACKPRESSURE'
+    # Error in user-provided callback code.
+    RUNTIME = 'RUNTIME'
+  end
+
+  # Maps each {ErrorCode} to its {ErrorCategory} and retryable flag.
+  #
+  # Each entry is +[category, retryable]+ where +category+ is an
+  # {ErrorCategory} constant and +retryable+ is a Boolean.
+  #
+  # @return [Hash{String => Array(String, Boolean)}]
+  #
+  # @see ErrorCode
+  # @see ErrorCategory
+  ERROR_CLASSIFICATION = {
+    ErrorCode::UNAVAILABLE => [ErrorCategory::TRANSIENT, true],
+    ErrorCode::ABORTED => [ErrorCategory::TRANSIENT, true],
+    ErrorCode::CONNECTION_TIMEOUT => [ErrorCategory::TIMEOUT, true],
+    ErrorCode::RESOURCE_EXHAUSTED => [ErrorCategory::THROTTLING, true],
+    ErrorCode::AUTH_FAILED => [ErrorCategory::AUTHENTICATION, false],
+    ErrorCode::PERMISSION_DENIED => [ErrorCategory::AUTHORIZATION, false],
+    ErrorCode::VALIDATION_ERROR => [ErrorCategory::VALIDATION, false],
+    ErrorCode::ALREADY_EXISTS => [ErrorCategory::VALIDATION, false],
+    ErrorCode::OUT_OF_RANGE => [ErrorCategory::VALIDATION, false],
+    ErrorCode::NOT_FOUND => [ErrorCategory::NOT_FOUND, false],
+    ErrorCode::INTERNAL => [ErrorCategory::FATAL, false],
+    ErrorCode::UNKNOWN => [ErrorCategory::TRANSIENT, true],
+    ErrorCode::UNIMPLEMENTED => [ErrorCategory::FATAL, false],
+    ErrorCode::DATA_LOSS => [ErrorCategory::FATAL, false],
+    ErrorCode::CANCELLED => [ErrorCategory::CANCELLATION, false],
+    ErrorCode::BUFFER_FULL => [ErrorCategory::BACKPRESSURE, false],
+    ErrorCode::STREAM_BROKEN => [ErrorCategory::TRANSIENT, true],
+    ErrorCode::CLIENT_CLOSED => [ErrorCategory::FATAL, false],
+    ErrorCode::CONNECTION_NOT_READY => [ErrorCategory::TRANSIENT, true],
+    ErrorCode::CONFIGURATION_ERROR => [ErrorCategory::VALIDATION, false],
+    ErrorCode::CALLBACK_ERROR => [ErrorCategory::RUNTIME, false]
+  }.freeze
+
+  # Maps each {ErrorCode} to a human-readable recovery suggestion.
+  #
+  # Used by {ErrorMapper} to populate {Error#suggestion} and by
+  # {KubeMQ.suggestion_for} for programmatic lookup.
+  #
+  # @return [Hash{String => String}]
+  #
+  # @see Error#suggestion
+  ERROR_SUGGESTIONS = {
+    ErrorCode::UNAVAILABLE => 'Check server connectivity and firewall rules.',
+    ErrorCode::AUTH_FAILED => 'Verify auth token is valid and not expired.',
+    ErrorCode::PERMISSION_DENIED => 'Verify credentials have required permissions.',
+    ErrorCode::NOT_FOUND => 'Verify channel/queue exists or create it first.',
+    ErrorCode::VALIDATION_ERROR => 'Check request parameters.',
+    ErrorCode::ALREADY_EXISTS => 'Resource already exists.',
+    ErrorCode::CONNECTION_TIMEOUT => 'Increase timeout or check server load.',
+    ErrorCode::RESOURCE_EXHAUSTED => 'Reduce send rate or increase server capacity.',
+    ErrorCode::BUFFER_FULL => 'Wait for connection to recover or increase buffer_size.',
+    ErrorCode::STREAM_BROKEN => 'Subscriptions will attempt to reconnect automatically. Stream senders must be recreated.',
+    ErrorCode::CLIENT_CLOSED => 'The client has been closed. Create a new client instance.',
+    ErrorCode::INTERNAL => 'Internal server error. Check server logs.',
+    ErrorCode::UNKNOWN => 'An unknown error occurred. Check server logs.',
+    ErrorCode::CONFIGURATION_ERROR => 'Check client configuration: address, TLS settings, credentials.',
+    ErrorCode::CANCELLED => 'The operation was cancelled.',
+    ErrorCode::UNIMPLEMENTED => 'Operation not supported. Check server version.',
+    ErrorCode::DATA_LOSS => 'Unrecoverable data loss. Check server storage.',
+    ErrorCode::OUT_OF_RANGE => 'Check pagination parameters or sequence numbers.',
+    ErrorCode::ABORTED => 'Operation aborted due to conflict. Retry may succeed.',
+    ErrorCode::CONNECTION_NOT_READY => 'Wait for the client to connect or check server availability.',
+    ErrorCode::CALLBACK_ERROR => 'A user callback raised an exception. Fix the callback code.'
+  }.freeze
+
+  # Classifies an error by its {ErrorCode} into a category and retryable flag.
+  #
+  # @param error [Error] an error with a +code+ attribute
+  #
+  # @return [Array(String, Boolean)] +[category, retryable]+ from {ERROR_CLASSIFICATION};
+  #   defaults to +[ErrorCategory::FATAL, false]+ for unknown codes
+  #
+  # @example
+  #   category, retryable = KubeMQ.classify_error(error)
+  #   retry if retryable
+  def self.classify_error(error)
+    return [ErrorCategory::FATAL, false] unless error.respond_to?(:code) && error.code
+
+    ERROR_CLASSIFICATION.fetch(error.code, [ErrorCategory::FATAL, false])
+  end
+
+  # Returns the recovery suggestion for a given error code.
+  #
+  # @param code [String] an {ErrorCode} constant value
+  #
+  # @return [String, nil] actionable suggestion, or +nil+ if the code is unknown
+  #
+  # @example
+  #   KubeMQ.suggestion_for(KubeMQ::ErrorCode::UNAVAILABLE)
+  #   # => "Check server connectivity and firewall rules."
+  def self.suggestion_for(code)
+    ERROR_SUGGESTIONS[code]
+  end
+end

data/lib/kubemq/errors/error_mapper.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'grpc'
+
+module KubeMQ
+  # Maps gRPC +GRPC::BadStatus+ exceptions to typed {Error} subclasses.
+  #
+  # Used internally by {Interceptors::ErrorMappingInterceptor} and subscription
+  # reconnect loops. Application code should rescue {Error} subclasses rather
+  # than raw gRPC exceptions.
+  #
+  # ## gRPC Status Code Mapping
+  #
+  # | gRPC Code | SDK Exception | Error Code | Retryable? |
+  # |-----------|--------------|------------|:----------:|
+  # | CANCELLED | {CancellationError} | CANCELLED | No |
+  # | UNKNOWN | {Error} | UNKNOWN | Yes |
+  # | INVALID_ARGUMENT | {ValidationError} | VALIDATION_ERROR | No |
+  # | DEADLINE_EXCEEDED | {TimeoutError} | CONNECTION_TIMEOUT | Yes |
+  # | NOT_FOUND | {ChannelError} | NOT_FOUND | No |
+  # | ALREADY_EXISTS | {ValidationError} | ALREADY_EXISTS | No |
+  # | PERMISSION_DENIED | {AuthenticationError} | PERMISSION_DENIED | No |
+  # | RESOURCE_EXHAUSTED | {MessageError} | RESOURCE_EXHAUSTED | Yes |
+  # | FAILED_PRECONDITION | {ValidationError} | VALIDATION_ERROR | No |
+  # | ABORTED | {TransactionError} | ABORTED | Yes |
+  # | OUT_OF_RANGE | {ValidationError} | OUT_OF_RANGE | No |
+  # | UNIMPLEMENTED | {Error} | UNIMPLEMENTED | No |
+  # | INTERNAL | {Error} | INTERNAL | No |
+  # | UNAVAILABLE | {ConnectionError} | UNAVAILABLE | Yes |
+  # | DATA_LOSS | {Error} | DATA_LOSS | No |
+  # | UNAUTHENTICATED | {AuthenticationError} | AUTH_FAILED | No |
+  #
+  # @see Error
+  # @see ErrorCode
+  module ErrorMapper
+    # Maps gRPC status codes to +[exception_class, error_code, retryable]+ tuples.
+    #
+    # @return [Hash{Integer => Array(Class, String, Boolean)}]
+    GRPC_MAPPING = {
+      GRPC::Core::StatusCodes::CANCELLED =>
+        [CancellationError, ErrorCode::CANCELLED, false],
+      GRPC::Core::StatusCodes::UNKNOWN =>
+        [KubeMQ::Error, ErrorCode::UNKNOWN, true],
+      GRPC::Core::StatusCodes::INVALID_ARGUMENT =>
+        [ValidationError, ErrorCode::VALIDATION_ERROR, false],
+      GRPC::Core::StatusCodes::DEADLINE_EXCEEDED =>
+        [KubeMQ::TimeoutError, ErrorCode::CONNECTION_TIMEOUT, true],
+      GRPC::Core::StatusCodes::NOT_FOUND =>
+        [ChannelError, ErrorCode::NOT_FOUND, false],
+      GRPC::Core::StatusCodes::ALREADY_EXISTS =>
+        [ValidationError, ErrorCode::ALREADY_EXISTS, false],
+      GRPC::Core::StatusCodes::PERMISSION_DENIED =>
+        [AuthenticationError, ErrorCode::PERMISSION_DENIED, false],
+      GRPC::Core::StatusCodes::RESOURCE_EXHAUSTED =>
+        [MessageError, ErrorCode::RESOURCE_EXHAUSTED, true],
+      GRPC::Core::StatusCodes::FAILED_PRECONDITION =>
+        [ValidationError, ErrorCode::VALIDATION_ERROR, false],
+      GRPC::Core::StatusCodes::ABORTED =>
+        [TransactionError, ErrorCode::ABORTED, true],
+      GRPC::Core::StatusCodes::OUT_OF_RANGE =>
+        [ValidationError, ErrorCode::OUT_OF_RANGE, false],
+      GRPC::Core::StatusCodes::UNIMPLEMENTED =>
+        [KubeMQ::Error, ErrorCode::UNIMPLEMENTED, false],
+      GRPC::Core::StatusCodes::INTERNAL =>
+        [KubeMQ::Error, ErrorCode::INTERNAL, false],
+      GRPC::Core::StatusCodes::UNAVAILABLE =>
+        [ConnectionError, ErrorCode::UNAVAILABLE, true],
+      GRPC::Core::StatusCodes::DATA_LOSS =>
+        [KubeMQ::Error, ErrorCode::DATA_LOSS, false],
+      GRPC::Core::StatusCodes::UNAUTHENTICATED =>
+        [AuthenticationError, ErrorCode::AUTH_FAILED, false]
+    }.freeze
+
+    # Regex patterns for detecting credentials in error messages.
+    #
+    # @api private
+    CREDENTIAL_PATTERNS = [
+      /(?:bearer|authorization)\s*[:=]\s*\S+(?:\s+\S+)?/i,
+      /eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/
+    ].freeze
+
+    module_function
+
+    # Converts a +GRPC::BadStatus+ exception to the appropriate {Error} subclass.
+    #
+    # Credential patterns (bearer tokens, JWTs) are scrubbed from error messages
+    # before constructing the exception. Falls back to {Error} with
+    # +UNKNOWN+ code for unmapped gRPC status codes.
+    #
+    # @param error [GRPC::BadStatus] the gRPC exception to map
+    # @param operation [String, nil] the SDK operation name for context
+    #
+    # @return [Error] a typed SDK error with code, suggestion, and cause chain
+    def map_grpc_error(error, operation: nil)
+      mapping = GRPC_MAPPING[error.code]
+      unless mapping
+        return KubeMQ::Error.new(
+          scrub_credentials(error.details || error.message),
+          code: ErrorCode::UNKNOWN,
+          cause: error,
+          operation: operation
+        )
+      end
+
+      exc_class, error_code, retryable = mapping
+      suggestion = KubeMQ.suggestion_for(error_code)
+
+      exc_class.new(
+        scrub_credentials(error.details || error.message),
+        code: error_code,
+        retryable: retryable,
+        cause: error,
+        operation: operation,
+        suggestion: suggestion
+      )
+    end
+
+    # Removes credential patterns from an error message string.
+    #
+    # Matches bearer/authorization headers and JWT tokens, replacing them
+    # with +[REDACTED]+.
+    #
+    # @param text [String, nil] the text to scrub
+    #
+    # @return [String] the scrubbed text, or an empty string if +text+ is +nil+
+    def scrub_credentials(text)
+      return '' if text.nil?
+
+      result = text.to_s
+      CREDENTIAL_PATTERNS.each { |pattern| result = result.gsub(pattern, '[REDACTED]') }
+      result
+    end
+  end
+end