rdkafka 0.22.2 → 0.27.0

data/lib/rdkafka/callbacks.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module Rdkafka
+  # Callback handlers for librdkafka events
+  # @private
   module Callbacks
     # Extracts attributes of a rd_kafka_topic_result_t
     #
@@ -8,12 +10,16 @@ module Rdkafka
     class TopicResult
       attr_reader :result_error, :error_string, :result_name
 
+      # @param topic_result_pointer [FFI::Pointer] pointer to the topic result struct
       def initialize(topic_result_pointer)
         @result_error = Rdkafka::Bindings.rd_kafka_topic_result_error(topic_result_pointer)
         @error_string = Rdkafka::Bindings.rd_kafka_topic_result_error_string(topic_result_pointer)
         @result_name = Rdkafka::Bindings.rd_kafka_topic_result_name(topic_result_pointer)
       end
 
+      # @param count [Integer] number of results
+      # @param array_pointer [FFI::Pointer] pointer to the results array
+      # @return [Array<TopicResult>] array of topic results
       def self.create_topic_results_from_array(count, array_pointer)
         (1..count).map do |index|
           result_pointer = (array_pointer + (index - 1)).read_pointer
@@ -22,13 +28,18 @@ module Rdkafka
       end
     end
 
+    # Extracts attributes of rd_kafka_group_result_t
+    #
+    # @private
     class GroupResult
       attr_reader :result_error, :error_string, :result_name
+
+      # @param group_result_pointer [FFI::Pointer] pointer to the group result struct
       def initialize(group_result_pointer)
         native_error = Rdkafka::Bindings.rd_kafka_group_result_error(group_result_pointer)
 
         if native_error.null?
-          @result_error = 0
+          @result_error = Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
           @error_string = FFI::Pointer::NULL
         else
           @result_error = native_error[:code]
@@ -37,6 +48,10 @@ module Rdkafka
 
         @result_name = Rdkafka::Bindings.rd_kafka_group_result_name(group_result_pointer)
       end
+
+      # @param count [Integer] number of results
+      # @param array_pointer [FFI::Pointer] pointer to the results array
+      # @return [Array<GroupResult>] array of group results
       def self.create_group_results_from_array(count, array_pointer)
         (1..count).map do |index|
           result_pointer = (array_pointer + (index - 1)).read_pointer
@@ -51,12 +66,16 @@ module Rdkafka
     class CreateAclResult
       attr_reader :result_error, :error_string
 
+      # @param acl_result_pointer [FFI::Pointer] pointer to the ACL result struct
       def initialize(acl_result_pointer)
         rd_kafka_error_pointer = Bindings.rd_kafka_acl_result_error(acl_result_pointer)
         @result_error = Rdkafka::Bindings.rd_kafka_error_code(rd_kafka_error_pointer)
         @error_string = Rdkafka::Bindings.rd_kafka_error_string(rd_kafka_error_pointer)
       end
 
+      # @param count [Integer] number of results
+      # @param array_pointer [FFI::Pointer] pointer to the results array
+      # @return [Array<CreateAclResult>] array of ACL results
       def self.create_acl_results_from_array(count, array_pointer)
         (1..count).map do |index|
           result_pointer = (array_pointer + (index - 1)).read_pointer
@@ -71,19 +90,23 @@ module Rdkafka
     class DeleteAclResult
       attr_reader :result_error, :error_string, :matching_acls, :matching_acls_count
 
+      # @param acl_result_pointer [FFI::Pointer] pointer to the delete ACL result response struct
       def initialize(acl_result_pointer)
-        @matching_acls=[]
+        @matching_acls = []
         rd_kafka_error_pointer = Rdkafka::Bindings.rd_kafka_DeleteAcls_result_response_error(acl_result_pointer)
         @result_error = Rdkafka::Bindings.rd_kafka_error_code(rd_kafka_error_pointer)
         @error_string = Rdkafka::Bindings.rd_kafka_error_string(rd_kafka_error_pointer)
-        if @result_error == 0
-           # Get the number of matching acls
-           pointer_to_size_t = FFI::MemoryPointer.new(:int32)
-           @matching_acls = Rdkafka::Bindings.rd_kafka_DeleteAcls_result_response_matching_acls(acl_result_pointer, pointer_to_size_t)
-           @matching_acls_count = pointer_to_size_t.read_int
+        if @result_error == Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
+          # Get the number of matching acls
+          pointer_to_size_t = FFI::MemoryPointer.new(:int32)
+          @matching_acls = Rdkafka::Bindings.rd_kafka_DeleteAcls_result_response_matching_acls(acl_result_pointer, pointer_to_size_t)
+          @matching_acls_count = pointer_to_size_t.read_int
         end
       end
 
