eh_messaging 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7f0602e56bb0054195d21d3ef88d5e9a784d7bd8462a4c0021e87c675b13687f
+  data.tar.gz: 6a2d3936b301d919f68b36043cb68681291e1e955b46bb7cb39b10c4ebc9acdb
+SHA512:
+  metadata.gz: a6dd61080c1409691c49d0d38384041b54fbdf851037b82a1c54deabfc6fea9c4f046f2895c770ae715ce9b2b39fad6ba6c36136169733278a7c2d78dd43d4f8
+  data.tar.gz: dba29ccd76b533621e61c18be2190cdc2a7bf954549eaaec04d02149ac644f136a5fe3fabd77d7e71feb3684a10cf17cfdadc35869927854feb3e8c98f056b5c

data/eh_messaging.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+require_relative "lib/eh_messaging/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "eh_messaging"
+  spec.version = EhMessaging::VERSION
+  spec.authors = ["Diego E"]
+
+  spec.summary = "Ruby library for Azure Event Hubs over the Kafka-compatible protocol"
+  spec.description = "A Ruby library for producing and consuming messages on Azure Event Hubs using its Kafka-compatible endpoint"
+  spec.required_ruby_version = ">= 3.4.0"
+
+  spec.files = Dir.chdir(__dir__) do
+    (Dir.glob("lib/**/*.rb") + Dir.glob("sig/**/*.rbs") + %w[eh_messaging.gemspec]).select { |file| File.file?(file) }
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Dependencies
+  # `logger` is no longer guaranteed to be bundled with Ruby starting with
+  # Ruby 4.0. Declare it explicitly so applications get a stable dependency.
+  spec.add_dependency "logger", ">= 1.6", "< 2.0"
+  spec.add_dependency "opentelemetry-api", ">= 1.3", "< 2.0"
+  spec.add_dependency "rdkafka", "~> 0.29.0"
+
+  # Development dependencies
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rbs", "~> 4.2"
+  spec.add_development_dependency "standard", "~> 1.43"
+  spec.add_development_dependency "steep", "~> 2.1"
+end

data/lib/eh_messaging/audit_logger.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module EhMessaging
+  class AuditLogger
+    LEVELS = {
+      "CRITICAL" => Logger::FATAL,
+      "ERROR" => Logger::ERROR,
+      "WARNING" => Logger::WARN,
+      "INFO" => Logger::INFO,
+      "DEBUG" => Logger::DEBUG
+    }.freeze
+
+    def initialize(configuration)
+      @configuration = configuration
+      @logger = configuration.logger || rails_logger || Logger.new($stdout)
+      @logger.level = LEVELS.fetch(configuration.log_level.to_s, Logger::INFO) if @logger.respond_to?(:level=)
+    end
+
+    def info(message, fields = {}) = write(:info, message, fields)
+    def warn(message, fields = {}) = write(:warn, message, fields)
+    def error(message, fields = {}) = write(:error, message, fields)
+
+    def message(event, envelope:, error: nil)
+      fields = {
+        Key: envelope.partition_key,
+        TopicName: envelope.topic,
+        Offset: envelope.offset,
+        Partition: envelope.partition,
+        EnqueuedTime: envelope.enqueued_at&.iso8601,
+        ConsumerGroup: envelope.consumer_group,
+        Error: error&.message
+      }
+      envelope.headers.each do |key, value|
+        normalized_key = key.to_s
+        field = %w[operation-id parent-id].include?(normalized_key) ? normalized_key : "Header.#{normalized_key}"
+        fields[field] = value
+      end
+      fields[:MessageBody] = envelope.payload if @configuration.log_message_body
+      public_send(error ? :error : :info, event, fields)
+    end
+
+    private
+
+    def write(level, message, fields)
+      return unless @configuration.logging
+
+      payload = fields.empty? ? message : JSON.generate({event: message}.merge(sanitize(fields)))
+      @logger.public_send(level, payload)
+    end
+
+    def sanitize(fields)
+      fields.transform_keys(&:to_s).reject do |key, _|
+        key.match?(/password|secret|token|connection|string/i)
+      end
+    end
+
+    def rails_logger
+      return unless defined?(Rails) && Rails.respond_to?(:logger)
+
+      Rails.logger
+    end
+  end
+end

