rdkafka 0.22.2 → 0.27.0

data/lib/rdkafka/defaults.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Rdkafka
+  # Default timeout and timing values used throughout rdkafka-ruby.
+  #
+  # All timeout values can be overridden per-call via method parameters.
+  # These constants provide a central place to understand and reference
+  # the default values used across the library.
+  #
+  # @note These are rdkafka-ruby defaults, not librdkafka configuration options.
+  #   For librdkafka options, see:
+  #   https://github.com/confluentinc/librdkafka/blob/master/CONFIGURATION.md
+  #
+  # @example Overriding a timeout per-call
+  #   consumer.committed(timeout_ms: 5_000)  # Use 5 seconds instead of default 2 seconds
+  #
+  # @example Checking the default value
+  #   Rdkafka::Defaults::CONSUMER_COMMITTED_TIMEOUT_MS  # => 2000
+  module Defaults
+    # Consumer timeouts (in milliseconds)
+
+    # Default timeout for fetching committed offsets
+    # @see Consumer#committed
+    CONSUMER_COMMITTED_TIMEOUT_MS = 2_000
+
+    # Default timeout for querying watermark offsets
+    # @see Consumer#query_watermark_offsets
+    CONSUMER_QUERY_WATERMARK_TIMEOUT_MS = 1_000
+
+    # Default timeout for lag calculation watermark queries
+    # @see Consumer#lag
+    CONSUMER_LAG_TIMEOUT_MS = 1_000
+
+    # Default timeout for offsets_for_times operation
+    # @see Consumer#offsets_for_times
+    CONSUMER_OFFSETS_FOR_TIMES_TIMEOUT_MS = 1_000
+
+    # Default poll timeout for Consumer#each iterator
+    # @see Consumer#each
+    CONSUMER_POLL_TIMEOUT_MS = 250
+
+    # Seek operation timeout (0 = non-blocking)
+    # @see Consumer#seek_by
+    CONSUMER_SEEK_TIMEOUT_MS = 0
+
+    # Events poll timeout (0 = non-blocking/async)
+    # @see Consumer#events_poll
+    CONSUMER_EVENTS_POLL_TIMEOUT_MS = 0
+
+    # Producer timeouts (in milliseconds)
+
+    # Default timeout for producer flush operation
+    # @see Producer#flush
+    PRODUCER_FLUSH_TIMEOUT_MS = 5_000
+
+    # Default flush timeout during purge operation
+    # @see Producer#purge
+    PRODUCER_PURGE_FLUSH_TIMEOUT_MS = 100
+
+    # Metadata timeouts (in milliseconds)
+
+    # Default timeout for metadata requests
+    # @see Admin#metadata
+    # @see Metadata#initialize
+    METADATA_TIMEOUT_MS = 2_000
+
+    # Handle wait timeouts (in milliseconds)
+
+    # Default maximum wait timeout for async handles (delivery, admin operations)
+    # @see AbstractHandle#wait
+    HANDLE_WAIT_TIMEOUT_MS = 60_000
+
+    # Native Kafka polling (in milliseconds)
+
+    # Default poll timeout for producer/admin native polling thread
+    # @see Config#producer
+    # @see Config#admin
+    NATIVE_KAFKA_POLL_TIMEOUT_MS = 100
+
+    # Internal timing (in milliseconds)
+
+    # Sleep interval during purge wait loop
+    # @see Producer#purge
+    PRODUCER_PURGE_SLEEP_INTERVAL_MS = 1
+
+    # Sleep interval while waiting for operations to complete in NativeKafka#synchronize
+    # @see NativeKafka#synchronize
+    NATIVE_KAFKA_SYNCHRONIZE_SLEEP_INTERVAL_MS = 10
+
+    # Base backoff factor for metadata retry in milliseconds (multiplied by 2^attempt)
+    # @see Metadata#initialize
+    METADATA_RETRY_BACKOFF_BASE_MS = 100
+
+    # Cache settings (in milliseconds)
+
+    # Default time-to-live for cached partition counts
+    # @see Producer::PartitionsCountCache
+    PARTITIONS_COUNT_CACHE_TTL_MS = 30_000
+
+    # Configuration values (not time-based)
+
+    # Maximum number of metadata fetch retry attempts
+    # @see Metadata#initialize
+    METADATA_MAX_RETRIES = 10
+  end
+end