+      # @param count [Integer] number of results
+      # @param array_pointer [FFI::Pointer] pointer to the results array
+      # @return [Array<DeleteAclResult>] array of delete ACL results
       def self.delete_acl_results_from_array(count, array_pointer)
         (1..count).map do |index|
           result_pointer = (array_pointer + (index - 1)).read_pointer
@@ -98,11 +121,12 @@ module Rdkafka
     class DescribeAclResult
       attr_reader :result_error, :error_string, :matching_acls, :matching_acls_count
 
+      # @param event_ptr [FFI::Pointer] pointer to the event
       def initialize(event_ptr)
-        @matching_acls=[]
+        @matching_acls = []
         @result_error = Rdkafka::Bindings.rd_kafka_event_error(event_ptr)
         @error_string = Rdkafka::Bindings.rd_kafka_event_error_string(event_ptr)
-        if @result_error == 0
+        if @result_error == Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
           acl_describe_result = Rdkafka::Bindings.rd_kafka_event_DescribeAcls_result(event_ptr)
           # Get the number of matching acls
           pointer_to_size_t = FFI::MemoryPointer.new(:int32)
@@ -112,15 +136,19 @@ module Rdkafka
       end
     end
 
+    # Extracts attributes of rd_kafka_DescribeConfigs_result_t
+    #
+    # @private
     class DescribeConfigsResult
       attr_reader :result_error, :error_string, :results, :results_count
 
+      # @param event_ptr [FFI::Pointer] pointer to the event
       def initialize(event_ptr)
-        @results=[]
+        @results = []
         @result_error = Rdkafka::Bindings.rd_kafka_event_error(event_ptr)
         @error_string = Rdkafka::Bindings.rd_kafka_event_error_string(event_ptr)
 
-        if @result_error == 0
+        if @result_error == Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
           configs_describe_result = Rdkafka::Bindings.rd_kafka_event_DescribeConfigs_result(event_ptr)
           # Get the number of matching acls
           pointer_to_size_t = FFI::MemoryPointer.new(:int32)
@@ -130,15 +158,19 @@ module Rdkafka
       end
     end
 
+    # Extracts attributes of rd_kafka_IncrementalAlterConfigs_result_t
+    #
+    # @private
     class IncrementalAlterConfigsResult
       attr_reader :result_error, :error_string, :results, :results_count
 
+      # @param event_ptr [FFI::Pointer] pointer to the event
       def initialize(event_ptr)
-        @results=[]
+        @results = []
         @result_error = Rdkafka::Bindings.rd_kafka_event_error(event_ptr)
         @error_string = Rdkafka::Bindings.rd_kafka_event_error_string(event_ptr)
 
-        if @result_error == 0
+        if @result_error == Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
           incremental_alter_result = Rdkafka::Bindings.rd_kafka_event_IncrementalAlterConfigs_result(event_ptr)
           # Get the number of matching acls
           pointer_to_size_t = FFI::MemoryPointer.new(:int32)
@@ -148,9 +180,34 @@ module Rdkafka
       end
     end
 
+    # Extracts attributes of rd_kafka_ListOffsets_result_t
+    #
+    # @private
+    class ListOffsetsResult
+      attr_reader :result_error, :error_string, :result_infos, :result_count
+
+      # @param event_ptr [FFI::Pointer] pointer to the event
+      def initialize(event_ptr)
+        @result_infos = FFI::Pointer::NULL
+        @result_error = Rdkafka::Bindings.rd_kafka_event_error(event_ptr)
+        @error_string = Rdkafka::Bindings.rd_kafka_event_error_string(event_ptr)
+
+        if @result_error == Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
+          list_offsets_result = Rdkafka::Bindings.rd_kafka_event_ListOffsets_result(event_ptr)
+          pointer_to_size_t = FFI::MemoryPointer.new(:size_t)
+          @result_infos = Rdkafka::Bindings.rd_kafka_ListOffsets_result_infos(list_offsets_result, pointer_to_size_t)
+          @result_count = pointer_to_size_t.read(:size_t)
+        end
+      end
+    end
+
     # @private
     class BackgroundEventCallback
