karafka-rdkafka 0.23.1.rc2-x86_64-linux-gnu → 0.24.0.rc1-x86_64-linux-gnu

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,8 +28,13 @@ 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)
 
@@ -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,6 +90,7 @@ 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=[]
         rd_kafka_error_pointer = Rdkafka::Bindings.rd_kafka_DeleteAcls_result_response_error(acl_result_pointer)
@@ -84,6 +104,9 @@ module Rdkafka
         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,6 +121,7 @@ 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=[]
         @result_error = Rdkafka::Bindings.rd_kafka_event_error(event_ptr)
@@ -112,9 +136,13 @@ 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=[]
         @result_error = Rdkafka::Bindings.rd_kafka_event_error(event_ptr)
@@ -130,9 +158,13 @@ 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=[]
         @result_error = Rdkafka::Bindings.rd_kafka_event_error(event_ptr)
@@ -150,7 +182,11 @@ module Rdkafka
 
     # @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)
@@ -175,6 +211,8 @@ module Rdkafka
 
       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 +231,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)
@@ -211,6 +251,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)
@@ -229,6 +271,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 +291,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 +311,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 +331,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 +350,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)
 
@@ -322,6 +374,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)
@@ -342,7 +396,11 @@ module Rdkafka
 
     # @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 +431,9 @@ module Rdkafka
       end
     end
 
+    # @private
     @@mutex = Mutex.new
+    # @private
     @@current_pid = nil
 
     class << self

data/lib/rdkafka/config.rb

@@ -71,8 +71,7 @@ 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
@@ -90,8 +89,7 @@ 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] callable object to handle errors
     # @return [nil]
     def self.error_callback=(callback)
       raise TypeError.new("Callback has to be callable") unless callback.respond_to?(:call)
@@ -108,8 +106,7 @@ 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
@@ -235,7 +232,7 @@ module Rdkafka
     #
     # @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)
       # Create opaque
       opaque = Opaque.new
       # Create Kafka config
@@ -270,7 +267,7 @@ module Rdkafka
     #
     # @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)
       opaque = Opaque.new
       config = native_config(opaque)
       Rdkafka::Bindings.rd_kafka_conf_set_background_event_cb(config, Rdkafka::Callbacks::BackgroundEventCallbackFunction)
@@ -301,6 +298,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
@@ -345,6 +345,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(
@@ -374,10 +379,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
     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)
@@ -385,6 +395,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)

data/lib/rdkafka/consumer/message.rb

@@ -28,10 +28,11 @@ module Rdkafka
       # @return [Time, nil]
       attr_reader :timestamp
 
-      # @return [Hash<String, String>] a message headers
+      # @return [Hash{String => String}] message headers
       attr_reader :headers
 
       # @private
+      # @param native_message [Rdkafka::Bindings::Message] native message struct from librdkafka
       def initialize(native_message)
         # Set topic
         unless native_message[:rkt].null?
@@ -71,6 +72,11 @@ module Rdkafka
         "<Message in '#{topic}' with key '#{truncate(key)}', payload '#{truncate(payload)}', partition #{partition}, offset #{offset}, timestamp #{timestamp}#{is_headers}>"
       end
 
+      private
+
+      # Truncates a string for display purposes
+      # @param string [String, nil] the string to truncate
+      # @return [String, nil] truncated string or nil
       def truncate(string)
         if string && string.length > 40
           "#{string[0..39]}..."
@@ -79,8 +85,6 @@ module Rdkafka
         end
       end
 
-      private
-
     end
   end
 end

data/lib/rdkafka/consumer/partition.rb

@@ -21,7 +21,11 @@ module Rdkafka
       attr_reader :metadata
 
       # @private
-      def initialize(partition, offset, err = 0, metadata = nil)
+      # @param partition [Integer] partition number
+      # @param offset [Integer, nil] partition offset
+      # @param err [Integer] error code from librdkafka
+      # @param metadata [String, nil] partition metadata
+      def initialize(partition, offset, err = Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR, metadata = nil)
         @partition = partition
         @offset = offset
         @err = err
@@ -46,6 +50,7 @@ module Rdkafka
       end
 
       # Whether another partition is equal to this
+      # @param other [Object] object to compare with
       # @return [Boolean]
       def ==(other)
         self.class == other.class &&

data/lib/rdkafka/consumer/topic_partition_list.rb

@@ -49,7 +49,6 @@ module Rdkafka
       #
       # @example Add a topic with all topics up to a count
       #   tpl.add_topic("topic", 9)
-      #
       def add_topic(topic, partitions=nil)
         if partitions.nil?
           @data[topic.to_s] = nil
@@ -65,10 +64,8 @@ module Rdkafka
       # Calling this method multiple times for the same topic will overwrite the previous configuraton.
       #
       # @param topic [String] The topic's name