data/lib/rdkafka/error.rb

@@ -18,12 +18,21 @@ module Rdkafka
     # @return [String]
     attr_reader :broker_message
 
+    # The name of the rdkafka instance that generated this error
+    # @return [String, nil]
+    attr_reader :instance_name
+
     # @private
-    def initialize(response, message_prefix=nil, broker_message: nil)
+    # @param response [Integer] the raw error response code from librdkafka
+    # @param message_prefix [String, nil] optional prefix for error messages
+    # @param broker_message [String, nil] optional error message from the broker
+    # @param instance_name [String, nil] optional name of the rdkafka instance
+    def initialize(response, message_prefix = nil, broker_message: nil, instance_name: nil)
       raise TypeError.new("Response has to be an integer") unless response.is_a? Integer
       @rdkafka_response = response
       @message_prefix = message_prefix
       @broker_message = broker_message
+      @instance_name = instance_name
     end
 
     # This error's code, for example `:partition_eof`, `:msg_size_too_large`.
@@ -31,7 +40,7 @@ module Rdkafka
     def code
       code = Rdkafka::Bindings.rd_kafka_err2name(@rdkafka_response).downcase
       if code[0] == "_"
-        code[1..-1].to_sym
+        code[1..].to_sym
       else
         code.to_sym
       end
@@ -41,11 +50,16 @@ module Rdkafka
     # @return [String]
     def to_s
       message_prefix_part = if message_prefix
-                       "#{message_prefix} - "
-                     else
-                       ''
-                     end
-      "#{message_prefix_part}#{Rdkafka::Bindings.rd_kafka_err2str(@rdkafka_response)} (#{code})"
+        "#{message_prefix} - "
+      else
+        ""
+      end
+      instance_name_part = if instance_name
+        " [#{instance_name}]"
+      else
+        ""
+      end
+      "#{message_prefix_part}#{Rdkafka::Bindings.rd_kafka_err2str(@rdkafka_response)} (#{code})#{instance_name_part}"
     end
 
     # Whether this error indicates the partition is EOF.
@@ -55,8 +69,10 @@ module Rdkafka
     end
 
     # Error comparison
-    def ==(another_error)
-       another_error.is_a?(self.class) && (self.to_s == another_error.to_s)
+    # @param other [Object] object to compare with
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(self.class) && (to_s == other.to_s)
     end
   end
 
@@ -66,7 +82,10 @@ module Rdkafka
     attr_reader :topic_partition_list
 
     # @private
-    def initialize(response, topic_partition_list, message_prefix=nil)
+    # @param response [Integer] the raw error response code from librdkafka
+    # @param topic_partition_list [TopicPartitionList] the topic partition list with error info
+    # @param message_prefix [String, nil] optional prefix for error messages
+    def initialize(response, topic_partition_list, message_prefix = nil)
       super(response, message_prefix)
       @topic_partition_list = topic_partition_list
     end
@@ -74,28 +93,35 @@ module Rdkafka
 
   # Error class for public consumer method calls on a closed consumer.
   class ClosedConsumerError < BaseError
+    # @param method [Symbol] the method that was called
     def initialize(method)
-      super("Illegal call to #{method.to_s} on a closed consumer")
+      super("Illegal call to #{method} on a closed consumer")
     end
   end
 
   # Error class for public producer method calls on a closed producer.
   class ClosedProducerError < BaseError
+    # @param method [Symbol] the method that was called
     def initialize(method)
-      super("Illegal call to #{method.to_s} on a closed producer")
+      super("Illegal call to #{method} on a closed producer")
     end
   end
 
-  # Error class for public consumer method calls on a closed admin.
+  # Error class for public admin method calls on a closed admin.
   class ClosedAdminError < BaseError
+    # @param method [Symbol] the method that was called
     def initialize(method)
-      super("Illegal call to #{method.to_s} on a closed admin")
+      super("Illegal call to #{method} on a closed admin")
     end
   end
 
+  # Error class for calls on a closed inner librdkafka instance.
   class ClosedInnerError < BaseError
     def initialize
       super("Illegal call to a closed inner librdkafka instance")
     end
   end