-      def self.call(_, event_ptr, _)
+      # Handles background events from librdkafka
+      # @param _client_ptr [FFI::Pointer] unused client pointer
+      # @param event_ptr [FFI::Pointer] pointer to the event
+      # @param _opaque_ptr [FFI::Pointer] unused opaque pointer
+      def self.call(_client_ptr, event_ptr, _opaque_ptr)
         case Rdkafka::Bindings.rd_kafka_event_type(event_ptr)
         when Rdkafka::Bindings::RD_KAFKA_EVENT_CREATETOPICS_RESULT
           process_create_topic(event_ptr)
@@ -170,11 +227,15 @@ module Rdkafka
           process_describe_acl(event_ptr)
         when Rdkafka::Bindings::RD_KAFKA_EVENT_DELETEGROUPS_RESULT
           process_delete_groups(event_ptr)
+        when Rdkafka::Bindings::RD_KAFKA_EVENT_LISTOFFSETS_RESULT
+          process_list_offsets(event_ptr)
         end
       end
 
       private
 
+      # Processes create topic result event
+      # @param event_ptr [FFI::Pointer] pointer to the event
       def self.process_create_topic(event_ptr)
         create_topics_result = Rdkafka::Bindings.rd_kafka_event_CreateTopics_result(event_ptr)
 
@@ -193,6 +254,8 @@ module Rdkafka
         end
       end
 
+      # Processes describe configs result event
+      # @param event_ptr [FFI::Pointer] pointer to the event
       def self.process_describe_configs(event_ptr)
         describe_configs = DescribeConfigsResult.new(event_ptr)
         describe_configs_handle_ptr = Rdkafka::Bindings.rd_kafka_event_opaque(event_ptr)
@@ -202,7 +265,7 @@ module Rdkafka
           describe_configs_handle[:response_string] = describe_configs.error_string
           describe_configs_handle[:pending] = false
 
-          if describe_configs.result_error == 0
+          if describe_configs.result_error == Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
             describe_configs_handle[:config_entries] = describe_configs.results
             describe_configs_handle[:entry_count] = describe_configs.results_count
           end
@@ -211,6 +274,8 @@ module Rdkafka
         end
       end
 
+      # Processes incremental alter configs result event
+      # @param event_ptr [FFI::Pointer] pointer to the event
       def self.process_incremental_alter_configs(event_ptr)
         incremental_alter = IncrementalAlterConfigsResult.new(event_ptr)
         incremental_alter_handle_ptr = Rdkafka::Bindings.rd_kafka_event_opaque(event_ptr)
@@ -220,7 +285,7 @@ module Rdkafka
           incremental_alter_handle[:response_string] = incremental_alter.error_string
           incremental_alter_handle[:pending] = false
 
-          if incremental_alter.result_error == 0
+          if incremental_alter.result_error == Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
             incremental_alter_handle[:config_entries] = incremental_alter.results
             incremental_alter_handle[:entry_count] = incremental_alter.results_count
           end
@@ -229,6 +294,8 @@ module Rdkafka
         end
       end
 
+      # Processes delete groups result event
+      # @param event_ptr [FFI::Pointer] pointer to the event
       def self.process_delete_groups(event_ptr)
         delete_groups_result = Rdkafka::Bindings.rd_kafka_event_DeleteGroups_result(event_ptr)
 
@@ -247,6 +314,8 @@ module Rdkafka
         end
       end
 
+      # Processes delete topic result event
+      # @param event_ptr [FFI::Pointer] pointer to the event
       def self.process_delete_topic(event_ptr)
         delete_topics_result = Rdkafka::Bindings.rd_kafka_event_DeleteTopics_result(event_ptr)
 
@@ -265,6 +334,8 @@ module Rdkafka
         end
       end
 
+      # Processes create partitions result event
+      # @param event_ptr [FFI::Pointer] pointer to the event
       def self.process_create_partitions(event_ptr)
         create_partitionss_result = Rdkafka::Bindings.rd_kafka_event_CreatePartitions_result(event_ptr)
 
@@ -283,6 +354,8 @@ module Rdkafka
         end
       end
 
+      # Processes create ACL result event
+      # @param event_ptr [FFI::Pointer] pointer to the event
       def self.process_create_acl(event_ptr)
         create_acls_result = Rdkafka::Bindings.rd_kafka_event_CreateAcls_result(event_ptr)
 
