rdkafka 0.22.2 → 0.27.0

data/lib/rdkafka/abstract_handle.rb

@@ -54,16 +54,34 @@ module Rdkafka
     # If there is a timeout this does not mean the operation failed, rdkafka might still be working
     # on the operation. In this case it is possible to call wait again.
     #
-    # @param max_wait_timeout [Numeric, nil] Amount of time to wait before timing out.
-    #   If this is nil we will wait forever
+    # @param max_wait_timeout [Numeric, nil] DEPRECATED: Use max_wait_timeout_ms instead.
+    #   Amount of time in seconds to wait before timing out. Will be removed in v1.0.0.
+    # @param max_wait_timeout_ms [Numeric, nil] Amount of time in milliseconds to wait before
+    #   timing out. If this is nil we will wait forever. Defaults to 60,000ms (60 seconds).
     # @param raise_response_error [Boolean] should we raise error when waiting finishes
     #
     # @return [Object] Operation-specific result
     #
     # @raise [RdkafkaError] When the operation failed
     # @raise [WaitTimeoutError] When the timeout has been reached and the handle is still pending
-    def wait(max_wait_timeout: 60, raise_response_error: true)
-      timeout = max_wait_timeout ? monotonic_now + max_wait_timeout : MAX_WAIT_TIMEOUT_FOREVER
+    def wait(max_wait_timeout: :not_provided, max_wait_timeout_ms: :not_provided, raise_response_error: true)
+      # Determine which timeout value to use
+      if max_wait_timeout != :not_provided && max_wait_timeout_ms != :not_provided
+        warn "DEPRECATION WARNING: Both max_wait_timeout and max_wait_timeout_ms were provided. " \
+             "Using max_wait_timeout_ms. The max_wait_timeout parameter is deprecated and will be removed in v1.0.0."
+        timeout_ms = max_wait_timeout_ms
+      elsif max_wait_timeout != :not_provided
+        warn "DEPRECATION WARNING: max_wait_timeout (seconds) is deprecated. " \
+             "Use max_wait_timeout_ms (milliseconds) instead. This parameter will be removed in v1.0.0."
+        timeout_ms = max_wait_timeout ? (max_wait_timeout * 1000).to_i : nil
+      elsif max_wait_timeout_ms == :not_provided
+        timeout_ms = Defaults::HANDLE_WAIT_TIMEOUT_MS
+      else
+        timeout_ms = max_wait_timeout_ms
+      end
+
+      timeout_s = timeout_ms ? timeout_ms / 1000.0 : nil
+      timeout = timeout_s ? monotonic_now + timeout_s : MAX_WAIT_TIMEOUT_FOREVER
 
       @mutex.synchronize do
         loop do
@@ -74,7 +92,7 @@ module Rdkafka
               @resource.wait(@mutex, to_wait)
             else
               raise WaitTimeoutError.new(
-                "Waiting for #{operation_name} timed out after #{max_wait_timeout} seconds"
+                "Waiting for #{operation_name} timed out after #{timeout_ms} ms"
               )
             end
           elsif self[:response] != 0 && raise_response_error

data/lib/rdkafka/admin/acl_binding_result.rb

@@ -3,17 +3,17 @@
 module Rdkafka
   class Admin
     # Extracts attributes of rd_kafka_AclBinding_t
-    #
     class AclBindingResult
       attr_reader :result_error, :error_string, :matching_acl_resource_type,
-                  :matching_acl_resource_name, :matching_acl_resource_pattern_type,
-                  :matching_acl_principal, :matching_acl_host, :matching_acl_operation,
-                  :matching_acl_permission_type
+        :matching_acl_resource_name, :matching_acl_resource_pattern_type,
+        :matching_acl_principal, :matching_acl_host, :matching_acl_operation,
+        :matching_acl_permission_type
 
       # This attribute was initially released under the name that is now an alias
       # We keep it for backwards compatibility but it was changed for the consistency