data/lib/eh_messaging/client.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module EhMessaging
+  class Client
+    def initialize
+      @configuration = nil
+      @publisher = nil
+      @subscriber = nil
+      @reconsume_subscribers = []
+      @booted = false
+    end
+
+    def configure(**options, &block)
+      raise Error, "EhMessaging is already configured" if @configuration
+
+      configuration = Configuration.new
+      configuration.apply(options)
+      block&.call(configuration)
+      configuration.validate!
+      @configuration = configuration
+      @publisher = Publisher.new(configuration, logger: AuditLogger.new(configuration))
+      @reconsume_subscribers = []
+      self
+    end
+
+    def configuration = @configuration || raise(Error, "EhMessaging is not configured")
+    def publish(topic, **options) = (@publisher || raise(Error, "EhMessaging is not configured")).publish(topic, **options)
+
+    def subscribe(handler)
+      configuration
+      @subscriber ||= Subscriber.new(configuration, logger: AuditLogger.new(configuration))
+      @subscriber.subscribe(handler)
+    end
+
+    def reconsume(handler, **options)
+      configuration
+      subscriber = Subscriber.new(configuration, producer: @publisher)
+      @reconsume_subscribers << subscriber
+      subscriber.reconsume(handler, **options)
+    ensure
+      @reconsume_subscribers&.delete(subscriber)
+    end
+
+    def boot
+      configuration
+      @publisher.boot
+      @subscriber&.boot
+      @booted = true
+      self
+    end
+
+    def run
+      boot unless @booted
+      @subscriber&.run
+    ensure
+      shutdown
+    end
+
+    def shutdown
+      @subscriber&.shutdown
+      @reconsume_subscribers&.each(&:shutdown)
+      @publisher&.shutdown
+      @booted = false
+    end
+
+    def reset!
+      shutdown
+      @configuration = @publisher = @subscriber = @reconsume_subscribers = nil
+      self
+    end
+  end
+end