@@ -300,6 +373,8 @@ module Rdkafka
         end
       end
 
+      # Processes delete ACL result event
+      # @param event_ptr [FFI::Pointer] pointer to the event
       def self.process_delete_acl(event_ptr)
         delete_acls_result = Rdkafka::Bindings.rd_kafka_event_DeleteAcls_result(event_ptr)
 
@@ -313,7 +388,7 @@ module Rdkafka
           delete_acl_handle[:response] = delete_acl_results[0].result_error
           delete_acl_handle[:response_string] = delete_acl_results[0].error_string
 
-          if delete_acl_results[0].result_error == 0
+          if delete_acl_results[0].result_error == Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
             delete_acl_handle[:matching_acls] = delete_acl_results[0].matching_acls
             delete_acl_handle[:matching_acls_count] = delete_acl_results[0].matching_acls_count
           end
@@ -322,6 +397,8 @@ module Rdkafka
         end
       end
 
+      # Processes describe ACL result event
+      # @param event_ptr [FFI::Pointer] pointer to the event
       def self.process_describe_acl(event_ptr)
         describe_acl = DescribeAclResult.new(event_ptr)
         describe_acl_handle_ptr = Rdkafka::Bindings.rd_kafka_event_opaque(event_ptr)
@@ -330,7 +407,7 @@ module Rdkafka
           describe_acl_handle[:response] = describe_acl.result_error
           describe_acl_handle[:response_string] = describe_acl.error_string
 
-          if describe_acl.result_error == 0
+          if describe_acl.result_error == Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
             describe_acl_handle[:acls] = describe_acl.matching_acls
             describe_acl_handle[:acls_count] = describe_acl.matching_acls_count
           end
@@ -338,11 +415,35 @@ module Rdkafka
           describe_acl_handle.unlock
         end
       end
+
+      # Processes list offsets result event
+      # @param event_ptr [FFI::Pointer] pointer to the event
+      def self.process_list_offsets(event_ptr)
+        list_offsets = ListOffsetsResult.new(event_ptr)
+        list_offsets_handle_ptr = Rdkafka::Bindings.rd_kafka_event_opaque(event_ptr)
+
+        if list_offsets_handle = Rdkafka::Admin::ListOffsetsHandle.remove(list_offsets_handle_ptr.address)
+          list_offsets_handle[:response] = list_offsets.result_error
+          list_offsets_handle[:response_string] = list_offsets.error_string
+          list_offsets_handle[:pending] = false
+
+          if list_offsets.result_error == Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
+            list_offsets_handle[:result_infos] = list_offsets.result_infos
+            list_offsets_handle[:result_count] = list_offsets.result_count
+          end
+
+          list_offsets_handle.unlock
+        end
+      end
     end
 
     # @private
     class DeliveryCallback
-      def self.call(_, message_ptr, opaque_ptr)
+      # Handles message delivery callbacks
+      # @param _client_ptr [FFI::Pointer] unused client pointer
+      # @param message_ptr [FFI::Pointer] pointer to the delivered message
+      # @param opaque_ptr [FFI::Pointer] pointer to the opaque object for callback context
+      def self.call(_client_ptr, message_ptr, opaque_ptr)
         message = Rdkafka::Bindings::Message.new(message_ptr)
         delivery_handle_ptr_address = message[:_private].address
         if delivery_handle = Rdkafka::Producer::DeliveryHandle.remove(delivery_handle_ptr_address)
@@ -373,7 +474,9 @@ module Rdkafka
       end
     end
 
+    # @private
     @@mutex = Mutex.new
+    # @private
     @@current_pid = nil
 
     class << self
@@ -392,14 +495,14 @@ module Rdkafka
 
           # FFI Function used for Create Topic and Delete Topic callbacks
           background_event_callback_function = FFI::Function.new(
-              :void, [:pointer, :pointer, :pointer]
+            :void, [:pointer, :pointer, :pointer]
           ) do |client_ptr, event_ptr, opaque_ptr|
             BackgroundEventCallback.call(client_ptr, event_ptr, opaque_ptr)
           end
 
           # FFI Function used for Message Delivery callbacks
           delivery_callback_function = FFI::Function.new(
-              :void, [:pointer, :pointer, :pointer]
+            :void, [:pointer, :pointer, :pointer]
           ) do |client_ptr, message_ptr, opaque_ptr|
             DeliveryCallback.call(client_ptr, message_ptr, opaque_ptr)
           end