-      alias matching_acl_pattern_type matching_acl_resource_pattern_type
+      alias_method :matching_acl_pattern_type, :matching_acl_resource_pattern_type
 
+      # @param matching_acl [FFI::Pointer] pointer to the ACL binding struct
       def initialize(matching_acl)
         rd_kafka_error_pointer = Rdkafka::Bindings.rd_kafka_AclBinding_error(matching_acl)
         @result_error = Rdkafka::Bindings.rd_kafka_error_code(rd_kafka_error_pointer)

data/lib/rdkafka/admin/config_resource_binding_result.rb

@@ -6,6 +6,7 @@ module Rdkafka
     class ConfigResourceBindingResult
       attr_reader :name, :type, :configs, :configs_count
 
+      # @param config_resource_ptr [FFI::Pointer] pointer to the config resource struct
       def initialize(config_resource_ptr)
         ffi_binding = Bindings::ConfigResource.new(config_resource_ptr)
 

data/lib/rdkafka/admin/create_acl_handle.rb

@@ -2,10 +2,11 @@
 
 module Rdkafka
   class Admin
+    # Handle for create ACL operation
     class CreateAclHandle < AbstractHandle
       layout :pending, :bool,
-             :response, :int,
-             :response_string, :pointer
+        :response, :int,
+        :response_string, :pointer
 
       # @return [String] the name of the operation
       def operation_name
@@ -17,10 +18,12 @@ module Rdkafka
         CreateAclReport.new(rdkafka_response: self[:response], rdkafka_response_string: self[:response_string])
       end
 
+      # Raises an error if the operation failed
+      # @raise [RdkafkaError]
       def raise_error
         raise RdkafkaError.new(
-            self[:response],
-            broker_message: self[:response_string].read_string
+          self[:response],
+          broker_message: self[:response_string].read_string
         )
       end
     end

data/lib/rdkafka/admin/create_acl_report.rb

@@ -2,17 +2,18 @@
 
 module Rdkafka
   class Admin
+    # Report for create ACL operation result
     class CreateAclReport
-
       # Upon successful creation of Acl RD_KAFKA_RESP_ERR_NO_ERROR - 0 is returned as rdkafka_response
       # @return [Integer]
       attr_reader :rdkafka_response
 
-
       # Upon successful creation of Acl empty string will be returned as rdkafka_response_string
       # @return [String]
       attr_reader :rdkafka_response_string
 
+      # @param rdkafka_response [Integer] response code from librdkafka
+      # @param rdkafka_response_string [FFI::Pointer] pointer to response string
       def initialize(rdkafka_response:, rdkafka_response_string:)
         @rdkafka_response = rdkafka_response
         if rdkafka_response_string != FFI::Pointer::NULL

data/lib/rdkafka/admin/create_partitions_handle.rb

@@ -1,10 +1,11 @@
 module Rdkafka
   class Admin
+    # Handle for create partitions operation
     class CreatePartitionsHandle < AbstractHandle
       layout :pending, :bool,
-             :response, :int,
-             :error_string, :pointer,
-             :result_name, :pointer
+        :response, :int,
+        :error_string, :pointer,
+        :result_name, :pointer
 
       # @return [String] the name of the operation
       def operation_name
@@ -16,10 +17,12 @@ module Rdkafka
         CreatePartitionsReport.new(self[:error_string], self[:result_name])
       end
 
+      # Raises an error if the operation failed
+      # @raise [RdkafkaError]
       def raise_error
         raise RdkafkaError.new(
-            self[:response],
-            broker_message: CreateTopicReport.new(self[:error_string], self[:result_name]).error_string
+          self[:response],
+          broker_message: CreateTopicReport.new(self[:error_string], self[:result_name]).error_string
         )
       end
     end

data/lib/rdkafka/admin/create_partitions_report.rb

@@ -1,5 +1,6 @@
 module Rdkafka
   class Admin