data/lib/eh_messaging/configuration.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module EhMessaging
+  class Configuration
+    PRODUCER_DEFAULTS = {"acks" => "all", "linger.ms" => 5, "message.send.max.retries" => 2,
+                         "request.timeout.ms" => 30_000, "batch.num.messages" => 5_000, "partitioner" => "consistent_random",
+                         "compression.type" => "none", "socket.keepalive.enable" => true, "metadata.max.age.ms" => 180_000}.freeze
+    CONSUMER_DEFAULTS = {"socket.timeout.ms" => 60_000, "session.timeout.ms" => 30_000,
+                         "heartbeat.interval.ms" => 3_000, "max.poll.interval.ms" => 300_000, "metadata.max.age.ms" => 180_000,
+                         "socket.keepalive.enable" => true, "auto.offset.reset" => "earliest",
+                         "enable.auto.commit" => true}.freeze
+    FIXED = {"enable.auto.offset.store" => true, "allow.auto.create.topics" => false}.freeze
+    AUTO_OFFSET_RESETS = %w[earliest latest error].freeze
+    LOG_LEVELS = %w[CRITICAL ERROR WARNING INFO DEBUG].freeze
+    CONNECTION_KEYS = %i[host username password protocol sasl_mechanisms].freeze
+    PRODUCER_KEYS = %i[metadata_max_age_ms message_send_max_retries request_timeout_ms socket_keepalive_enable batch_num_messages linger_ms].freeze
+    CONSUMER_KEYS = %i[socket_timeout_ms session_timeout_ms heartbeat_interval_ms max_poll_interval_ms metadata_max_age_ms socket_keepalive_enable auto_offset_reset enable_auto_commit].freeze
+    attr_accessor :application_name, :logging, :log_message_body, :poll_timeout, :log_level, :logger
+    attr_reader :brokers, :topics, :producer, :consumer
+
+    def initialize
+      @brokers, @topics = {}, {}
+      @logging, @log_message_body, @poll_timeout, @log_level = true, true, 1, "INFO"
+      @producer, @consumer = ProducerSettings.new, ConsumerSettings.new
+    end
+
+    def apply(options)
+      if options.key?(:broker)
+        raise ArgumentError, "connection_string is required with broker shorthand" unless options.key?(:connection_string)
+        broker(:default, host: options[:broker], protocol: :sasl_ssl, username: "$ConnectionString", password: options[:connection_string])
+      end
+      allowed = %i[broker connection_string application_name logging log_message_body poll_timeout log_level logger]
+      unknown = options.keys - allowed
+      raise ArgumentError, "Unknown configuration: #{unknown.join(", ")}" unless unknown.empty?
+      options.except(:broker, :connection_string).each { |key, value| public_send("#{key}=", value) }
+    end
+
+    def broker(name, **options)
+      reject_unknown(options, CONNECTION_KEYS, "broker")
+      @brokers[name.to_sym] = {name: name.to_sym}.merge(options)
+    end
+
+    def topic(name, broker: nil, side: :both, **options)
+      raise ArgumentError, "topic cannot specify both broker and host" if broker && options.key?(:host)
+      reject_unknown(options, CONNECTION_KEYS, "topic")
+      raise ArgumentError, "invalid topic side" unless %i[produce consume both].include?(side)
+      @topics[name] = {broker: broker&.to_sym, side: side, name: (broker || name).to_sym}.merge(options)
+    end
+
+    def validate!
+      raise ArgumentError, "application_name is required" if application_name.to_s.empty?
+      raise ArgumentError, "default broker is required" unless @brokers[:default]
+      @brokers.each_value do |config|
+        raise ArgumentError, "broker host is required" if config[:host].to_s.empty?
+        raise ArgumentError, "broker protocol is required" if config[:protocol].nil?
+      end
+      raise ArgumentError, "invalid log_level" unless LOG_LEVELS.include?(log_level.to_s)
+      raise ArgumentError, "poll_timeout must be positive" unless poll_timeout.is_a?(Numeric) && poll_timeout.positive?
+      raise ArgumentError, "invalid auto_offset_reset" unless AUTO_OFFSET_RESETS.include?(consumer.auto_offset_reset)
+      validate_settings!
+      self
+    end
+
+    def broker_config(name = :default)
+      config = @brokers[name.to_sym]
+      raise ArgumentError, "Unknown broker: #{name}" unless config
+      config
+    end
+
+    def topic_config(name, side: nil)
+      config = @topics[name]
+      return broker_config if config.nil?
+      if side && config[:side] != :both && config[:side] != side
+        raise ArgumentError, "Topic #{name} is not configured for #{side}"
+      end
+      return broker_config(config[:broker]) if config[:broker]
+      broker_config.merge(config.except(:broker, :side))
+    end
+
+    def kafka_config(connection, kind: :producer, group_id: nil)
+      result = ((kind == :producer) ? @producer : @consumer).to_kafka.merge("bootstrap.servers" => connection.fetch(:host))
+      {protocol: "security.protocol", username: "sasl.username", password: "sasl.password", sasl_mechanisms: "sasl.mechanisms"}.each do |key, kafka_key|
+        result[kafka_key] = connection[key] if connection.key?(key)
+      end
+      result["group.id"] = group_id if group_id
+      result.merge((kind == :consumer) ? FIXED : {}).merge("allow.auto.create.topics" => false)
+    end
+
+    class Settings
+      def initialize(defaults)
+        @values = defaults.dup
+      end
+
+      def to_kafka = @values.dup
+
+      protected
+
+      def read(key) = @values.fetch(key)
+      def write(key, value) = @values[key] = value
+    end
+
+    class ProducerSettings < Settings
+      def initialize = super(PRODUCER_DEFAULTS)
+      def metadata_max_age_ms = read("metadata.max.age.ms")
+
+      def metadata_max_age_ms=(value)
+        write("metadata.max.age.ms", value)
+      end
+
+      def message_send_max_retries = read("message.send.max.retries")
+
+      def message_send_max_retries=(value)
+        write("message.send.max.retries", value)
+      end
+
+      def request_timeout_ms = read("request.timeout.ms")
+
+      def request_timeout_ms=(value)
+        write("request.timeout.ms", value)
+      end
+
+      def socket_keepalive_enable = read("socket.keepalive.enable")
+
+      def socket_keepalive_enable=(value)
+        write("socket.keepalive.enable", value)
+      end
+
+      def batch_num_messages = read("batch.num.messages")
+
+      def batch_num_messages=(value)
+        write("batch.num.messages", value)
+      end
+
+      def linger_ms = read("linger.ms")
+
+      def linger_ms=(value)
+        write("linger.ms", value)
+      end
+    end
+
+    class ConsumerSettings < Settings
+      def initialize = super(CONSUMER_DEFAULTS)
+      def socket_timeout_ms = read("socket.timeout.ms")
+
+      def socket_timeout_ms=(value)
+        write("socket.timeout.ms", value)
+      end
+
+      def session_timeout_ms = read("session.timeout.ms")
+
+      def session_timeout_ms=(value)
+        write("session.timeout.ms", value)
+      end
+
+      def heartbeat_interval_ms = read("heartbeat.interval.ms")
+
+      def heartbeat_interval_ms=(value)
+        write("heartbeat.interval.ms", value)
+      end
+
+      def max_poll_interval_ms = read("max.poll.interval.ms")
+
+      def max_poll_interval_ms=(value)
+        write("max.poll.interval.ms", value)
+      end
+
+      def metadata_max_age_ms = read("metadata.max.age.ms")
+
+      def metadata_max_age_ms=(value)
+        write("metadata.max.age.ms", value)
+      end
+
+      def socket_keepalive_enable = read("socket.keepalive.enable")
+
+      def socket_keepalive_enable=(value)
+        write("socket.keepalive.enable", value)
+      end
+
+      def auto_offset_reset = read("auto.offset.reset")
+
+      def auto_offset_reset=(value)
+        write("auto.offset.reset", value)
+      end
+
+      def enable_auto_commit = read("enable.auto.commit")
+
+      def enable_auto_commit=(value)
+        write("enable.auto.commit", value)
+      end
+    end
+
+    private
+
+    def validate_settings!
+      @producer.to_kafka.each_value { |value| raise ArgumentError, "producer settings cannot be nil" if value.nil? }
+      @consumer.to_kafka.each_value { |value| raise ArgumentError, "consumer settings cannot be nil" if value.nil? }
+    end
+
+    def reject_unknown(options, allowed, kind)
+      unknown = options.keys - allowed
+      raise ArgumentError, "Unknown #{kind} option: #{unknown.join(", ")}" unless unknown.empty?
+    end
+  end
+end

