rdkafka 0.24.2 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b0467e6f670f137f458bb1cb856f812ba2292c45a4c2a4b19477531fd59a3b7
-  data.tar.gz: 9e18e607e5114b7ed31266565c308517729890e643a68b8535d19fb8df4f8256
+  metadata.gz: 6e080c8b1e6e04090b729bcea44d0d35ab53083c7878c952e0e09146318ccf66
+  data.tar.gz: aee7d2f5e8d71de67e25ff89192f8f02f065c3dea3978e1850dac7c823e4fb17
 SHA512:
-  metadata.gz: d90b9aff5f184ec165c37451773845f66c71cfa47dc4dbf62d4764c009711ac28ab40fe4b3ecc083c2b599043f3906d552b52a1296fcbee089a8024a03c16e9e
-  data.tar.gz: 91db6ebb4e3dde0d98395c1714205bae0a5027b31f4d1a1fa435171873d81998efa56c76bdb2c8a410f3cbb3d4348ae847d564d8c2348884d0a7ee080877e7a4
+  metadata.gz: fdcc94f6e3b2f9ac318f2e3146987c12b823f016add46e881ab772838df2238a627f84fbb6741fcf3c30ed34b1a00c8197e71faa543db2a9c6f47439dae7a083
+  data.tar.gz: 0e5f9095c34b21c2307d7736b786c1376a1ab976fc0f9cf0a6fb27c6c5e0382ce3ab005701333b50066f23c64cb5fea352f5443ae31c85abc59e1c0cdabf1660

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Rdkafka Changelog
 
+## 0.25.0 (2026-01-20)
+- **[Deprecation]** `AbstractHandle#wait` parameter `max_wait_timeout:` (seconds) is deprecated in favor of `max_wait_timeout_ms:` (milliseconds). The old parameter still works but will be removed in v1.0.0.
+- **[Deprecation]** `PartitionsCountCache` constructor parameter `ttl` (seconds) is deprecated in favor of `ttl_ms:` (milliseconds). The old parameter still works but will be removed in v1.0.0.
+- [Enhancement] Extract all timeout defaults to `Rdkafka::Defaults` module for discoverability and per-call overrides (#310). All time-related values are now in milliseconds for consistency.
+- [Enhancement] Add `timeout_ms` parameter to `Consumer#each` for configurable poll timeout.
+- [Enhancement] Extract non-time configuration values (`METADATA_MAX_RETRIES`, `PARTITIONS_COUNT_CACHE_TTL_MS`) to `Rdkafka::Defaults` module.
+- [Enhancement] Bump librdkafka to `2.12.1`
+- [Enhancement] Add descriptive error messages for glibc compatibility issues with instructions for resolution (#654)
+- [Enhancement] Replace magic numbers with named constants throughout codebase for improved readability and maintainability
+
 ## 0.24.2 (2025-10-31)
 - [Enhancement] Force lock FFI to 1.17.1 or higher to include critical bug fixes around GCC, write barriers, and thread restarts for forks.
 - [Fix] Fix for Core dump when providing extensions to oauthbearer_set_token (dssjoblom)

data/Gemfile

@@ -3,3 +3,12 @@
 source "https://rubygems.org"
 
 gemspec
+
+group :development do
+  gem 'ostruct'
+  gem 'pry'
+  gem 'rspec'
+  gem 'simplecov'
+  gem 'warning'
+  gem 'yard-lint', '~> 1.3.0'
+end

data/README.md

@@ -163,7 +163,8 @@ bundle exec rake produce_messages
 
 | rdkafka-ruby | librdkafka | patches |
 |-|-|-|
-| 0.24.x (Unreleased) | 2.11.1 (2025-08-08) | yes |
+| 0.25.x (Unreleased) | 2.12.1 (2025-10-21) | yes |
+| 0.24.x (2025-10-10) | 2.11.1 (2025-08-18) | yes |
 | 0.23.x (2025-09-04) | 2.11.0 (2025-07-03) | yes |
 | 0.22.x (2025-07-17) | 2.8.0 (2025-01-07)  | yes |
 | 0.21.x (2025-02-13) | 2.8.0 (2025-01-07)  | yes |

data/docker-compose-ssl.yml

@@ -1,7 +1,7 @@
 services:
   kafka:
     container_name: kafka
-    image: confluentinc/cp-kafka:8.1.0
+    image: confluentinc/cp-kafka:8.1.1
     ports:
       - 9092:9092 # Support PLAINTEXT so we can run one docker setup for SSL and PLAINTEXT
       - 9093:9093

data/docker-compose.yml

@@ -1,7 +1,7 @@
 services:
   kafka:
     container_name: kafka
-    image: confluentinc/cp-kafka:8.1.0
+    image: confluentinc/cp-kafka:8.1.1
 
     ports:
       - 9092:9092

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,7 +3,6 @@
 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,
@@ -14,6 +13,7 @@ module Rdkafka
       # We keep it for backwards compatibility but it was changed for the consistency
       alias 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,6 +2,7 @@
 
 module Rdkafka
   class Admin
+    # Handle for create ACL operation
     class CreateAclHandle < AbstractHandle
       layout :pending, :bool,
              :response, :int,
@@ -17,6 +18,8 @@ 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],

data/lib/rdkafka/admin/create_acl_report.rb

@@ -2,6 +2,7 @@
 
 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
@@ -13,6 +14,8 @@ module Rdkafka
       # @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,5 +1,6 @@
 module Rdkafka
   class Admin
+    # Handle for create partitions operation
     class CreatePartitionsHandle < AbstractHandle
       layout :pending, :bool,
              :response, :int,
@@ -16,6 +17,8 @@ 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],

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,6 +2,7 @@
 
 module Rdkafka
   class Admin