+    # Report for create partitions operation result
     class CreatePartitionsReport < CreateTopicReport
     end
   end

data/lib/rdkafka/admin/create_topic_handle.rb

@@ -2,11 +2,12 @@
 
 module Rdkafka
   class Admin
+    # Handle for create topic operation
     class CreateTopicHandle < AbstractHandle
       layout :pending, :bool,
-             :response, :int,
-             :error_string, :pointer,
-             :result_name, :pointer
+        :response, :int,
+        :error_string, :pointer,
+        :result_name, :pointer
 
       # @return [String] the name of the operation
       def operation_name
@@ -18,10 +19,12 @@ module Rdkafka
         CreateTopicReport.new(self[:error_string], self[:result_name])
       end
 
+      # Raises an error if the operation failed
+      # @raise [RdkafkaError]
       def raise_error
         raise RdkafkaError.new(
-            self[:response],
-            broker_message: CreateTopicReport.new(self[:error_string], self[:result_name]).error_string
+          self[:response],
+          broker_message: CreateTopicReport.new(self[:error_string], self[:result_name]).error_string
         )
       end
     end

data/lib/rdkafka/admin/create_topic_report.rb

@@ -2,6 +2,7 @@
 
 module Rdkafka
   class Admin
+    # Report for create topic operation result
     class CreateTopicReport
       # Any error message generated from the CreateTopic
       # @return [String]
@@ -11,6 +12,8 @@ module Rdkafka
       # @return [String]
       attr_reader :result_name
 
+      # @param error_string [FFI::Pointer] pointer to error string
+      # @param result_name [FFI::Pointer] pointer to topic name
       def initialize(error_string, result_name)
         if error_string != FFI::Pointer::NULL
           @error_string = error_string.read_string

data/lib/rdkafka/admin/delete_acl_handle.rb

@@ -2,12 +2,13 @@
 
 module Rdkafka
   class Admin
+    # Handle for delete ACL operation
     class DeleteAclHandle < AbstractHandle
       layout :pending, :bool,
-             :response, :int,
-             :response_string, :pointer,
-             :matching_acls, :pointer,
-             :matching_acls_count, :int
+        :response, :int,
+        :response_string, :pointer,
+        :matching_acls, :pointer,
+        :matching_acls_count, :int
 
       # @return [String] the name of the operation
       def operation_name
@@ -19,10 +20,12 @@ module Rdkafka
         DeleteAclReport.new(matching_acls: self[:matching_acls], matching_acls_count: self[:matching_acls_count])
       end
 
+      # Raises an error if the operation failed
+      # @raise [RdkafkaError]
       def raise_error
         raise RdkafkaError.new(
-            self[:response],
-            broker_message: self[:response_string].read_string
+          self[:response],
+          broker_message: self[:response_string].read_string
         )
       end
     end

data/lib/rdkafka/admin/delete_acl_report.rb

@@ -2,16 +2,18 @@
 
 module Rdkafka
   class Admin
+    # Report for delete ACL operation result
     class DeleteAclReport
-
       # deleted acls
       # @return [Rdkafka::Bindings::AclBindingResult]
       attr_reader :deleted_acls
 
+      # @param matching_acls [FFI::Pointer] pointer to matching ACLs array
+      # @param matching_acls_count [Integer] number of matching ACLs
       def initialize(matching_acls:, matching_acls_count:)
-        @deleted_acls=[]
+        @deleted_acls = []
         if matching_acls != FFI::Pointer::NULL
-          acl_binding_result_pointers  = matching_acls.read_array_of_pointer(matching_acls_count)
+          acl_binding_result_pointers = matching_acls.read_array_of_pointer(matching_acls_count)
           (1..matching_acls_count).map do |matching_acl_index|
             acl_binding_result = AclBindingResult.new(acl_binding_result_pointers[matching_acl_index - 1])
             @deleted_acls << acl_binding_result

