karafka-rdkafka 0.14.10 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92d61e2b492453bf19ead6abf1c9377d5222aeba36c19c25caff5641a2c8fb1b
-  data.tar.gz: 4170931c8ced8d09813d22359c36d36da09b3f39d2429daad6a342dd3df2982c
+  metadata.gz: a8d87787ad144c70fc58e6f70d50581e2ad4e1324089f3b0ebf6c27e42e000ad
+  data.tar.gz: 400929c4f6ae6d617039a716d47088d18a17e6922e93b1e699ebc1755ceeeafa
 SHA512:
-  metadata.gz: ceae2da64aad6589779b60160fc28b5db6bc305c289f76bbf7f0aa034afdf88277b3aa75f4c14ec8b441250e81bca7bf7afededea22c2eb0568753cf6968c2b3
-  data.tar.gz: 61a3c8a40bca6d598782b093f6a2575fcdbe247d6a31c624f95e236015d713e3d2ace38e2fae43b622b9e4c6b37be57ef0f2d508a0a57310d3eeb79404146436
+  metadata.gz: 4b97d0a84d0d0e59d0482533b9e6ca93e91c5963910d6f9b3e4a8f5004fc968fc9a5a0042c65c2f32902de7a38b1126fbc31c296bb913df1e2eb876057dad5f3
+  data.tar.gz: da3ce8ebf3d1726d23f87cc28f2f7f4ede47afc1309dd098212fcab7c0d0b89bf33956282e45669b21a5251c93e89cbd73f13ae02a085b89b7695e035092c187

data/.github/workflows/ci.yml

@@ -25,9 +25,7 @@ jobs:
           - '3.3'
           - '3.2'
           - '3.1'
-          - '3.1.0'
           - '3.0'
-          - '3.0.0'
           - '2.7'
         include:
           - ruby: '3.3'
@@ -37,9 +35,9 @@ jobs:
       - name: Install package dependencies
         run: "[ -e $APT_DEPS ] || sudo apt-get install -y --no-install-recommends $APT_DEPS"
 
-      - name: Start Kafka with docker-compose
+      - name: Start Kafka with docker compose
         run: |
-          docker-compose up -d || (sleep 5 && docker-compose up -d)
+          docker compose up -d || (sleep 5 && docker compose up -d)
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1

data/.gitignore

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

data/.ruby-version

@@ -1 +1 @@
-3.3.0
+3.3.1

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Rdkafka Changelog
 
+## 0.15.0 (2024-04-26)
+- **[Feature]** Oauthbearer token refresh callback (bruce-szalwinski-he)
+- **[Feature]** Support incremental config describe + alter API (mensfeld)
+- [Enhancement] name polling Thread as `rdkafka.native_kafka#<name>` (nijikon)
+- [Enhancement] Replace time poll based wait engine with an event based to improve response times on blocking operations and wait (nijikon + mensfeld)
+- [Enhancement] Allow for usage of the second regex engine of librdkafka by setting `RDKAFKA_DISABLE_REGEX_EXT` during build (mensfeld)
+- [Enhancement] name polling Thread as `rdkafka.native_kafka#<name>` (nijikon)
+- [Change] Allow for native kafka thread operations deferring and manual start for consumer, producer and admin.
+- [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)
+- [Fix] Fix bogus case/when syntax. Levels 1, 2, and 6 previously defaulted to UNKNOWN (jjowdy)
+
 ## 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.1
 
     ports:
       - 9092:9092

data/ext/Rakefile

@@ -27,6 +27,14 @@ task :default => :clean do
       :sha256 => Rdkafka::LIBRDKAFKA_SOURCE_SHA256
     }
     recipe.configure_options = ["--host=#{recipe.host}"]
+
+    # Disable using libc regex engine in favor of the embedded one
+    # The default regex engine of librdkafka does not always work exactly as most of the users
+    # would expect, hence this flag allows for changing it to the other one
+    if ENV.key?('RDKAFKA_DISABLE_REGEX_EXT')
+      recipe.configure_options << '--disable-regex-ext'
+    end
+
     recipe.cook
     # Move dynamic library we're interested in
     if recipe.host.include?('darwin')

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