data/lib/eh_messaging/dead_letter_router.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module EhMessaging
+  class DeadLetterRouter
+    def initialize(configuration, producer:, logger:)
+      @configuration, @producer, @logger = configuration, producer, logger
+    end
+
+    def route(handler, envelope, error)
+      publisher = @producer || Publisher.new(@configuration)
+      owns_publisher = @producer.nil?
+      broker = handler.respond_to?(:dead_letter_broker) ? handler.dead_letter_broker : :default
+      topic = Topics.dead_letter(handler.topic, envelope.consumer_group)
+      return @logger.warn("EhMessaging: DLT topic unavailable: #{topic}") unless publisher.topic_exists?(topic, broker: broker)
+
+      report = publisher.publish_dead_letter(handler.topic, envelope, error, broker: broker)
+      @logger.error("EhMessaging: DLT delivery failed: #{report.error.message}") if report.respond_to?(:error) && report.error
+    rescue => publish_error
+      @logger.error("EhMessaging: DLT routing failed: #{publish_error.class}: #{publish_error.message}")
+    ensure
+      publisher&.shutdown if owns_publisher
+    end
+  end
+end

data/lib/eh_messaging/envelope.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module EhMessaging
+  class Envelope
+    STANDARD_HEADERS = %w[EVENT_NAME APPLICATION_NAME COMPONENT_NAME CORRELATION_ID VERSION EVENT_ID TIMESTAMP].freeze
+    attr_reader :payload, :partition_key, :headers, :event_name, :event_id, :correlation_id,
+      :application_name, :component_name, :version, :timestamp, :enqueued_at,
+      :topic, :partition, :offset, :consumer_group, :mode
+
+    def initialize(payload:, partition_key:, headers:, mode: nil, consumer_group: nil, topic: nil,
+      partition: nil, offset: nil, enqueued_at: nil)
+      @payload, @partition_key, @headers = payload, partition_key, headers
+      @mode, @consumer_group, @topic = mode, consumer_group, topic
+      @partition, @offset, @enqueued_at = partition, offset, enqueued_at&.utc
+      @event_name = self.class.header(headers, "EVENT_NAME")
+      @event_id = self.class.header(headers, "EVENT_ID")
+      @correlation_id = self.class.header(headers, "CORRELATION_ID")
+      @application_name = self.class.header(headers, "APPLICATION_NAME")
+      @component_name = self.class.header(headers, "COMPONENT_NAME")
+      @version = self.class.header(headers, "VERSION")
+      @timestamp = self.class.header(headers, "TIMESTAMP")
+    end
+
+    def self.header(headers, key)
+      value = headers[key] || headers[key.to_s] || headers[key.to_sym]
+      decode(value)
+    end
+
+    def self.from_message(message, mode:, consumer_group:)
+      headers = (message.headers || {}).each_with_object({}) { |(key, value), result| result[key.to_s] = value }
+      payload = JSON.parse(message.payload)
+      timestamp = message.respond_to?(:timestamp) ? message.timestamp : nil
+      timestamp = Time.at(timestamp / 1000.0).utc if timestamp.is_a?(Numeric)
+      new(payload: payload, partition_key: message.key, headers: headers, mode: mode,
+        consumer_group: consumer_group, topic: message.topic, partition: message.partition,
+        offset: message.offset, enqueued_at: timestamp)
+    end
+
+    def self.headers_from_message(message)
+      (message.headers || {}).each_with_object({}) { |(key, value), result| result[key.to_s] = value }
+    end
+
+    def self.decode(value)
+      return nil if value.nil?
+      return value unless value.is_a?(String)
+      parsed = JSON.parse(value)
+      parsed.is_a?(String) ? parsed : value
+    rescue JSON::ParserError
+      value
+    end
+
+    def self.header_bytes(value)
+      return value.map { |item| header_bytes(item) } if value.is_a?(Array)
+
+      (value.is_a?(String) ? value : JSON.generate(value)).dup.force_encoding(Encoding::UTF_8)
+    end
+
+    def self.timestamp = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
+
+    def self.headers(event:, application_name:, component:, correlation_id:, version:, headers: {})
+      generated = {
+        "EVENT_NAME" => event, "APPLICATION_NAME" => application_name, "COMPONENT_NAME" => component,
+        "CORRELATION_ID" => correlation_id, "VERSION" => version, "EVENT_ID" => SecureRandom.uuid,
+        "TIMESTAMP" => timestamp
+      }
+      generated.merge(headers.transform_keys(&:to_s))
+    end
+  end
+end

