karafka-rdkafka 0.14.10 → 0.15.0.alpha2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92d61e2b492453bf19ead6abf1c9377d5222aeba36c19c25caff5641a2c8fb1b
-  data.tar.gz: 4170931c8ced8d09813d22359c36d36da09b3f39d2429daad6a342dd3df2982c
+  metadata.gz: 4f13043e49d80f647a9012f54ec3f54f77c93c275f0a16dbc689b9695a9592ab
+  data.tar.gz: f1d1d8dbba3389280fa19035b9507e46949b4a34a855147dc68642a12f20a045
 SHA512:
-  metadata.gz: ceae2da64aad6589779b60160fc28b5db6bc305c289f76bbf7f0aa034afdf88277b3aa75f4c14ec8b441250e81bca7bf7afededea22c2eb0568753cf6968c2b3
-  data.tar.gz: 61a3c8a40bca6d598782b093f6a2575fcdbe247d6a31c624f95e236015d713e3d2ace38e2fae43b622b9e4c6b37be57ef0f2d508a0a57310d3eeb79404146436
+  metadata.gz: '09c0e2f0171c07b9d70d75d72878b6a8dd039ab2880be4ddf142eb5542637016bc55da799e9ac79f9ecff9adcd7fc63abe17145bb15bda1ab212220b7aeea8c5'
+  data.tar.gz: 2eb1fccc6380ca4841f65a6cd319bcffdf848767e4f791c0230d934ba9588735abd8e7d042f6159226c837d7f501c71cce556d683f5b14045610d4aa987c2b02

data/.gitignore

@@ -10,3 +10,5 @@ ext/librdkafka.*
 doc
 coverage
 vendor
+.idea/
+out/

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Rdkafka Changelog
 
+## 0.15.0 (Unreleased)
+- **[Feature]** Oauthbearer token refresh callback (bruce-szalwinski-he)
+- **[Feature]** Support incremental config describe + alter API (mensfeld)
+- [Enhancement] Replace time poll based wait engine with an event based to improve response times on blocking operations and wait (nijikon + mensfeld)
+- [Change] The `wait_timeout` argument in `AbstractHandle.wait` method is deprecated and will be removed in future versions without replacement. We don't rely on it's value anymore (nijikon)
+
 ## 0.14.10 (2024-02-08)
 - [Fix] Background logger stops working after forking causing memory leaks (mensfeld).
 

data/README.md