+
+  # Error class for librdkafka library loading failures (e.g., glibc compatibility issues).
+  class LibraryLoadError < BaseError; end
 end

data/lib/rdkafka/helpers/oauth.rb

@@ -1,8 +1,7 @@
 module Rdkafka
   module Helpers
-
+    # OAuth helper methods for setting and refreshing SASL/OAUTHBEARER tokens
     module OAuth
-
       # Set the OAuthBearer token
       #
       # @param token [String] the mandatory token value to set, often (but not necessarily) a JWS compact serialization as per https://tools.ietf.org/html/rfc7515#section-3.1.
@@ -12,12 +11,18 @@ module Rdkafka
       # @return [Integer] 0 on success
       def oauthbearer_set_token(token:, lifetime_ms:, principal_name:, extensions: nil)
         error_buffer = FFI::MemoryPointer.from_string(" " * 256)
+        extensions_ptr, extensions_str_ptrs = map_extensions(extensions)
 
-        response = @native_kafka.with_inner do |inner|
-          Rdkafka::Bindings.rd_kafka_oauthbearer_set_token(
-            inner, token, lifetime_ms, principal_name,
-            flatten_extensions(extensions), extension_size(extensions), error_buffer, 256
-          )
+        begin
+          response = @native_kafka.with_inner do |inner|
+            Rdkafka::Bindings.rd_kafka_oauthbearer_set_token(
+              inner, token, lifetime_ms, principal_name,
+              extensions_ptr, extension_size(extensions), error_buffer, 256
+            )
+          end
+        ensure
+          extensions_str_ptrs&.each { |ptr| ptr.free }
+          extensions_ptr&.free
         end
 
         return response if response.zero?
@@ -41,14 +46,41 @@ module Rdkafka
 
       private
 
-      # Flatten the extensions hash into a string according to the spec, https://datatracker.ietf.org/doc/html/rfc7628#section-3.1
-      def flatten_extensions(extensions)
-        return nil unless extensions
-        "\x01#{extensions.map { |e| e.join("=") }.join("\x01")}"
+      # Convert extensions hash to FFI::MemoryPointer (`const char **`).
+      #
+      # @param extensions [Hash, nil] extension key-value pairs
+      # @return [Array<FFI::MemoryPointer, Array<FFI::MemoryPointer>>] array pointer and string pointers
+      # @note The returned pointers must be freed manually (autorelease = false).
+      def map_extensions(extensions)
+        return [nil, nil] if extensions.nil? || extensions.empty?
+
+        # https://github.com/confluentinc/librdkafka/blob/master/src/rdkafka_sasl_oauthbearer.c#L327-L347
+
+        # The method argument is const char **
+        array_ptr = FFI::MemoryPointer.new(:pointer, extension_size(extensions))
+        array_ptr.autorelease = false
+        str_ptrs = []
+
+        # Element i is the key, i + 1 is the value.
+        extensions.each_with_index do |(k, v), i|
+          k_ptr = FFI::MemoryPointer.from_string(k.to_s)
+          k_ptr.autorelease = false
+          str_ptrs << k_ptr
+          v_ptr = FFI::MemoryPointer.from_string(v.to_s)
+          v_ptr.autorelease = false
+          str_ptrs << v_ptr
+          array_ptr[i * 2].put_pointer(0, k_ptr)
+          array_ptr[i * 2 + 1].put_pointer(0, v_ptr)
+        end
+
+        [array_ptr, str_ptrs]
       end
 
-      # extension_size is the number of keys + values which should be a non-negative even number
-      # https://github.com/confluentinc/librdkafka/blob/master/src/rdkafka_sasl_oauthbearer.c#L327-L347
+      # Returns the extension size (number of keys + values).
+      #
+      # @param extensions [Hash, nil] extension key-value pairs
+      # @return [Integer] non-negative even number representing keys + values count
+      # @see https://github.com/confluentinc/librdkafka/blob/master/src/rdkafka_sasl_oauthbearer.c#L327-L347
       def extension_size(extensions)
         return 0 unless extensions
         extensions.size * 2

data/lib/rdkafka/helpers/time.rb

@@ -9,6 +9,11 @@ module Rdkafka
       def monotonic_now
         ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       end
+
+      # @return [Integer] current monotonic time in milliseconds
+      def monotonic_now_ms
+        ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :millisecond)
+      end
     end
   end
 end