+    # Handle for create topic operation
     class CreateTopicHandle < AbstractHandle
       layout :pending, :bool,
              :response, :int,
@@ -18,6 +19,8 @@ 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],

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,6 +2,7 @@
 
 module Rdkafka
   class Admin
+    # Handle for delete ACL operation
     class DeleteAclHandle < AbstractHandle
       layout :pending, :bool,
              :response, :int,
@@ -19,6 +20,8 @@ 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],

data/lib/rdkafka/admin/delete_acl_report.rb

@@ -2,12 +2,15 @@
 
 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=[]
         if matching_acls != FFI::Pointer::NULL

data/lib/rdkafka/admin/delete_groups_handle.rb

@@ -2,6 +2,7 @@
 
 module Rdkafka
   class Admin
+    # Handle for delete groups operation
     class DeleteGroupsHandle < AbstractHandle
       layout :pending, :bool, # TODO: ???
              :response, :int,
@@ -13,10 +14,14 @@ module Rdkafka
         "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],

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,6 +2,7 @@
 
 module Rdkafka
   class Admin
+    # Handle for delete topic operation
     class DeleteTopicHandle < AbstractHandle
       layout :pending, :bool,
              :response, :int,
@@ -18,6 +19,8 @@ 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],

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,6 +2,7 @@
 
 module Rdkafka
   class Admin
+    # Handle for describe ACL operation
     class DescribeAclHandle < AbstractHandle
       layout :pending, :bool,
              :response, :int,
@@ -19,6 +20,8 @@ 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],

data/lib/rdkafka/admin/describe_acl_report.rb

@@ -2,12 +2,15 @@
 
 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=[]
 

data/lib/rdkafka/admin/describe_configs_handle.rb

@@ -2,6 +2,7 @@
 
 module Rdkafka
   class Admin
+    # Handle for describe configs operation
     class DescribeConfigsHandle < AbstractHandle
       layout :pending, :bool,
              :response, :int,
@@ -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,9 +2,12 @@
 
 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=[]
 
@@ -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,6 +2,7 @@
 
 module Rdkafka
   class Admin
+    # Handle for incremental alter configs operation
     class IncrementalAlterConfigsHandle < AbstractHandle
       layout :pending, :bool,
              :response, :int,
@@ -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,9 +2,12 @@
 
 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=[]
 
@@ -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)