@@ -18,7 +18,7 @@ become EOL.
 
 `rdkafka` was written because of the need for a reliable Ruby client for Kafka that supports modern Kafka at [AppSignal](https://appsignal.com). AppSignal runs it in production on very high-traffic systems.
 
-The most important pieces of a Kafka client are implemented, and we aim to provide all relevant consumer, producer, and admin APIs.
+The most essential pieces of a Kafka client are implemented, and we aim to provide all relevant consumer, producer, and admin APIs.
 
 ## Table of content
 
@@ -30,6 +30,7 @@ The most important pieces of a Kafka client are implemented, and we aim to provi
 - [Higher Level Libraries](#higher-level-libraries)
   * [Message Processing Frameworks](#message-processing-frameworks)
   * [Message Publishing Libraries](#message-publishing-libraries)
+- [Forking](#forking)
 - [Development](#development)
 - [Example](#example)
 - [Versions](#versions)
@@ -47,12 +48,13 @@ While rdkafka-ruby aims to simplify the use of librdkafka in Ruby applications,
 
 ## Installation
 
-This gem downloads and compiles librdkafka when it is installed. If you
-If you have any problems installing the gem, please open an issue.
+When installed, this gem downloads and compiles librdkafka. If you have any problems installing the gem, please open an issue.
 
 ## Usage
 
-See the [documentation](https://karafka.io/docs/code/rdkafka-ruby/) for full details on how to use this gem. Two quick examples:
+Please see the [documentation](https://karafka.io/docs/code/rdkafka-ruby/) for full details on how to use this gem. Below are two quick examples.
+
+Unless you are seeking specific low-level capabilities, we **strongly** recommend using [Karafka](https://github.com/karafka/karafka) and [WaterDrop](https://github.com/karafka/waterdrop) when working with Kafka. These are higher-level libraries also maintained by us based on rdkafka-ruby.
 
 ### Consuming Messages
 
@@ -74,7 +76,7 @@ end
 
 ### Producing Messages
 
-Produce a number of messages, put the delivery handles in an array, and
+Produce several messages, put the delivery handles in an array, and
 wait for them before exiting. This way the messages will be batched and
 efficiently sent to Kafka.
 
@@ -95,13 +97,11 @@ end
 delivery_handles.each(&:wait)
 ```
 
-Note that creating a producer consumes some resources that will not be
-released until it `#close` is explicitly called, so be sure to call
-`Config#producer` only as necessary.
+Note that creating a producer consumes some resources that will not be released until it `#close` is explicitly called, so be sure to call `Config#producer` only as necessary.
 
 ## Higher Level Libraries
 
-Currently, there are two actively developed frameworks based on rdkafka-ruby, that provide higher-level API that can be used to work with Kafka messages and one library for publishing messages.
+Currently, there are two actively developed frameworks based on `rdkafka-ruby`, that provide higher-level API that can be used to work with Kafka messages and one library for publishing messages.
 
 ### Message Processing Frameworks
 
@@ -112,6 +112,16 @@ Currently, there are two actively developed frameworks based on rdkafka-ruby, th
 
 * [WaterDrop](https://github.com/karafka/waterdrop) – Standalone Karafka library for producing Kafka messages.
 
+## Forking
+
+When working with `rdkafka-ruby`, it's essential to know that the underlying `librdkafka` library does not support fork-safe operations, even though it is thread-safe. Forking a process after initializing librdkafka clients can lead to unpredictable behavior due to inherited file descriptors and memory states. This limitation requires careful handling, especially in Ruby applications that rely on forking.
+
+To address this, it's highly recommended to:
+
+- Never initialize any `rdkafka-ruby` producers or consumers before forking to avoid state corruption.
+- Before forking, always close any open producers or consumers if you've opened any.
+- Use high-level libraries like [WaterDrop](https://github.com/karafka/waterdrop) and [Karafka](https://github.com/karafka/karafka/), which provide abstractions for handling librdkafka's intricacies.
+
 ## Development
 
 Contributors are encouraged to focus on enhancements that align with the core goal of the library. We appreciate contributions but will likely not accept pull requests for features that:

data/docker-compose.yml

@@ -3,7 +3,7 @@ version: '2'
 services:
   kafka:
     container_name: kafka
-    image: confluentinc/cp-kafka:7.5.3
+    image: confluentinc/cp-kafka:7.6.0
 
     ports:
       - 9092:9092

data/lib/rdkafka/abstract_handle.rb

@@ -14,6 +14,13 @@ module Rdkafka
 
     # Registry for registering all the handles.
     REGISTRY = {}
+    # Default wait timeout is 31 years
+    MAX_WAIT_TIMEOUT_FOREVER = 10_000_000_000
+    # Deprecation message for wait_timeout argument in wait method
+    WAIT_TIMEOUT_DEPRECATION_MESSAGE = "The 'wait_timeout' argument is deprecated and will be removed in future versions without replacement. " \
+      "We don't rely on it's value anymore. Please refactor your code to remove references to it."
+
+    private_constant :MAX_WAIT_TIMEOUT_FOREVER
 
     class << self
       # Adds handle to the register
@@ -32,6 +39,12 @@ module Rdkafka
       end
     end
 
+    def initialize
+      @mutex = Thread::Mutex.new
+      @resource = Thread::ConditionVariable.new
+
+      super
+    end
 
     # Whether the handle is still pending.
     #
@@ -45,37 +58,48 @@ module Rdkafka
     # 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 it does not time out.
-    # @param wait_timeout [Numeric] Amount of time we should wait before we recheck if the
-    #   operation has completed
+    #   If this is nil we will wait forever
+    # @param wait_timeout [nil] deprecated
     # @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, wait_timeout: 0.1, raise_response_error: true)
-      timeout = if max_wait_timeout
-                  monotonic_now + max_wait_timeout
-                else
-                  nil
-                end
-      loop do
-        if pending?
-          if timeout && timeout <= monotonic_now
-            raise WaitTimeoutError.new(
-              "Waiting for #{operation_name} timed out after #{max_wait_timeout} seconds"
-            )
+    def wait(max_wait_timeout: 60, wait_timeout: nil, raise_response_error: true)
+      Kernel.warn(WAIT_TIMEOUT_DEPRECATION_MESSAGE) unless wait_timeout.nil?
+
+      timeout = max_wait_timeout ? monotonic_now + max_wait_timeout : MAX_WAIT_TIMEOUT_FOREVER
+
+      @mutex.synchronize do
+        loop do
+          if pending?
+            to_wait = (timeout - monotonic_now)
+
+            if to_wait.positive?
+              @resource.wait(@mutex, to_wait)
+            else
+              raise WaitTimeoutError.new(
+                "Waiting for #{operation_name} timed out after #{max_wait_timeout} seconds"
+              )
+            end
+          elsif self[:response] != 0 && raise_response_error
+            raise_error
+          else
+            return create_result
           end
-          sleep wait_timeout
-        elsif self[:response] != 0 && raise_response_error
-          raise_error
-        else
-          return create_result
         end
       end
     end
 
+    # Unlock the resources
+    def unlock
+      @mutex.synchronize do
+        self[:pending] = false
+        @resource.broadcast
+      end
+    end
+
     # @return [String] the name of the operation (e.g. "delivery")
     def operation_name
       raise "Must be implemented by subclass!"

data/lib/rdkafka/admin/config_binding_result.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Rdkafka
+  class Admin
+    # A single config binding result that represents its values extracted from C
+    class ConfigBindingResult
+      attr_reader :name, :value, :read_only, :default, :sensitive, :synonym, :synonyms
+
+      # @param config_ptr [FFI::Pointer] config pointer
+      def initialize(config_ptr)
+        @name = Bindings.rd_kafka_ConfigEntry_name(config_ptr)
+        @value = Bindings.rd_kafka_ConfigEntry_value(config_ptr)
+        @read_only = Bindings.rd_kafka_ConfigEntry_is_read_only(config_ptr)
+        @default = Bindings.rd_kafka_ConfigEntry_is_default(config_ptr)
+        @sensitive = Bindings.rd_kafka_ConfigEntry_is_sensitive(config_ptr)
+        @synonym = Bindings.rd_kafka_ConfigEntry_is_synonym(config_ptr)
+        @synonyms = []
+
+        # The code below builds up the config synonyms using same config binding
+        pointer_to_size_t = FFI::MemoryPointer.new(:int32)
+        synonym_ptr = Bindings.rd_kafka_ConfigEntry_synonyms(config_ptr, pointer_to_size_t)
+        synonyms_ptr = synonym_ptr.read_array_of_pointer(pointer_to_size_t.read_int)
+
+        (1..pointer_to_size_t.read_int).map do |ar|
+          @synonyms << self.class.new(synonyms_ptr[ar - 1])
+        end
+      end
+    end
+  end
+end

data/lib/rdkafka/admin/config_resource_binding_result.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Rdkafka
+  class Admin
+    # A simple binding that represents the requested config resource
+    class ConfigResourceBindingResult
+      attr_reader :name, :type, :configs, :configs_count
+
+      def initialize(config_resource_ptr)
+        ffi_binding = Bindings::ConfigResource.new(config_resource_ptr)
+
+        @name = ffi_binding[:name]
+        @type = ffi_binding[:type]
+        @configs = []
+      end
+    end
+  end
+end

data/lib/rdkafka/admin/create_topic_report.rb

@@ -16,7 +16,7 @@ module Rdkafka
           @error_string = error_string.read_string
         end
         if result_name != FFI::Pointer::NULL
-          @result_name = @result_name = result_name.read_string
+          @result_name = result_name.read_string
         end
       end
     end

data/lib/rdkafka/admin/delete_groups_report.rb

@@ -16,7 +16,7 @@ module Rdkafka
           @error_string = error_string.read_string
         end
         if result_name != FFI::Pointer::NULL
-          @result_name = @result_name = result_name.read_string
+          @result_name = result_name.read_string
         end
       end
     end

data/lib/rdkafka/admin/delete_topic_report.rb

@@ -16,7 +16,7 @@ module Rdkafka
           @error_string = error_string.read_string
         end
         if result_name != FFI::Pointer::NULL
-          @result_name = @result_name = result_name.read_string
+          @result_name = result_name.read_string
         end
       end
     end

data/lib/rdkafka/admin/describe_acl_report.rb

@@ -10,6 +10,7 @@ module Rdkafka
 
       def initialize(acls:, acls_count:)
         @acls=[]
+
         if acls != FFI::Pointer::NULL
           acl_binding_result_pointers  = acls.read_array_of_pointer(acls_count)
           (1..acls_count).map do |acl_index|

data/lib/rdkafka/admin/describe_configs_handle.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Rdkafka
+  class Admin
+    class DescribeConfigsHandle < AbstractHandle
+      layout :pending, :bool,
+             :response, :int,
+             :response_string, :pointer,
+             :config_entries, :pointer,
+             :entry_count, :int
+
+      # @return [String] the name of the operation.
+      def operation_name
+        "describe configs"
+      end
+
+      # @return [DescribeAclReport] instance with an array of acls that matches the request filters.
+      def create_result
+        DescribeConfigsReport.new(
+          config_entries: self[:config_entries],
+          entry_count: self[:entry_count]
+        )
+      end
+
+      def raise_error
+        raise RdkafkaError.new(
+          self[:response],
+          broker_message: self[:response_string].read_string
+        )
+      end
+    end
+  end
+end

data/lib/rdkafka/admin/describe_configs_report.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Rdkafka
+  class Admin
+    class DescribeConfigsReport
+      attr_reader :resources
+
+      def initialize(config_entries:, entry_count:)
+        @resources=[]
+
+        return if config_entries == FFI::Pointer::NULL
+
+        config_entries
+          .read_array_of_pointer(entry_count)
+          .each { |config_resource_result_ptr| validate!(config_resource_result_ptr) }
+          .each do |config_resource_result_ptr|
+            config_resource_result = ConfigResourceBindingResult.new(config_resource_result_ptr)
+
+            pointer_to_size_t = FFI::MemoryPointer.new(:int32)
+            configs_ptr = Bindings.rd_kafka_ConfigResource_configs(
+              config_resource_result_ptr,
+              pointer_to_size_t
+            )
+
+            configs_ptr
+              .read_array_of_pointer(pointer_to_size_t.read_int)
+              .map { |config_ptr| ConfigBindingResult.new(config_ptr) }
+              .each { |config_binding| config_resource_result.configs << config_binding }
+
+            @resources << config_resource_result
+          end
+      ensure
+        return if config_entries == FFI::Pointer::NULL
+
+        Bindings.rd_kafka_ConfigResource_destroy_array(config_entries, entry_count)
+      end
+
+      private
+
+      def validate!(config_resource_result_ptr)
+        RdkafkaError.validate!(
+          Bindings.rd_kafka_ConfigResource_error(config_resource_result_ptr),
+          Bindings.rd_kafka_ConfigResource_error_string(config_resource_result_ptr)
+        )
+      end
+    end
+  end
+end

data/lib/rdkafka/admin/incremental_alter_configs_handle.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Rdkafka
+  class Admin
+    class IncrementalAlterConfigsHandle < AbstractHandle
+      layout :pending, :bool,
+             :response, :int,
+             :response_string, :pointer,
+             :config_entries, :pointer,
+             :entry_count, :int
+
+      # @return [String] the name of the operation.
+      def operation_name
+        "incremental alter configs"
+      end
+
+      # @return [DescribeAclReport] instance with an array of acls that matches the request filters.
+      def create_result
+        IncrementalAlterConfigsReport.new(
+          config_entries: self[:config_entries],
+          entry_count: self[:entry_count]
+        )
+      end
+
+      def raise_error
+        raise RdkafkaError.new(
+          self[:response],
+          broker_message: self[:response_string].read_string
+        )
+      end
+    end
+  end
+end

data/lib/rdkafka/admin/incremental_alter_configs_report.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Rdkafka
+  class Admin
+    class IncrementalAlterConfigsReport
+      attr_reader :resources
+
+      def initialize(config_entries:, entry_count:)
+        @resources=[]
+
+        return if config_entries == FFI::Pointer::NULL
+
+        config_entries
+          .read_array_of_pointer(entry_count)
+          .each { |config_resource_result_ptr| validate!(config_resource_result_ptr) }
+          .each do |config_resource_result_ptr|
+            config_resource_result = ConfigResourceBindingResult.new(config_resource_result_ptr)
+
+            pointer_to_size_t = FFI::MemoryPointer.new(:int32)
+            configs_ptr = Bindings.rd_kafka_ConfigResource_configs(
+              config_resource_result_ptr,
+              pointer_to_size_t
+            )
+
+            configs_ptr
+              .read_array_of_pointer(pointer_to_size_t.read_int)
+              .map { |config_ptr| ConfigBindingResult.new(config_ptr) }
+              .each { |config_binding| config_resource_result.configs << config_binding }
+
+            @resources << config_resource_result
+          end
+      ensure
+        return if config_entries == FFI::Pointer::NULL
+
+        Bindings.rd_kafka_ConfigResource_destroy_array(config_entries, entry_count)
+      end
+
+      private
+
+      def validate!(config_resource_result_ptr)
+        RdkafkaError.validate!(
+          Bindings.rd_kafka_ConfigResource_error(config_resource_result_ptr),
+          Bindings.rd_kafka_ConfigResource_error_string(config_resource_result_ptr)
+        )
+      end
+    end
+  end
+end

data/lib/rdkafka/admin.rb

@@ -2,6 +2,8 @@
 
 module Rdkafka
   class Admin
+    include Helpers::OAuth
+
     # @private
     def initialize(native_kafka)
       @native_kafka = native_kafka
@@ -605,6 +607,165 @@ module Rdkafka
       describe_acl_handle
     end
 
+    # Describe configs
+    #
+    # @param resources [Array<Hash>]  Array where elements are hashes with two keys:
+    #   - `:resource_type` - numerical resource type based on Kafka API
+    #   - `:resource_name` - string with resource name
+    # @return [DescribeConfigsHandle] Describe config handle that can be used to wait for the
+    #   result of fetching resources with their appropriate configs
+    #
+    # @raise [RdkafkaError]
+    #
+    # @note Several resources can be requested at one go, but only one broker at a time
+    def describe_configs(resources)
+      closed_admin_check(__method__)
+
+      handle = DescribeConfigsHandle.new
+      handle[:pending] = true
+      handle[:response] = -1
+
+      queue_ptr = @native_kafka.with_inner do |inner|
+        Rdkafka::Bindings.rd_kafka_queue_get_background(inner)
+      end
+
+      if queue_ptr.null?
+        raise Rdkafka::Config::ConfigError.new("rd_kafka_queue_get_background was NULL")
+      end
+
+      admin_options_ptr = @native_kafka.with_inner do |inner|
+        Rdkafka::Bindings.rd_kafka_AdminOptions_new(
+          inner,
+          Rdkafka::Bindings::RD_KAFKA_ADMIN_OP_DESCRIBECONFIGS
+        )
+      end
+
+      DescribeConfigsHandle.register(handle)
+      Rdkafka::Bindings.rd_kafka_AdminOptions_set_opaque(admin_options_ptr, handle.to_ptr)
+
+      pointer_array = resources.map do |resource_details|
+        Rdkafka::Bindings.rd_kafka_ConfigResource_new(
+          resource_details.fetch(:resource_type),
+          FFI::MemoryPointer.from_string(
+            resource_details.fetch(:resource_name)
+          )
+        )
+      end
+
+      configs_array_ptr = FFI::MemoryPointer.new(:pointer, pointer_array.size)
+      configs_array_ptr.write_array_of_pointer(pointer_array)
+
+      begin
+        @native_kafka.with_inner do |inner|
+          Rdkafka::Bindings.rd_kafka_DescribeConfigs(
+            inner,
+            configs_array_ptr,
+            pointer_array.size,
+            admin_options_ptr,
+            queue_ptr
+          )
+        end
+      rescue Exception
+        DescribeConfigsHandle.remove(handle.to_ptr.address)
+
+        raise
+      ensure
+        Rdkafka::Bindings.rd_kafka_ConfigResource_destroy_array(
+          configs_array_ptr,
+          pointer_array.size
+        ) if configs_array_ptr
+      end
+
+      handle
+    end
+
+    # Alters in an incremental way all the configs provided for given resources
+    #
+    # @param resources_with_configs [Array<Hash>] resources with the configs key that contains
+    # name, value and the proper op_type to perform on this value.
+    #
+    # @return [IncrementalAlterConfigsHandle] Incremental alter configs handle that can be used to
+    #   wait for the result of altering resources with their appropriate configs
+    #
+    # @raise [RdkafkaError]
+    #
+    # @note Several resources can be requested at one go, but only one broker at a time
+    # @note The results won't contain altered values but only the altered resources
+    def incremental_alter_configs(resources_with_configs)
+      closed_admin_check(__method__)
+
+      handle = IncrementalAlterConfigsHandle.new
+      handle[:pending] = true
+      handle[:response] = -1
+
+      queue_ptr = @native_kafka.with_inner do |inner|
+        Rdkafka::Bindings.rd_kafka_queue_get_background(inner)
+      end
+
+      if queue_ptr.null?
+        raise Rdkafka::Config::ConfigError.new("rd_kafka_queue_get_background was NULL")
+      end
+
+      admin_options_ptr = @native_kafka.with_inner do |inner|
+        Rdkafka::Bindings.rd_kafka_AdminOptions_new(
+          inner,
+          Rdkafka::Bindings::RD_KAFKA_ADMIN_OP_INCREMENTALALTERCONFIGS
+        )
+      end
+
+      IncrementalAlterConfigsHandle.register(handle)
+      Rdkafka::Bindings.rd_kafka_AdminOptions_set_opaque(admin_options_ptr, handle.to_ptr)
+
+      # Tu poprawnie tworzyc
+      pointer_array = resources_with_configs.map do |resource_details|
+        # First build the appropriate resource representation
+        resource_ptr = Rdkafka::Bindings.rd_kafka_ConfigResource_new(
+          resource_details.fetch(:resource_type),
+          FFI::MemoryPointer.from_string(
+            resource_details.fetch(:resource_name)
+          )
+        )
+
+        resource_details.fetch(:configs).each do |config|
+          Bindings.rd_kafka_ConfigResource_add_incremental_config(
+            resource_ptr,
+            config.fetch(:name),
+            config.fetch(:op_type),
+            config.fetch(:value)
+          )
+        end
+
+        resource_ptr
+      end
+
+      configs_array_ptr = FFI::MemoryPointer.new(:pointer, pointer_array.size)
+      configs_array_ptr.write_array_of_pointer(pointer_array)
+
+
+      begin
+        @native_kafka.with_inner do |inner|
+          Rdkafka::Bindings.rd_kafka_IncrementalAlterConfigs(
+            inner,
+            configs_array_ptr,
+            pointer_array.size,
+            admin_options_ptr,
+            queue_ptr
+          )
+        end
+      rescue Exception
+        IncrementalAlterConfigsHandle.remove(handle.to_ptr.address)
+
+        raise
+      ensure
+        Rdkafka::Bindings.rd_kafka_ConfigResource_destroy_array(
+          configs_array_ptr,
+          pointer_array.size
+        ) if configs_array_ptr
+      end
+
+      handle
+    end
+
     private
 
     def closed_admin_check(method)