data/lib/rdkafka/admin/delete_groups_handle.rb

@@ -2,25 +2,30 @@
 
 module Rdkafka
   class Admin
+    # Handle for delete groups operation
     class DeleteGroupsHandle < AbstractHandle
       layout :pending, :bool, # TODO: ???
-             :response, :int,
-             :error_string, :pointer,
-             :result_name, :pointer
+        :response, :int,
+        :error_string, :pointer,
+        :result_name, :pointer
 
       # @return [String] the name of the operation
       def operation_name
         "delete groups"
       end
 
+      # Creates the result report
+      # @return [DeleteGroupsReport]
       def create_result
         DeleteGroupsReport.new(self[:error_string], self[:result_name])
       end
 
+      # Raises an error if the operation failed
+      # @raise [RdkafkaError]
       def raise_error
         raise RdkafkaError.new(
-            self[:response],
-            broker_message: create_result.error_string
+          self[:response],
+          broker_message: create_result.error_string
         )
       end
     end

data/lib/rdkafka/admin/delete_groups_report.rb

@@ -2,6 +2,7 @@
 
 module Rdkafka
   class Admin
+    # Report for delete groups operation result
     class DeleteGroupsReport
       # Any error message generated from the DeleteTopic
       # @return [String]
@@ -11,6 +12,8 @@ module Rdkafka
       # @return [String]
       attr_reader :result_name
 
+      # @param error_string [FFI::Pointer] pointer to error string
+      # @param result_name [FFI::Pointer] pointer to group name
       def initialize(error_string, result_name)
         if error_string != FFI::Pointer::NULL
           @error_string = error_string.read_string

data/lib/rdkafka/admin/delete_topic_handle.rb

@@ -2,11 +2,12 @@
 
 module Rdkafka
   class Admin
+    # Handle for delete topic operation
     class DeleteTopicHandle < AbstractHandle
       layout :pending, :bool,
-             :response, :int,
-             :error_string, :pointer,
-             :result_name, :pointer
+        :response, :int,
+        :error_string, :pointer,
+        :result_name, :pointer
 
       # @return [String] the name of the operation
       def operation_name
@@ -18,10 +19,12 @@ module Rdkafka
         DeleteTopicReport.new(self[:error_string], self[:result_name])
       end
 
+      # Raises an error if the operation failed
+      # @raise [RdkafkaError]
       def raise_error
         raise RdkafkaError.new(
-            self[:response],
-            broker_message: DeleteTopicReport.new(self[:error_string], self[:result_name]).error_string
+          self[:response],
+          broker_message: DeleteTopicReport.new(self[:error_string], self[:result_name]).error_string
         )
       end
     end

data/lib/rdkafka/admin/delete_topic_report.rb

@@ -2,6 +2,7 @@
 
 module Rdkafka
   class Admin
+    # Report for delete topic operation result
     class DeleteTopicReport
       # Any error message generated from the DeleteTopic
       # @return [String]
@@ -11,6 +12,8 @@ module Rdkafka
       # @return [String]
       attr_reader :result_name
 
+      # @param error_string [FFI::Pointer] pointer to error string
+      # @param result_name [FFI::Pointer] pointer to topic name
       def initialize(error_string, result_name)
         if error_string != FFI::Pointer::NULL
           @error_string = error_string.read_string

data/lib/rdkafka/admin/describe_acl_handle.rb

@@ -2,12 +2,13 @@
 
 module Rdkafka
   class Admin
+    # Handle for describe ACL operation
     class DescribeAclHandle < AbstractHandle
       layout :pending, :bool,
-             :response, :int,
-             :response_string, :pointer,
-             :acls, :pointer,
-             :acls_count, :int
+        :response, :int,
+        :response_string, :pointer,
+        :acls, :pointer,
+        :acls_count, :int
 
       # @return [String] the name of the operation.
       def operation_name