data/lib/rdkafka/config.rb

@@ -6,7 +6,7 @@ module Rdkafka
   # configuration options is available on https://github.com/confluentinc/librdkafka/blob/master/CONFIGURATION.md.
   class Config
     # @private
-    @@logger = Logger.new(STDOUT)
+    @@logger = Logger.new($stdout)
     # @private
     @@statistics_callback = nil
     # @private
@@ -33,7 +33,7 @@ module Rdkafka
     # Makes sure that there is a thread for consuming logs
     # We do not spawn thread immediately and we need to check if it operates to support forking
     def self.ensure_log_thread
-      return if @@log_thread && @@log_thread.alive?
+      return if @@log_thread&.alive?
 
       @@log_mutex.synchronize do
         # Restart if dead (fork, crash)
@@ -71,11 +71,10 @@ module Rdkafka
     # You can configure if and how often this happens using `statistics.interval.ms`.
     # The callback is called with a hash that's documented here: https://github.com/confluentinc/librdkafka/blob/master/STATISTICS.md
     #
-    # @param callback [Proc, #call] The callback
-    #
+    # @param callback [Proc, #call, nil] callable object or nil to clear
     # @return [nil]
     def self.statistics_callback=(callback)
-      raise TypeError.new("Callback has to be callable") unless callback.respond_to?(:call) || callback == nil
+      raise TypeError.new("Callback has to be callable") unless callback.respond_to?(:call) || callback.nil?
       @@statistics_callback = callback
     end
 
@@ -90,11 +89,10 @@ module Rdkafka
     # If this callback is not set, global errors such as brokers becoming unavailable will only be sent to the logger, as defined by librdkafka.
     # The callback is called with an instance of RdKafka::Error.
     #
-    # @param callback [Proc, #call] The callback
-    #
+    # @param callback [Proc, #call, nil] callable object to handle errors or nil to clear
     # @return [nil]
     def self.error_callback=(callback)
-      raise TypeError.new("Callback has to be callable") unless callback.respond_to?(:call)
+      raise TypeError.new("Callback has to be callable") unless callback.respond_to?(:call) || callback.nil?
       @@error_callback = callback
     end
 
@@ -108,11 +106,10 @@ module Rdkafka
     # Sets the SASL/OAUTHBEARER token refresh callback.
     # This callback will be triggered when it is time to refresh the client's OAUTHBEARER token
     #
-    # @param callback [Proc, #call] The callback
-    #
+    # @param callback [Proc, #call, nil] callable object to handle token refresh or nil to clear
     # @return [nil]
     def self.oauthbearer_token_refresh_callback=(callback)
-      raise TypeError.new("Callback has to be callable") unless callback.respond_to?(:call) || callback == nil
+      raise TypeError.new("Callback has to be callable") unless callback.respond_to?(:call) || callback.nil?
       @@oauthbearer_token_refresh_callback = callback
     end
 
@@ -129,15 +126,12 @@ module Rdkafka
     end
 
     # Default config that can be overwritten.
-    DEFAULT_CONFIG = {
-      # Request api version so advanced features work
-      :"api.version.request" => true
-    }.freeze
+    DEFAULT_CONFIG = {}.freeze
 
     # Required config that cannot be overwritten.
     REQUIRED_CONFIG = {
       # Enable log queues so we get callbacks in our own Ruby threads
-      :"log.queue" => true
+      "log.queue": true
     }.freeze
 
     # Returns a new config with the provided options which are merged with {DEFAULT_CONFIG}.
@@ -174,10 +168,8 @@ module Rdkafka
 
     # Get notifications on partition assignment/revocation for the subscribed topics
     #
-    # @param listener [Object, #on_partitions_assigned, #on_partitions_revoked] listener instance
-    def consumer_rebalance_listener=(listener)
-      @consumer_rebalance_listener = listener
-    end
+    # @return [Object, #on_partitions_assigned, #on_partitions_revoked] listener instance
+    attr_writer :consumer_rebalance_listener
 
     # Should we use a single queue for the underlying consumer and events.
     #
@@ -190,10 +182,8 @@ module Rdkafka
     # It is recommended to use the defaults and only set it to `false` in advance multi-threaded
     # and complex cases where granular events handling control is needed.
     #