-      # @param partitions_with_offsets [Hash<Integer, Integer>] The topic's partitions and offsets
-      # @param partitions_with_offsets [Array<Consumer::Partition>] The topic's partitions with offsets
-      #   and metadata (if any)
-      #
+      # @param partitions_with_offsets [Hash{Integer => Integer}, Array<Consumer::Partition>] The topic's
+      #   partitions and offsets (Hash) or partitions with offsets and metadata (Array)
       # @return [nil]
       def add_topic_and_partitions_with_offsets(topic, partitions_with_offsets)
         @data[topic.to_s] = partitions_with_offsets.map do |p, o|
@@ -89,6 +86,9 @@ module Rdkafka
         "<TopicPartitionList: #{to_h}>"
       end
 
+      # Check equality with another TopicPartitionList
+      # @param other [TopicPartitionList] object to compare with
+      # @return [Boolean]
       def ==(other)
         self.to_h == other.to_h
       end

data/lib/rdkafka/consumer.rb

@@ -16,6 +16,7 @@ module Rdkafka
     include Helpers::OAuth
 
     # @private
+    # @param native_kafka [NativeKafka] wrapper around the native Kafka consumer handle
     def initialize(native_kafka)
       @native_kafka = native_kafka
     end
@@ -33,6 +34,8 @@ module Rdkafka
       end
     end
 
+    # @return [Proc] finalizer proc for closing the consumer
+    # @private
     def finalizer
       ->(_) { close }
     end
@@ -237,7 +240,7 @@ module Rdkafka
     # @param timeout_ms [Integer] The timeout for fetching this information.
     # @return [TopicPartitionList]
     # @raise [RdkafkaError] When getting the committed positions fails.
-    def committed(list=nil, timeout_ms=2_000)
+    def committed(list = nil, timeout_ms = Defaults::CONSUMER_COMMITTED_TIMEOUT_MS)
       closed_consumer_check(__method__)
 
       if list.nil?
@@ -292,7 +295,7 @@ module Rdkafka
     # @param timeout_ms [Integer] The timeout for querying the broker
     # @return [Integer] The low and high watermark
     # @raise [RdkafkaError] When querying the broker fails.
-    def query_watermark_offsets(topic, partition, timeout_ms=1000)
+    def query_watermark_offsets(topic, partition, timeout_ms = Defaults::CONSUMER_QUERY_WATERMARK_TIMEOUT_MS)
       closed_consumer_check(__method__)
 
       low = FFI::MemoryPointer.new(:int64, 1)
@@ -323,10 +326,10 @@ module Rdkafka
     #
     # @param topic_partition_list [TopicPartitionList] The list to calculate lag for.
     # @param watermark_timeout_ms [Integer] The timeout for each query watermark call.
-    # @return [Hash<String, Hash<Integer, Integer>>] A hash containing all topics with the lag
+    # @return [Hash{String => Hash{Integer => Integer}}] A hash containing all topics with the lag
     #   per partition
     # @raise [RdkafkaError] When querying the broker fails.
-    def lag(topic_partition_list, watermark_timeout_ms=1000)
+    def lag(topic_partition_list, watermark_timeout_ms = Defaults::CONSUMER_LAG_TIMEOUT_MS)
       out = {}
 
       topic_partition_list.to_h.each do |topic, partitions|
@@ -454,7 +457,7 @@ module Rdkafka
         native_topic,
         partition,
         offset,
-        0 # timeout
+        Defaults::CONSUMER_SEEK_TIMEOUT_MS
       )
 
       return nil if response == Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
@@ -471,11 +474,10 @@ module Rdkafka
     # Lookup offset for the given partitions by timestamp.
     #
     # @param list [TopicPartitionList] The TopicPartitionList with timestamps instead of offsets
-    #
+    # @param timeout_ms [Integer] timeout in milliseconds for the operation
     # @return [TopicPartitionList]
-    #
     # @raise [RdKafkaError] When the OffsetForTimes lookup fails
-    def offsets_for_times(list, timeout_ms = 1000)
+    def offsets_for_times(list, timeout_ms = Defaults::CONSUMER_OFFSETS_FOR_TIMES_TIMEOUT_MS)
       closed_consumer_check(__method__)
 
       if !list.is_a?(TopicPartitionList)
@@ -583,7 +585,7 @@ module Rdkafka
     # @note This method technically should be called `#poll` and the current `#poll` should be
     #   called `#consumer_poll` though we keep the current naming convention to make it backward
     #   compatible.
-    def events_poll(timeout_ms = 0)
+    def events_poll(timeout_ms = Defaults::CONSUMER_EVENTS_POLL_TIMEOUT_MS)
       @native_kafka.with_inner do |inner|
         Rdkafka::Bindings.rd_kafka_poll(inner, timeout_ms)
       end
@@ -595,12 +597,13 @@ module Rdkafka
     # If `enable.partition.eof` is turned on in the config this will raise an error when an eof is
     # reached, so you probably want to disable that when using this method of iteration.
     #
+    # @param timeout_ms [Integer] The timeout for each poll
     # @yieldparam message [Message] Received message
     # @return [nil]
     # @raise [RdkafkaError] When polling fails