@@ -19,10 +20,12 @@ module Rdkafka
         DescribeAclReport.new(acls: self[:acls], acls_count: self[:acls_count])
       end
 
+      # Raises an error if the operation failed
+      # @raise [RdkafkaError]
       def raise_error
         raise RdkafkaError.new(
-            self[:response],
-            broker_message: self[:response_string].read_string
+          self[:response],
+          broker_message: self[:response_string].read_string
         )
       end
     end

data/lib/rdkafka/admin/describe_acl_report.rb

@@ -2,17 +2,19 @@
 
 module Rdkafka
   class Admin
+    # Report for describe ACL operation result
     class DescribeAclReport
-
       # acls that exists in the cluster for the resource_type, resource_name and pattern_type filters provided in the request.
       # @return [Rdkafka::Bindings::AclBindingResult] array of matching acls.
       attr_reader :acls
 
+      # @param acls [FFI::Pointer] pointer to ACLs array
+      # @param acls_count [Integer] number of ACLs
       def initialize(acls:, acls_count:)
-        @acls=[]
+        @acls = []
 
         if acls != FFI::Pointer::NULL
-          acl_binding_result_pointers  = acls.read_array_of_pointer(acls_count)
+          acl_binding_result_pointers = acls.read_array_of_pointer(acls_count)
           (1..acls_count).map do |acl_index|
             acl_binding_result = AclBindingResult.new(acl_binding_result_pointers[acl_index - 1])
             @acls << acl_binding_result

data/lib/rdkafka/admin/describe_configs_handle.rb

@@ -2,12 +2,13 @@
 
 module Rdkafka
   class Admin
+    # Handle for describe configs operation
     class DescribeConfigsHandle < AbstractHandle
       layout :pending, :bool,
-             :response, :int,
-             :response_string, :pointer,
-             :config_entries, :pointer,
-             :entry_count, :int
+        :response, :int,
+        :response_string, :pointer,
+        :config_entries, :pointer,
+        :entry_count, :int
 
       # @return [String] the name of the operation.
       def operation_name
@@ -22,6 +23,8 @@ module Rdkafka
         )
       end
 
+      # Raises an error if the operation failed
+      # @raise [RdkafkaError]
       def raise_error
         raise RdkafkaError.new(
           self[:response],

data/lib/rdkafka/admin/describe_configs_report.rb

@@ -2,11 +2,14 @@
 
 module Rdkafka
   class Admin
+    # Report for describe configs operation result
     class DescribeConfigsReport
       attr_reader :resources
 
+      # @param config_entries [FFI::Pointer] pointer to config entries array
+      # @param entry_count [Integer] number of config entries
       def initialize(config_entries:, entry_count:)
-        @resources=[]
+        @resources = []
 
         return if config_entries == FFI::Pointer::NULL
 
@@ -37,6 +40,9 @@ module Rdkafka
 
       private
 
+      # Validates the config resource result and raises an error if invalid
+      # @param config_resource_result_ptr [FFI::Pointer] pointer to the config resource result
+      # @raise [RdkafkaError] when the config resource has an error
       def validate!(config_resource_result_ptr)
         code = Bindings.rd_kafka_ConfigResource_error(config_resource_result_ptr)
 

data/lib/rdkafka/admin/incremental_alter_configs_handle.rb

@@ -2,12 +2,13 @@
 
 module Rdkafka
   class Admin
+    # Handle for incremental alter configs operation
     class IncrementalAlterConfigsHandle < AbstractHandle
       layout :pending, :bool,
-             :response, :int,
-             :response_string, :pointer,
-             :config_entries, :pointer,
-             :entry_count, :int
+        :response, :int,
+        :response_string, :pointer,
+        :config_entries, :pointer,
+        :entry_count, :int
 
       # @return [String] the name of the operation.
       def operation_name
@@ -22,6 +23,8 @@ module Rdkafka
         )
       end
 