data/lib/rdkafka/metadata.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
 module Rdkafka
+  # Provides cluster metadata information
   class Metadata
-    attr_reader :brokers, :topics
+    # @return [Array<Hash>] list of broker metadata
+    attr_reader :brokers
+    # @return [Array<Hash>] list of topic metadata
+    attr_reader :topics
 
     # Errors upon which we retry the metadata fetch
     RETRIED_ERRORS = %i[
@@ -12,7 +16,13 @@ module Rdkafka
 
     private_constant :RETRIED_ERRORS
 
-    def initialize(native_client, topic_name = nil, timeout_ms = 2_000)
+    # Fetches metadata from the Kafka cluster
+    #
+    # @param native_client [FFI::Pointer] pointer to the native Kafka client
+    # @param topic_name [String, nil] specific topic to fetch metadata for, or nil for all topics
+    # @param timeout_ms [Integer] timeout in milliseconds
+    # @raise [RdkafkaError] when metadata fetch fails
+    def initialize(native_client, topic_name = nil, timeout_ms = Defaults::METADATA_TIMEOUT_MS)
       attempt ||= 0
       attempt += 1
 
@@ -35,12 +45,12 @@ module Rdkafka
       metadata_from_native(ptr.read_pointer)
     rescue ::Rdkafka::RdkafkaError => e
       raise unless RETRIED_ERRORS.include?(e.code)
-      raise if attempt > 10
+      raise if attempt > Defaults::METADATA_MAX_RETRIES
 
       backoff_factor = 2**attempt
-      timeout = backoff_factor * 0.1
+      timeout_ms = backoff_factor * Defaults::METADATA_RETRY_BACKOFF_BASE_MS
 
-      sleep(timeout)
+      sleep(timeout_ms / 1000.0)
 
       retry
     ensure
@@ -50,6 +60,8 @@ module Rdkafka
 
     private
 
+    # Extracts metadata from native pointer
+    # @param ptr [FFI::Pointer] pointer to native metadata
     def metadata_from_native(ptr)
       metadata = Metadata.new(ptr)
       @brokers = Array.new(metadata[:brokers_count]) do |i|
@@ -69,7 +81,11 @@ module Rdkafka
       end
     end
 
+    # Base class for metadata FFI structs with hash conversion
+    # @private
     class CustomFFIStruct < FFI::Struct
+      # Converts struct to a hash
+      # @return [Hash]
       def to_h
         members.each_with_object({}) do |mem, hsh|
           val = self.[](mem)
@@ -80,36 +96,44 @@ module Rdkafka
       end
     end
 
+    # @private
+    # FFI struct for rd_kafka_metadata_t
     class Metadata < CustomFFIStruct
       layout :brokers_count, :int,
-             :brokers_metadata, :pointer,
-             :topics_count, :int,
-             :topics_metadata, :pointer,
-             :broker_id, :int32,
-             :broker_name, :string
+        :brokers_metadata, :pointer,
+        :topics_count, :int,
+        :topics_metadata, :pointer,
+        :broker_id, :int32,
+        :broker_name, :string
     end
 
+    # @private
+    # FFI struct for rd_kafka_metadata_broker_t
     class BrokerMetadata < CustomFFIStruct
       layout :broker_id, :int32,
-             :broker_name, :string,
-             :broker_port, :int
+        :broker_name, :string,
+        :broker_port, :int
     end
 
+    # @private
+    # FFI struct for rd_kafka_metadata_topic_t
     class TopicMetadata < CustomFFIStruct
       layout :topic_name, :string,
-             :partition_count, :int,
-             :partitions_metadata, :pointer,
-             :rd_kafka_resp_err, :int
+        :partition_count, :int,
+        :partitions_metadata, :pointer,
+        :rd_kafka_resp_err, :int
     end
 
+    # @private
+    # FFI struct for rd_kafka_metadata_partition_t
     class PartitionMetadata < CustomFFIStruct
       layout :partition_id, :int32,
-             :rd_kafka_resp_err, :int,
-             :leader, :int32,
-             :replica_count, :int,
-             :replicas, :pointer,
-             :in_sync_replica_brokers, :int,
-             :isrs, :pointer
+        :rd_kafka_resp_err, :int,
+        :leader, :int32,
+        :replica_count, :int,
+        :replicas, :pointer,
+        :in_sync_replica_brokers, :int,
+        :isrs, :pointer
     end
   end
 end

data/lib/rdkafka/native_kafka.rb

@@ -4,7 +4,13 @@ module Rdkafka
   # @private
   # A wrapper around a native kafka that polls and cleanly exits
   class NativeKafka
-    def initialize(inner, run_polling_thread:, opaque:, auto_start: true, timeout_ms: 100)
+    # Creates a new NativeKafka wrapper
+    # @param inner [FFI::Pointer] pointer to the native Kafka handle
+    # @param run_polling_thread [Boolean] whether to run a background polling thread
+    # @param opaque [Rdkafka::Opaque] opaque object for callback context
+    # @param auto_start [Boolean] whether to start the polling thread automatically
+    # @param timeout_ms [Integer] poll timeout in milliseconds
+    def initialize(inner, run_polling_thread:, opaque:, auto_start: true, timeout_ms: Defaults::NATIVE_KAFKA_POLL_TIMEOUT_MS)
       @inner = inner
       @opaque = opaque
       # Lock around external access
@@ -37,6 +43,8 @@ module Rdkafka
       @closing = false
     end
 
+    # Starts the polling thread if configured
+    # @return [nil]
     def start
       synchronize do
         return if @started
@@ -62,13 +70,17 @@ module Rdkafka
             end
           end
 
-          @polling_thread.name = "rdkafka.native_kafka##{Rdkafka::Bindings.rd_kafka_name(@inner).gsub('rdkafka', '')}"
+          @polling_thread.name = "rdkafka.native_kafka##{Rdkafka::Bindings.rd_kafka_name(@inner).gsub("rdkafka", "")}"
           @polling_thread.abort_on_exception = true
           @polling_thread[:closing] = false
         end
       end
     end
 
+    # Executes a block with the inner native Kafka handle
+    # @yield [FFI::Pointer] the inner native Kafka handle
+    # @return [Object] the result of the block
+    # @raise [ClosedInnerError] when the inner handle is nil
     def with_inner
       if @access_mutex.owned?
         @operations_in_progress += 1
@@ -81,27 +93,100 @@ module Rdkafka
       @decrement_mutex.synchronize { @operations_in_progress -= 1 }
     end
 
+    # Executes a block while holding exclusive access to the native Kafka handle
+    # @param block [Proc] block to execute with the native handle
+    # @yield [FFI::Pointer] the inner native Kafka handle
+    # @return [Object] the result of the block
     def synchronize(&block)
       @access_mutex.synchronize do
         # Wait for any commands using the inner to finish
         # This can take a while on blocking operations like polling but is essential not to proceed
         # with certain types of operations like resources destruction as it can cause the process
         # to hang or crash
-        sleep(0.01) until @operations_in_progress.zero?
+        sleep(Defaults::NATIVE_KAFKA_SYNCHRONIZE_SLEEP_INTERVAL_MS / 1000.0) until @operations_in_progress.zero?
 
         with_inner(&block)
       end
     end
 
+    # Returns a finalizer proc for closing this native Kafka handle
+    # @return [Proc] finalizer proc
     def finalizer
       ->(_) { close }
     end
 
+    # Returns whether this native Kafka handle is closed or closing
+    # @return [Boolean] true if closed or closing
     def closed?
       @closing || @inner.nil?
     end
 
-    def close(object_id=nil)
+    # Enable IO event notifications on the main queue
+    # Librdkafka will write to your FD when the queue transitions from empty to non-empty
+    #
+    # @note This method is incompatible with background polling threads.
+    #   If background polling is enabled, use manual polling instead (e.g., consumer.poll)
+    #
+    # @param fd [Integer] your file descriptor (from IO.pipe or eventfd)
+    # @param payload [String] data to write to fd when queue has data (default: "\x01")
+    # @return [nil]
+    # @raise [ClosedInnerError] when the handle is closed
+    # @raise [RuntimeError] when background polling thread is active
+    #
+    # @example
+    #   # Create your own signaling FD
+    #   signal_r, signal_w = IO.pipe
+    #   native_kafka.enable_main_queue_io_events(signal_w.fileno)
+    #
+    #   # Monitor it with select
+    #   readable, = IO.select([signal_r], nil, nil, timeout)
+    #   if readable
+    #     consumer.poll(0)  # Get messages
+    #   end
+    def enable_main_queue_io_events(fd, payload = "\x01")
+      if @run_polling_thread
+        raise "Cannot enable IO events while background polling thread is active. " \
+          "Either disable background polling by setting run_polling_thread: false, " \
+          "or use manual polling with consumer.poll() instead of the FD API."
+      end
+
+      with_inner do |inner|
+        queue_ptr = Bindings.rd_kafka_queue_get_main(inner)
+        Bindings.rd_kafka_queue_io_event_enable(queue_ptr, fd, payload, payload.bytesize)
+        Bindings.rd_kafka_queue_destroy(queue_ptr)
+      end
+    end
+
+    # Enable IO event notifications on the background queue
+    # Librdkafka will write to your FD when the background queue transitions from empty to non-empty
+    #
+    # @note This method is incompatible with background polling threads.
+    #   If background polling is enabled, use manual polling instead (e.g., consumer.poll)
+    #
+    # @param fd [Integer] your file descriptor (from IO.pipe or eventfd)
+    # @param payload [String] data to write to fd when queue has data (default: "\x01")
+    # @return [nil]
+    # @raise [ClosedInnerError] when the handle is closed
+    # @raise [RuntimeError] when background polling thread is active
+    def enable_background_queue_io_events(fd, payload = "\x01")
+      if @run_polling_thread
+        raise "Cannot enable IO events while background polling thread is active. " \
+          "Either disable background polling by setting run_polling_thread: false, " \
+          "or use manual polling with consumer.poll() instead of the FD API."
+      end
+
+      with_inner do |inner|
+        queue_ptr = Bindings.rd_kafka_queue_get_background(inner)
+        Bindings.rd_kafka_queue_io_event_enable(queue_ptr, fd, payload, payload.bytesize)
+        Bindings.rd_kafka_queue_destroy(queue_ptr)
+      end
+    end
+
+    # Closes the native Kafka handle and cleans up resources
+    # @param object_id [Integer, nil] optional object ID (unused, for finalizer compatibility)
+    # @yield optional block to execute before destroying the handle
+    # @return [nil]
+    def close(object_id = nil)
       return if closed?
 
       synchronize do

data/lib/rdkafka/producer/delivery_handle.rb

@@ -6,10 +6,10 @@ module Rdkafka
     # producing a message.
     class DeliveryHandle < Rdkafka::AbstractHandle
       layout :pending, :bool,
-             :response, :int,
-             :partition, :int,
-             :offset, :int64,
-             :topic_name, :pointer
+        :response, :int,
+        :partition, :int,
+        :offset, :int64,
+        :topic_name, :pointer
 
       # @return [Object, nil] label set during message production or nil by default
       attr_accessor :label
@@ -31,7 +31,7 @@ module Rdkafka
           # For part of errors, we will not get a topic name reference and in cases like this
           # we should not return it
           topic,
-          self[:response] != 0 ? RdkafkaError.new(self[:response]) : nil,
+          (self[:response] != 0) ? RdkafkaError.new(self[:response]) : nil,
           label
         )
       end

data/lib/rdkafka/producer/delivery_report.rb

@@ -12,8 +12,8 @@ module Rdkafka
       # @return [Integer]
       attr_reader :offset
 
-      # The name of the topic this message was produced to or nil in case of reports with errors
-      # where topic was not reached.
+      # The name of the topic this message was produced to or nil in case delivery failed and we
+      #   we not able to get the topic reference
       #
       # @return [String, nil]
       attr_reader :topic_name
@@ -30,10 +30,14 @@ module Rdkafka
       # is present in both places
       #
       # We do not remove the original `#topic_name` because of backwards compatibility
-      alias topic topic_name
-
-      private
-
+      alias_method :topic, :topic_name
+
+      # @private
+      # @param partition [Integer] partition number
+      # @param offset [Integer] message offset
+      # @param topic_name [String, nil] topic name
+      # @param error [Integer, nil] error code if any
+      # @param label [Object, nil] user-defined label
       def initialize(partition, offset, topic_name = nil, error = nil, label = nil)
         @partition = partition
         @offset = offset