-    def each
+    def each(timeout_ms: Defaults::CONSUMER_POLL_TIMEOUT_MS)
       loop do
-        message = poll(250)
+        message = poll(timeout_ms)
         if message
           yield(message)
         else
@@ -613,7 +616,13 @@ module Rdkafka
       end
     end
 
-    # Deprecated. Please read the error message for more details.
+    # @deprecated This method has been removed due to data consistency concerns
+    # @param max_items [Integer] unused
+    # @param bytes_threshold [Numeric] unused
+    # @param timeout_ms [Integer] unused
+    # @param yield_on_error [Boolean] unused
+    # @param block [Proc] unused block
+    # @raise [NotImplementedError] Always raises as this method is no longer supported
     def each_batch(max_items: 100, bytes_threshold: Float::INFINITY, timeout_ms: 250, yield_on_error: false, &block)
       raise NotImplementedError, <<~ERROR
         `each_batch` has been removed due to data consistency concerns.
@@ -650,6 +659,9 @@ module Rdkafka
 
     private
 
+    # Checks if the consumer is closed and raises an error if so
+    # @param method [Symbol] name of the calling method for error context
+    # @raise [ClosedConsumerError] when the consumer is closed
     def closed_consumer_check(method)
       raise Rdkafka::ClosedConsumerError.new(method) if closed?
     end

data/lib/rdkafka/defaults.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Rdkafka
+  # Provides default timeout and configuration values used throughout the library.
+  #
+  # These constants standardize timing values across consumers, producers, and admin clients.
+  # Values are specified in milliseconds (ms) unless otherwise noted.
+  module Defaults
+    # Consumer timeout for fetching committed offsets
+    # @see Consumer#committed
+    CONSUMER_COMMITTED_TIMEOUT_MS = 2_000
+
+    # Consumer timeout for querying watermark offsets
+    # @see Consumer#query_watermark_offsets
+    CONSUMER_QUERY_WATERMARK_TIMEOUT_MS = 1_000
+
+    # Consumer timeout for lag calculations
+    # @see Consumer#lag
+    CONSUMER_LAG_TIMEOUT_MS = 1_000
+
+    # Consumer timeout for offset-by-timestamp lookups
+    # @see Consumer#offsets_for_times
+    CONSUMER_OFFSETS_FOR_TIMES_TIMEOUT_MS = 1_000
+
+    # Consumer timeout for poll operations (used in each iteration)
+    # @see Consumer#each
+    CONSUMER_POLL_TIMEOUT_MS = 250
+
+    # Consumer timeout for seek operations (0 = non-blocking)
+    # @see Consumer#seek_by
+    CONSUMER_SEEK_TIMEOUT_MS = 0
+
+    # Consumer timeout for events_poll (0 = non-blocking async)
+    # @see Consumer#events_poll
+    CONSUMER_EVENTS_POLL_TIMEOUT_MS = 0
+
+    # Producer timeout for flush operations
+    # @see Producer#flush
+    PRODUCER_FLUSH_TIMEOUT_MS = 5_000
+
+    # Producer timeout for flush during purge
+    # @see Producer#purge
+    PRODUCER_PURGE_FLUSH_TIMEOUT_MS = 100
+
+    # Sleep interval used in producer purge loop
+    # @see Producer#purge
+    PRODUCER_PURGE_SLEEP_INTERVAL_MS = 1
+
+    # Timeout for transactional send_offsets_to_transaction
+    # @see Producer#send_offsets_to_transaction
+    PRODUCER_SEND_OFFSETS_TIMEOUT_MS = 5_000
+
+    # Default timeout for metadata requests
+    # @see Metadata#initialize
+    # @see Admin#metadata
+    METADATA_TIMEOUT_MS = 2_000
+
+    # Maximum retries for metadata requests on transient errors
+    # @see Metadata#initialize
+    METADATA_MAX_RETRIES = 10
+
+    # Base backoff time for metadata retry (100ms = 0.1s)
+    # @see Metadata#initialize
+    METADATA_RETRY_BACKOFF_BASE_MS = 100
+
+    # Default wait timeout for operation handles
+    # @see AbstractHandle#wait
+    HANDLE_WAIT_TIMEOUT_MS = 60_000
+
+    # Polling interval for NativeKafka background thread
+    # @see NativeKafka#initialize
+    # @see Config#producer
+    # @see Config#admin
+    NATIVE_KAFKA_POLL_TIMEOUT_MS = 100
+
+    # Sleep interval used in NativeKafka#synchronize wait loop
+    # @see NativeKafka#synchronize
+    NATIVE_KAFKA_SYNCHRONIZE_SLEEP_INTERVAL_MS = 10
+
+    # TTL for partitions count cache entries (30 seconds)
+    # @see Producer::PartitionsCountCache
+    PARTITIONS_COUNT_CACHE_TTL_MS = 30_000
+  end
+end