+      # Raises an error if the operation failed
+      # @raise [RdkafkaError]
       def raise_error
         raise RdkafkaError.new(
           self[:response],

data/lib/rdkafka/admin/incremental_alter_configs_report.rb

@@ -2,11 +2,14 @@
 
 module Rdkafka
   class Admin
+    # Report for incremental alter configs operation result
     class IncrementalAlterConfigsReport
       attr_reader :resources
 
+      # @param config_entries [FFI::Pointer] pointer to config entries array
+      # @param entry_count [Integer] number of config entries
       def initialize(config_entries:, entry_count:)
-        @resources=[]
+        @resources = []
 
         return if config_entries == FFI::Pointer::NULL
 
@@ -37,6 +40,9 @@ module Rdkafka
 
       private
 
+      # Validates the config resource result and raises an error if invalid
+      # @param config_resource_result_ptr [FFI::Pointer] pointer to the config resource result
+      # @raise [RdkafkaError] when the config resource has an error
       def validate!(config_resource_result_ptr)
         code = Bindings.rd_kafka_ConfigResource_error(config_resource_result_ptr)
 

data/lib/rdkafka/admin/list_offsets_handle.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Rdkafka
+  class Admin
+    # Handle for list offsets operation
+    class ListOffsetsHandle < AbstractHandle
+      layout :pending, :bool,
+        :response, :int,
+        :response_string, :pointer,
+        :result_infos, :pointer,
+        :result_count, :int
+
+      # @return [String] the name of the operation.
+      def operation_name
+        "list offsets"
+      end
+
+      # @return [ListOffsetsReport] instance with partition offset information.
+      def create_result
+        ListOffsetsReport.new(
+          result_infos: self[:result_infos],
+          result_count: self[:result_count]
+        )
+      end
+
+      # Raises an error if the operation failed
+      # @raise [RdkafkaError]
+      def raise_error
+        raise RdkafkaError.new(
+          self[:response],
+          broker_message: self[:response_string].read_string
+        )
+      end
+    end
+  end
+end

data/lib/rdkafka/admin/list_offsets_report.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Rdkafka
+  class Admin
+    # Report for list offsets operation result
+    class ListOffsetsReport
+      attr_reader :offsets
+
+      # @param result_infos [FFI::Pointer] pointer to result info array
+      # @param result_count [Integer] number of result info entries
+      def initialize(result_infos:, result_count:)
+        @offsets = []
+
+        return if result_infos.null?
+
+        result_infos
+          .read_array_of_pointer(result_count)
+          .each { |result_info_ptr| validate!(result_info_ptr) }
+          .each do |result_info_ptr|
+            tp_ptr = Bindings.rd_kafka_ListOffsetsResultInfo_topic_partition(result_info_ptr)
+            tp = Bindings::TopicPartition.new(tp_ptr)
+            timestamp = Bindings.rd_kafka_ListOffsetsResultInfo_timestamp(result_info_ptr)
+            leader_epoch = Bindings.rd_kafka_topic_partition_get_leader_epoch(tp_ptr)
+
+            @offsets << {
+              topic: tp[:topic],
+              partition: tp[:partition],
+              offset: tp[:offset],
+              timestamp: timestamp,
+              leader_epoch: (leader_epoch == -1) ? nil : leader_epoch
+            }
+          end
+      end
+
+      private
+
+      # Validates the partition result and raises an error if invalid
+      # @param result_info_ptr [FFI::Pointer] pointer to the result info
+      # @raise [RdkafkaError] when the partition has an error
+      def validate!(result_info_ptr)
+        tp_ptr = Bindings.rd_kafka_ListOffsetsResultInfo_topic_partition(result_info_ptr)
+        tp = Bindings::TopicPartition.new(tp_ptr)
+        code = tp[:err]
+
+        return if code.zero?
+
+        raise RdkafkaError.new(code)
+      end
+    end
+  end
+end