data/lib/eh_messaging/publisher.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module EhMessaging
+  class DeliveryReport
+    attr_reader :raw, :sent_keys, :error_keys
+
+    def initialize(raw, key)
+      @raw = raw
+      @sent_keys = raw.error ? [] : [key]
+      @error_keys = raw.error ? [key] : []
+    end
+
+    def error = raw.error
+
+    def topic_name
+      raw.topic_name if raw.respond_to?(:topic_name)
+    end
+
+    def partition
+      raw.partition if raw.respond_to?(:partition)
+    end
+
+    def offset
+      raw.offset if raw.respond_to?(:offset)
+    end
+  end
+
+  class Publisher
+    REQUIRED = %i[event application_name component correlation_id version partition_key payload].freeze
+    attr_reader :producers
+
+    def initialize(configuration, producer_factory: nil, logger: nil)
+      @configuration, @producer_factory, @producers, @mutex = configuration, producer_factory, {}, Mutex.new
+      @logger = logger || AuditLogger.new(configuration)
+      @closed = false
+    end
+
+    def boot
+      ensure_open
+      @configuration.brokers.each_key { |name| producer(name) }
+      self
+    end
+
+    def publish(topic, **options)
+      ensure_open
+      validate_options(options)
+      connection = resolve_connection(topic, options[:broker])
+      header_options = options.slice(:event, :application_name, :component, :correlation_id, :version, :headers)
+      payload = options[:raw] ? options[:payload] : JSON.generate(options[:payload])
+      key = Envelope.header_bytes(options[:partition_key])
+      Telemetry.in_span("eh_messaging.publish", attributes: {"messaging.destination.name" => topic}) do |span|
+        headers = Telemetry.headers(Envelope.headers(**header_options), current_span: span)
+        report = producer(connection[:name], connection).produce(topic: topic, payload: payload, key: key,
+          headers: headers.transform_values { |value| Envelope.header_bytes(value) }).wait
+        delivery_report = DeliveryReport.new(report, options[:partition_key])
+        log_delivery(topic, options[:partition_key], delivery_report)
+        delivery_report
+      end
+    end
+
+    def publish_dead_letter(topic, envelope, error, broker: :default)
+      extras = envelope.headers.except(*Envelope::STANDARD_HEADERS)
+      payload = envelope.payload.is_a?(String) ? envelope.payload : JSON.generate(envelope.payload)
+      headers = Envelope.headers(event: envelope.event_name, application_name: envelope.application_name,
+        component: envelope.component_name, correlation_id: envelope.correlation_id, version: envelope.version,
+        headers: extras)
+      publish_raw(Topics.dead_letter(topic, envelope.consumer_group), payload, envelope.partition_key,
+        Telemetry.headers(headers), broker: broker)
+    end
+
+    def publish_raw(topic, payload, key, headers, broker: :default)
+      ensure_open
+      connection = resolve_connection(topic, broker)
+      report = producer(connection[:name], connection).produce(topic: topic, payload: payload, key: key,
+        headers: headers.transform_values { |value| Envelope.header_bytes(value) }).wait
+      DeliveryReport.new(report, key)
+    end
+
+    def topic_exists?(topic, broker: :default)
+      connection = @configuration.broker_config(broker)
+      metadata = producer(connection[:name], connection).metadata(topic)
+      topics = metadata.topics
+      topics = topics.keys if topics.is_a?(Hash)
+      Array(topics).any? do |item|
+        if item.is_a?(String)
+          item == topic
+        elsif item.respond_to?(:name)
+          item.name == topic
+        elsif item.is_a?(Hash)
+          item[:topic_name] == topic || item["topic_name"] == topic || item[:name] == topic || item["name"] == topic
+        else
+          item.respond_to?(:topic_name) && item.topic_name == topic
+        end
+      end
+    end
+
+    def shutdown
+      return self if @closed
+      @producers.each_value { |producer|
+        producer.flush if producer.respond_to?(:flush)
+        producer.close
+      }
+      @producers.clear
+      @closed = true
+      self
+    end
+
+    private
+
+    def ensure_open
+      raise Error, "publisher is shut down" if @closed
+    end
+
+    def producer(name, config = nil)
+      @mutex.synchronize do
+        @producers[name] ||= if @producer_factory
+          @producer_factory.call(name, config || @configuration.broker_config(name))
+        else
+          Rdkafka::Config.new(@configuration.kafka_config(config || @configuration.broker_config(name))).producer
+        end
+      end
+    end
+
+    def resolve_connection(topic, requested)
+      return @configuration.broker_config(requested) if requested.is_a?(Symbol)
+      if requested
+        return @configuration.brokers.values.find { |config| config[:host] == requested } ||
+            raise(ArgumentError, "Unknown broker host: #{requested}")
+      end
+      @configuration.topic_config(topic, side: :produce)
+    end
+
+    def validate_options(options)
+      missing = REQUIRED.reject { |key| options.key?(key) && !options[key].nil? }
+      raise ArgumentError, "Missing publish options: #{missing.join(", ")}" unless missing.empty?
+      allowed = REQUIRED + %i[headers broker raw]
+      unknown = options.keys - allowed
+      raise ArgumentError, "Unknown publish options: #{unknown.join(", ")}" unless unknown.empty?
+      raise ArgumentError, "headers must be a Hash" unless options.fetch(:headers, {}).is_a?(Hash)
+      raise ArgumentError, "payload must be a Hash, Array, or String" unless [Hash, Array, String].any? { |type| options[:payload].is_a?(type) }
+    end
+
+    def log_delivery(topic, key, report)
+      fields = {Key: key, TopicName: topic, Error: report.error&.message}
+      fields[:Offset] = report.offset if delivery_field?(report, :offset)
+      fields[:Partition] = report.partition if delivery_field?(report, :partition)
+      @logger.public_send(report.error ? :error : :info, "publish", fields)
+    end
+
+    def delivery_field?(report, name)
+      report.class.public_method_defined?(name, false)
+    end
+  end
+end

data/lib/eh_messaging/recoverable_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EhMessaging
+  class RecoverableError < StandardError; end
+end