-    # @param poll_set [Boolean]
-    def consumer_poll_set=(poll_set)
-      @consumer_poll_set = poll_set
-    end
+    # @return [Boolean]
+    attr_writer :consumer_poll_set
 
     # Creates a consumer with this configuration.
     #
@@ -234,11 +224,13 @@ module Rdkafka
     # @param native_kafka_auto_start [Boolean] should the native kafka operations be started
     #   automatically. Defaults to true. Set to false only when doing complex initialization.
     # @param native_kafka_poll_timeout_ms [Integer] ms poll time of the native Kafka
+    # @param run_polling_thread [Boolean] should the background polling thread be started.
+    #   Defaults to true. Set to false when using the FD API for fiber scheduler integration.
     # @return [Producer] The created producer
     #
     # @raise [ConfigError] When the configuration contains invalid options
     # @raise [ClientCreationError] When the native client cannot be created
-    def producer(native_kafka_auto_start: true, native_kafka_poll_timeout_ms: 100)
+    def producer(native_kafka_auto_start: true, native_kafka_poll_timeout_ms: Defaults::NATIVE_KAFKA_POLL_TIMEOUT_MS, run_polling_thread: true)
       # Create opaque
       opaque = Opaque.new
       # Create Kafka config
@@ -253,7 +245,7 @@ module Rdkafka
       Rdkafka::Producer.new(
         Rdkafka::NativeKafka.new(
           kafka,
-          run_polling_thread: true,
+          run_polling_thread: run_polling_thread,
           opaque: opaque,
           auto_start: native_kafka_auto_start,
           timeout_ms: native_kafka_poll_timeout_ms
@@ -269,11 +261,13 @@ module Rdkafka
     # @param native_kafka_auto_start [Boolean] should the native kafka operations be started
     #   automatically. Defaults to true. Set to false only when doing complex initialization.
     # @param native_kafka_poll_timeout_ms [Integer] ms poll time of the native Kafka
+    # @param run_polling_thread [Boolean] should the background polling thread be started.
+    #   Defaults to true. Set to false when using the FD API for fiber scheduler integration.
     # @return [Admin] The created admin instance
     #
     # @raise [ConfigError] When the configuration contains invalid options
     # @raise [ClientCreationError] When the native client cannot be created
-    def admin(native_kafka_auto_start: true, native_kafka_poll_timeout_ms: 100)
+    def admin(native_kafka_auto_start: true, native_kafka_poll_timeout_ms: Defaults::NATIVE_KAFKA_POLL_TIMEOUT_MS, run_polling_thread: true)
       opaque = Opaque.new
       config = native_config(opaque)
       Rdkafka::Bindings.rd_kafka_conf_set_background_event_cb(config, Rdkafka::Callbacks::BackgroundEventCallbackFunction)
@@ -283,7 +277,7 @@ module Rdkafka
       Rdkafka::Admin.new(
         Rdkafka::NativeKafka.new(
           kafka,
-          run_polling_thread: true,
+          run_polling_thread: run_polling_thread,
           opaque: opaque,
           auto_start: native_kafka_auto_start,
           timeout_ms: native_kafka_poll_timeout_ms
@@ -291,6 +285,46 @@ module Rdkafka
       )
     end
 
+    # Returns all configuration properties and their current values for this config.
+    #
+    # Uses `rd_kafka_conf_dump` to retrieve every property (including defaults and
+    # internal properties like `client.software.name`) as a flat Hash.
+    #
+    # @note The librdkafka C API does not distinguish between producer-only, consumer-only,
+    #   and global properties at the configuration level. All properties are returned
+    #   regardless of the intended client type.
+    #
+    # @note The returned Hash may include sensitive values such as authentication
+    #   credentials and key passwords. Do not log or serialize the returned data
+    #   unless you have explicitly redacted secret entries.
+    #
+    # @return [Hash{Symbol => String}] property names mapped to their current values
+    #
+    # @raise [ConfigError] When the configuration contains invalid options
+    def describe_properties
+      config = nil
+      dump_ptr = nil
+      count = 0
+
+      config = native_config
+      count_ptr = Rdkafka::Bindings::SizePtr.new
+      dump_ptr = Rdkafka::Bindings.rd_kafka_conf_dump(config, count_ptr)
+
+      count = count_ptr[:value]
+      result = {}
+
+      (0...count).step(2) do |i|
+        key = dump_ptr.get_pointer(i * FFI::Pointer.size).read_string
+        value = dump_ptr.get_pointer((i + 1) * FFI::Pointer.size).read_string
+        result[key.to_sym] = value
+      end
+
+      result
+    ensure
+      Rdkafka::Bindings.rd_kafka_conf_dump_free(dump_ptr, count) if dump_ptr
+      Rdkafka::Bindings.rd_kafka_conf_destroy(config) if config
+    end
+
     # Error that is returned by the underlying rdkafka error if an invalid configuration option is present.
     class ConfigError < RuntimeError; end
 
@@ -304,6 +338,9 @@ module Rdkafka
 
     # This method is only intended to be used to create a client,
     # using it in another way will leak memory.
+    #
+    # @param opaque [Object, nil] optional opaque pointer for callbacks
+    # @return [FFI::Pointer] native rdkafka configuration pointer
     def native_config(opaque = nil)
       Rdkafka::Bindings.rd_kafka_conf_new.tap do |config|
         # Create config
@@ -348,6 +385,11 @@ module Rdkafka
       end
     end
 
+    # Creates a native Kafka handle
+    # @param config [FFI::Pointer] pointer to the native config
+    # @param type [Symbol] type of client (:rd_kafka_producer or :rd_kafka_consumer)
+    # @return [FFI::Pointer] pointer to the native Kafka handle
+    # @private
     def native_kafka(config, type)
       error_buffer = FFI::MemoryPointer.from_string(" " * 256)
       handle = Rdkafka::Bindings.rd_kafka_new(
@@ -362,10 +404,9 @@ module Rdkafka
       end
 
       # Redirect log to handle's queue
-      Rdkafka::Bindings.rd_kafka_set_log_queue(
-        handle,
-        Rdkafka::Bindings.rd_kafka_queue_get_main(handle)
-      )
+      main_queue = Rdkafka::Bindings.rd_kafka_queue_get_main(handle)
+      Rdkafka::Bindings.rd_kafka_set_log_queue(handle, main_queue)
+      Rdkafka::Bindings.rd_kafka_queue_destroy(main_queue)
 
       # Return handle which should be closed using rd_kafka_destroy after usage.
       handle
@@ -377,10 +418,15 @@ module Rdkafka
     attr_accessor :producer
     attr_accessor :consumer_rebalance_listener
 
+    # Invokes the delivery callback on the producer if one is set
+    # @param delivery_report [Rdkafka::Producer::DeliveryReport] the delivery report
+    # @param delivery_handle [Rdkafka::Producer::DeliveryHandle] the delivery handle
     def call_delivery_callback(delivery_report, delivery_handle)
-      producer.call_delivery_callback(delivery_report, delivery_handle) if producer
+      producer&.call_delivery_callback(delivery_report, delivery_handle)
     end
 
+    # Invokes the on_partitions_assigned callback on the rebalance listener if set
+    # @param list [Rdkafka::Consumer::TopicPartitionList] the assigned partitions
     def call_on_partitions_assigned(list)
       return unless consumer_rebalance_listener
       return unless consumer_rebalance_listener.respond_to?(:on_partitions_assigned)
@@ -388,6 +434,8 @@ module Rdkafka
       consumer_rebalance_listener.on_partitions_assigned(list)
     end
 
+    # Invokes the on_partitions_revoked callback on the rebalance listener if set
+    # @param list [Rdkafka::Consumer::TopicPartitionList] the revoked partitions
     def call_on_partitions_revoked(list)
       return unless consumer_rebalance_listener
       return unless consumer_rebalance_listener.respond_to?(:on_partitions_revoked)

data/lib/rdkafka/consumer/headers.rb

@@ -4,6 +4,7 @@ module Rdkafka
   class Consumer
     # Interface to return headers for a consumer message
     module Headers
+      # Empty frozen hash used when there are no headers
       EMPTY_HEADERS = {}.freeze
 
       # Reads a librdkafka native message's headers and returns them as a Ruby Hash
@@ -12,8 +13,8 @@ module Rdkafka
       #
       # @private
       #
-      # @param [Rdkafka::Bindings::Message] native_message
-      # @return [Hash<String, String|Array<String>>] headers Hash for the native_message
+      # @param native_message [Rdkafka::Bindings::Message] the native message to read headers from
+      # @return [Hash{String => String, Array<String>}] headers Hash for the native_message
       # @raise [Rdkafka::RdkafkaError] when fail to read headers
       def self.from_native(native_message)
         headers_ptrptr = FFI::MemoryPointer.new(:pointer)