rdkafka 0.22.2 → 0.29.0

data/lib/rdkafka/admin.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
 module Rdkafka
+  # Admin client for Kafka administrative operations
   class Admin
     include Helpers::OAuth
+    include Helpers::Metadata
 
     class << self
       # Allows us to retrieve librdkafka errors with descriptions
       # Useful for debugging and building UIs, etc.
       #
-      # @return [Hash<Integer, Hash>] hash with errors mapped by code
+      # @return [Hash{Integer => Hash}] hash with errors mapped by code
       def describe_errors
         # Memory pointers for the array of structures and count
         p_error_descs = FFI::MemoryPointer.new(:pointer)
@@ -35,8 +37,8 @@ module Rdkafka
           # Read values from the struct
           code = error_desc[:code]
 
-          name = ''
-          desc = ''
+          name = ""
+          desc = ""
 
           name = error_desc[:name].read_string unless error_desc[:name].null?
           desc = error_desc[:desc].read_string unless error_desc[:desc].null?
@@ -49,6 +51,7 @@ module Rdkafka
     end
 
     # @private
+    # @param native_kafka [NativeKafka] wrapper around the native Kafka handle
     def initialize(native_kafka)
       @native_kafka = native_kafka
 
@@ -69,20 +72,62 @@ module Rdkafka
       end
     end
 
-    def finalizer
-      ->(_) { close }
+    # Enable IO event notifications for fiber scheduler integration
+    # When admin operations complete, librdkafka will write to your FD
+    #
+    # @param fd [Integer] file descriptor to signal (from IO.pipe or eventfd)
+    # @param payload [String] data to write to fd (default: "\x01")
+    # @return [nil]
+    # @raise [ClosedInnerError] when the admin client is closed
+    def enable_queue_io_events(fd, payload = "\x01")
+      @native_kafka.enable_main_queue_io_events(fd, payload)
+    end
+
+    # Enable IO event notifications for background events
+    # @param fd [Integer] file descriptor to signal (from IO.pipe or eventfd)
+    # @param payload [String] data to write to fd (default: "\x01")
+    # @return [nil]
+    # @raise [ClosedInnerError] when the admin client is closed
+    def enable_background_queue_io_events(fd, payload = "\x01")
+      @native_kafka.enable_background_queue_io_events(fd, payload)
     end
 
-    # Performs the metadata request using admin
+    # Polls for events in a non-blocking loop, yielding the count after each iteration.
+    #
+    # This method processes events (stats, errors, etc.) in a single GVL/mutex session,
+    # which is more efficient than repeated individual polls. It uses non-blocking polls
+    # internally (no GVL release between polls).
+    #
+    # Yields the count of events processed after each poll iteration, allowing the caller
+    # to implement timeout or other termination logic by returning `:stop`.
+    #
+    # @yield [count] Called after each poll iteration
+    # @yieldparam count [Integer] Number of events processed in this iteration
+    # @yieldreturn [Symbol, Object] Return `:stop` to break the loop, any other value continues
+    # @return [nil]
+    # @raise [Rdkafka::ClosedAdminError] if called on a closed admin client
+    #
+    # @note This method holds the inner lock until the queue is empty or `:stop` is returned.
+    #   Other admin operations will wait until this method returns.
+    # @note This method is thread-safe as it uses @native_kafka.with_inner synchronization
     #
-    # @param topic_name [String, nil] metadat about particular topic or all if nil
-    # @param timeout_ms [Integer] metadata request timeout
-    # @return [Metadata] requested metadata
-    def metadata(topic_name = nil, timeout_ms = 2_000)
+    # @example Drain all pending events
+    #   admin.events_poll_nb_each { |_count| }
+    #
+    # @example With timeout control
+    #   deadline = monotonic_now + timeout_ms
+    #   admin.events_poll_nb_each do |_count|
+    #     :stop if monotonic_now >= deadline
+    #   end
+    def events_poll_nb_each
       closed_admin_check(__method__)
 
       @native_kafka.with_inner do |inner|
-        Metadata.new(inner, topic_name, timeout_ms)
+        loop do
+          count = Rdkafka::Bindings.rd_kafka_poll_nb(inner, 0)
+          break if count.zero?
+          break if yield(count) == :stop
+        end
       end
     end
 
@@ -100,13 +145,16 @@ module Rdkafka
 
     # Create a topic with the given partition count and replication factor
     #
+    # @param topic_name [String] name of the topic to create
+    # @param partition_count [Integer] number of partitions for the topic
+    # @param replication_factor [Integer] replication factor for the topic
+    # @param topic_config [Hash] optional topic configuration settings
     # @return [CreateTopicHandle] Create topic handle that can be used to wait for the result of
     #   creating the topic
-    #
     # @raise [ConfigError] When the partition count or replication factor are out of valid range
     # @raise [RdkafkaError] When the topic name is invalid or the topic already exists
     # @raise [RdkafkaError] When the topic configuration is invalid
-    def create_topic(topic_name, partition_count, replication_factor, topic_config={})
+    def create_topic(topic_name, partition_count, replication_factor, topic_config = {})
       closed_admin_check(__method__)
 
       # Create a rd_kafka_NewTopic_t representing the new topic
@@ -122,14 +170,12 @@ module Rdkafka
         raise Rdkafka::Config::ConfigError.new(error_buffer.read_string)
       end
 
-      unless topic_config.nil?
-        topic_config.each do |key, value|
-          Rdkafka::Bindings.rd_kafka_NewTopic_set_config(
-            new_topic_ptr,
-            key.to_s,
-            value.to_s
-          )
-        end
+      topic_config&.each do |key, value|
+        Rdkafka::Bindings.rd_kafka_NewTopic_set_config(
+          new_topic_ptr,
+          key.to_s,
+          value.to_s
+        )
       end
 
       # Note that rd_kafka_CreateTopics can create more than one topic at a time
@@ -149,7 +195,7 @@ module Rdkafka
       # Create and register the handle we will return to the caller
       create_topic_handle = CreateTopicHandle.new
       create_topic_handle[:pending] = true
-      create_topic_handle[:response] = -1
+      create_topic_handle[:response] = Rdkafka::Bindings::RD_KAFKA_PARTITION_UA
       CreateTopicHandle.register(create_topic_handle)
       admin_options_ptr = @native_kafka.with_inner do |inner|
         Rdkafka::Bindings.rd_kafka_AdminOptions_new(inner, Rdkafka::Bindings::RD_KAFKA_ADMIN_OP_CREATETOPICS)
@@ -178,6 +224,11 @@ module Rdkafka
       create_topic_handle
     end
 
+    # Deletes a consumer group
+    #
+    # @param group_id [String] the group id to delete
+    # @return [DeleteGroupsHandle] delete groups handle that can be used to wait for the result
+    # @raise [RdkafkaError] When deleting the group fails
     def delete_group(group_id)
       closed_admin_check(__method__)
 
@@ -195,14 +246,14 @@ module Rdkafka
         Rdkafka::Bindings.rd_kafka_queue_get_background(inner)
       end
       if queue_ptr.null?
-        Rdkafka::Bindings.rd_kafka_DeleteTopic_destroy(delete_topic_ptr)
+        Rdkafka::Bindings.rd_kafka_DeleteGroup_destroy(delete_groups_ptr)
         raise Rdkafka::Config::ConfigError.new("rd_kafka_queue_get_background was NULL")
       end
 
       # Create and register the handle we will return to the caller
       delete_groups_handle = DeleteGroupsHandle.new
       delete_groups_handle[:pending] = true
-      delete_groups_handle[:response] = -1
+      delete_groups_handle[:response] = Rdkafka::Bindings::RD_KAFKA_PARTITION_UA
       DeleteGroupsHandle.register(delete_groups_handle)
       admin_options_ptr = @native_kafka.with_inner do |inner|
         Rdkafka::Bindings.rd_kafka_AdminOptions_new(inner, Rdkafka::Bindings::RD_KAFKA_ADMIN_OP_DELETETOPICS)
@@ -233,6 +284,7 @@ module Rdkafka
 
     # Deletes the named topic
     #
+    # @param topic_name [String] name of the topic to delete
     # @return [DeleteTopicHandle] Delete topic handle that can be used to wait for the result of
     #   deleting the topic
     # @raise [RdkafkaError] When the topic name is invalid or the topic does not exist
@@ -259,7 +311,7 @@ module Rdkafka
       # Create and register the handle we will return to the caller
       delete_topic_handle = DeleteTopicHandle.new
       delete_topic_handle[:pending] = true
-      delete_topic_handle[:response] = -1
+      delete_topic_handle[:response] = Rdkafka::Bindings::RD_KAFKA_PARTITION_UA
       DeleteTopicHandle.register(delete_topic_handle)
       admin_options_ptr = @native_kafka.with_inner do |inner|
         Rdkafka::Bindings.rd_kafka_AdminOptions_new(inner, Rdkafka::Bindings::RD_KAFKA_ADMIN_OP_DELETETOPICS)
@@ -290,14 +342,12 @@ module Rdkafka
 
     # Creates extra partitions for a given topic
     #
-    # @param topic_name [String]
+    # @param topic_name [String] name of the topic
     # @param partition_count [Integer] how many partitions we want to end up with for given topic
-    #
+    # @return [CreatePartitionsHandle] Create partitions handle that can be used to wait for the result
     # @raise [ConfigError] When the partition count or replication factor are out of valid range
     # @raise [RdkafkaError] When the topic name is invalid or the topic already exists
     # @raise [RdkafkaError] When the topic configuration is invalid
-    #
-    # @return [CreateTopicHandle] Create topic handle that can be used to wait for the result of creating the topic
     def create_partitions(topic_name, partition_count)
       closed_admin_check(__method__)
 
@@ -327,7 +377,7 @@ module Rdkafka
         # Create and register the handle we will return to the caller
         create_partitions_handle = CreatePartitionsHandle.new
         create_partitions_handle[:pending] = true
-        create_partitions_handle[:response] = -1
+        create_partitions_handle[:response] = Rdkafka::Bindings::RD_KAFKA_PARTITION_UA
         CreatePartitionsHandle.register(create_partitions_handle)
         admin_options_ptr = Rdkafka::Bindings.rd_kafka_AdminOptions_new(inner, Rdkafka::Bindings::RD_KAFKA_ADMIN_OP_CREATEPARTITIONS)
         Rdkafka::Bindings.rd_kafka_AdminOptions_set_opaque(admin_options_ptr, create_partitions_handle.to_ptr)
@@ -354,40 +404,36 @@ module Rdkafka
     end
 
     # Create acl
-    # @param resource_type - values of type rd_kafka_ResourceType_t
-    #        https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L7307
-    #        valid values are:
-    #           RD_KAFKA_RESOURCE_TOPIC   = 2
-    #           RD_KAFKA_RESOURCE_GROUP   = 3
-    #           RD_KAFKA_RESOURCE_BROKER  = 4
-    # @param resource_pattern_type - values of type rd_kafka_ResourcePatternType_t
-    #        https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L7320
-    #        valid values are:
-    #           RD_KAFKA_RESOURCE_PATTERN_MATCH    = 2
-    #           RD_KAFKA_RESOURCE_PATTERN_LITERAL  = 3
-    #           RD_KAFKA_RESOURCE_PATTERN_PREFIXED = 4
-    # @param operation - values of type rd_kafka_AclOperation_t
-    #        https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L8403
-    #        valid values are:
-    #           RD_KAFKA_ACL_OPERATION_ALL              = 2
-    #           RD_KAFKA_ACL_OPERATION_READ             = 3
-    #           RD_KAFKA_ACL_OPERATION_WRITE            = 4
-    #           RD_KAFKA_ACL_OPERATION_CREATE           = 5
-    #           RD_KAFKA_ACL_OPERATION_DELETE           = 6
-    #           RD_KAFKA_ACL_OPERATION_ALTER            = 7
-    #           RD_KAFKA_ACL_OPERATION_DESCRIBE         = 8
-    #           RD_KAFKA_ACL_OPERATION_CLUSTER_ACTION   = 9
-    #           RD_KAFKA_ACL_OPERATION_DESCRIBE_CONFIGS = 10
-    #           RD_KAFKA_ACL_OPERATION_ALTER_CONFIGS    = 11
-    #           RD_KAFKA_ACL_OPERATION_IDEMPOTENT_WRITE = 12
-    # @param permission_type - values of type rd_kafka_AclPermissionType_t
-    #        https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L8435
-    #        valid values are:
-    #           RD_KAFKA_ACL_PERMISSION_TYPE_DENY  = 2
-    #           RD_KAFKA_ACL_PERMISSION_TYPE_ALLOW = 3
     #
+    # @param resource_type [Integer] rd_kafka_ResourceType_t value:
+    #   - RD_KAFKA_RESOURCE_TOPIC   = 2
+    #   - RD_KAFKA_RESOURCE_GROUP   = 3
+    #   - RD_KAFKA_RESOURCE_BROKER  = 4
+    # @param resource_name [String] name of the resource
+    # @param resource_pattern_type [Integer] rd_kafka_ResourcePatternType_t value:
+    #   - RD_KAFKA_RESOURCE_PATTERN_UNKNOWN  = 0
+    #   - RD_KAFKA_RESOURCE_PATTERN_ANY      = 1
+    #   - RD_KAFKA_RESOURCE_PATTERN_MATCH    = 2
+    #   - RD_KAFKA_RESOURCE_PATTERN_LITERAL  = 3
+    #   - RD_KAFKA_RESOURCE_PATTERN_PREFIXED = 4
+    # @param principal [String] principal (e.g., "User:alice")
+    # @param host [String] host address
+    # @param operation [Integer] rd_kafka_AclOperation_t value:
+    #   - RD_KAFKA_ACL_OPERATION_ALL              = 2
+    #   - RD_KAFKA_ACL_OPERATION_READ             = 3
+    #   - RD_KAFKA_ACL_OPERATION_WRITE            = 4
+    #   - RD_KAFKA_ACL_OPERATION_CREATE           = 5
+    #   - RD_KAFKA_ACL_OPERATION_DELETE           = 6
+    #   - RD_KAFKA_ACL_OPERATION_ALTER            = 7
+    #   - RD_KAFKA_ACL_OPERATION_DESCRIBE         = 8
+    #   - RD_KAFKA_ACL_OPERATION_CLUSTER_ACTION   = 9
+    #   - RD_KAFKA_ACL_OPERATION_DESCRIBE_CONFIGS = 10
+    #   - RD_KAFKA_ACL_OPERATION_ALTER_CONFIGS    = 11
+    #   - RD_KAFKA_ACL_OPERATION_IDEMPOTENT_WRITE = 12
+    # @param permission_type [Integer] rd_kafka_AclPermissionType_t value:
+    #   - RD_KAFKA_ACL_PERMISSION_TYPE_DENY  = 2
+    #   - RD_KAFKA_ACL_PERMISSION_TYPE_ALLOW = 3
     # @return [CreateAclHandle] Create acl handle that can be used to wait for the result of creating the acl
-    #
     # @raise [RdkafkaError]
     def create_acl(resource_type:, resource_name:, resource_pattern_type:, principal:, host:, operation:, permission_type:)
       closed_admin_check(__method__)
@@ -427,7 +473,7 @@ module Rdkafka
       # Create and register the handle that we will return to the caller
       create_acl_handle = CreateAclHandle.new
       create_acl_handle[:pending] = true
-      create_acl_handle[:response] = -1
+      create_acl_handle[:response] = Rdkafka::Bindings::RD_KAFKA_PARTITION_UA
       CreateAclHandle.register(create_acl_handle)
 
       admin_options_ptr = @native_kafka.with_inner do |inner|
@@ -460,39 +506,35 @@ module Rdkafka
 
     # Delete acl
     #
-    # @param resource_type - values of type rd_kafka_ResourceType_t
-    #        https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L7307
-    #        valid values are:
-    #           RD_KAFKA_RESOURCE_TOPIC   = 2
-    #           RD_KAFKA_RESOURCE_GROUP   = 3
-    #           RD_KAFKA_RESOURCE_BROKER  = 4
-    # @param resource_pattern_type - values of type rd_kafka_ResourcePatternType_t
-    #        https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L7320
-    #        valid values are:
-    #           RD_KAFKA_RESOURCE_PATTERN_MATCH    = 2
-    #           RD_KAFKA_RESOURCE_PATTERN_LITERAL  = 3
-    #           RD_KAFKA_RESOURCE_PATTERN_PREFIXED = 4
-    # @param operation - values of type rd_kafka_AclOperation_t
-    #        https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L8403
-    #        valid values are:
-    #           RD_KAFKA_ACL_OPERATION_ALL              = 2
-    #           RD_KAFKA_ACL_OPERATION_READ             = 3
-    #           RD_KAFKA_ACL_OPERATION_WRITE            = 4
-    #           RD_KAFKA_ACL_OPERATION_CREATE           = 5
-    #           RD_KAFKA_ACL_OPERATION_DELETE           = 6
-    #           RD_KAFKA_ACL_OPERATION_ALTER            = 7
-    #           RD_KAFKA_ACL_OPERATION_DESCRIBE         = 8
-    #           RD_KAFKA_ACL_OPERATION_CLUSTER_ACTION   = 9
-    #           RD_KAFKA_ACL_OPERATION_DESCRIBE_CONFIGS = 10
-    #           RD_KAFKA_ACL_OPERATION_ALTER_CONFIGS    = 11
-    #           RD_KAFKA_ACL_OPERATION_IDEMPOTENT_WRITE = 12
-    # @param permission_type - values of type rd_kafka_AclPermissionType_t
-    #        https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L8435
-    #        valid values are:
-    #           RD_KAFKA_ACL_PERMISSION_TYPE_DENY  = 2
-    #           RD_KAFKA_ACL_PERMISSION_TYPE_ALLOW = 3
+    # @param resource_type [Integer] rd_kafka_ResourceType_t value:
+    #   - RD_KAFKA_RESOURCE_TOPIC   = 2
+    #   - RD_KAFKA_RESOURCE_GROUP   = 3
+    #   - RD_KAFKA_RESOURCE_BROKER  = 4
+    # @param resource_name [String, nil] name of the resource or nil for any
+    # @param resource_pattern_type [Integer] rd_kafka_ResourcePatternType_t value:
+    #   - RD_KAFKA_RESOURCE_PATTERN_UNKNOWN  = 0
+    #   - RD_KAFKA_RESOURCE_PATTERN_ANY      = 1
+    #   - RD_KAFKA_RESOURCE_PATTERN_MATCH    = 2
+    #   - RD_KAFKA_RESOURCE_PATTERN_LITERAL  = 3
+    #   - RD_KAFKA_RESOURCE_PATTERN_PREFIXED = 4
+    # @param principal [String, nil] principal (e.g., "User:alice") or nil for any
+    # @param host [String, nil] host address or nil for any
+    # @param operation [Integer] rd_kafka_AclOperation_t value:
+    #   - RD_KAFKA_ACL_OPERATION_ALL              = 2
+    #   - RD_KAFKA_ACL_OPERATION_READ             = 3
+    #   - RD_KAFKA_ACL_OPERATION_WRITE            = 4
+    #   - RD_KAFKA_ACL_OPERATION_CREATE           = 5
+    #   - RD_KAFKA_ACL_OPERATION_DELETE           = 6
+    #   - RD_KAFKA_ACL_OPERATION_ALTER            = 7
+    #   - RD_KAFKA_ACL_OPERATION_DESCRIBE         = 8
+    #   - RD_KAFKA_ACL_OPERATION_CLUSTER_ACTION   = 9
+    #   - RD_KAFKA_ACL_OPERATION_DESCRIBE_CONFIGS = 10
+    #   - RD_KAFKA_ACL_OPERATION_ALTER_CONFIGS    = 11
+    #   - RD_KAFKA_ACL_OPERATION_IDEMPOTENT_WRITE = 12
+    # @param permission_type [Integer] rd_kafka_AclPermissionType_t value:
+    #   - RD_KAFKA_ACL_PERMISSION_TYPE_DENY  = 2
+    #   - RD_KAFKA_ACL_PERMISSION_TYPE_ALLOW = 3
     # @return [DeleteAclHandle] Delete acl handle that can be used to wait for the result of deleting the acl
-    #
     # @raise [RdkafkaError]
     def delete_acl(resource_type:, resource_name:, resource_pattern_type:, principal:, host:, operation:, permission_type:)
       closed_admin_check(__method__)
@@ -527,14 +569,14 @@ module Rdkafka
       end
 
       if queue_ptr.null?
-        Rdkafka::Bindings.rd_kafka_AclBinding_destroy(new_acl_ptr)
+        Rdkafka::Bindings.rd_kafka_AclBinding_destroy(delete_acl_ptr)
         raise Rdkafka::Config::ConfigError.new("rd_kafka_queue_get_background was NULL")
       end
 
       # Create and register the handle that we will return to the caller
       delete_acl_handle = DeleteAclHandle.new
       delete_acl_handle[:pending] = true
-      delete_acl_handle[:response] = -1
+      delete_acl_handle[:response] = Rdkafka::Bindings::RD_KAFKA_PARTITION_UA
       DeleteAclHandle.register(delete_acl_handle)
 
       admin_options_ptr = @native_kafka.with_inner do |inner|
@@ -567,39 +609,35 @@ module Rdkafka
 
     # Describe acls
     #
-    # @param resource_type - values of type rd_kafka_ResourceType_t
-    #        https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L7307
-    #        valid values are:
-    #           RD_KAFKA_RESOURCE_TOPIC   = 2
-    #           RD_KAFKA_RESOURCE_GROUP   = 3
-    #           RD_KAFKA_RESOURCE_BROKER  = 4
-    # @param resource_pattern_type - values of type rd_kafka_ResourcePatternType_t
-    #        https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L7320
-    #        valid values are:
-    #           RD_KAFKA_RESOURCE_PATTERN_MATCH    = 2
-    #           RD_KAFKA_RESOURCE_PATTERN_LITERAL  = 3
-    #           RD_KAFKA_RESOURCE_PATTERN_PREFIXED = 4
-    # @param operation - values of type rd_kafka_AclOperation_t
-    #        https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L8403
-    #        valid values are:
-    #           RD_KAFKA_ACL_OPERATION_ALL              = 2
-    #           RD_KAFKA_ACL_OPERATION_READ             = 3
-    #           RD_KAFKA_ACL_OPERATION_WRITE            = 4
-    #           RD_KAFKA_ACL_OPERATION_CREATE           = 5
-    #           RD_KAFKA_ACL_OPERATION_DELETE           = 6
-    #           RD_KAFKA_ACL_OPERATION_ALTER            = 7
-    #           RD_KAFKA_ACL_OPERATION_DESCRIBE         = 8
-    #           RD_KAFKA_ACL_OPERATION_CLUSTER_ACTION   = 9
-    #           RD_KAFKA_ACL_OPERATION_DESCRIBE_CONFIGS = 10
-    #           RD_KAFKA_ACL_OPERATION_ALTER_CONFIGS    = 11
-    #           RD_KAFKA_ACL_OPERATION_IDEMPOTENT_WRITE = 12
-    # @param permission_type - values of type rd_kafka_AclPermissionType_t
-    #        https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L8435
-    #        valid values are:
-    #           RD_KAFKA_ACL_PERMISSION_TYPE_DENY  = 2
-    #           RD_KAFKA_ACL_PERMISSION_TYPE_ALLOW = 3
+    # @param resource_type [Integer] rd_kafka_ResourceType_t value:
+    #   - RD_KAFKA_RESOURCE_TOPIC   = 2
+    #   - RD_KAFKA_RESOURCE_GROUP   = 3
+    #   - RD_KAFKA_RESOURCE_BROKER  = 4
+    # @param resource_name [String, nil] name of the resource or nil for any
+    # @param resource_pattern_type [Integer] rd_kafka_ResourcePatternType_t value:
+    #   - RD_KAFKA_RESOURCE_PATTERN_UNKNOWN  = 0
+    #   - RD_KAFKA_RESOURCE_PATTERN_ANY      = 1
+    #   - RD_KAFKA_RESOURCE_PATTERN_MATCH    = 2
+    #   - RD_KAFKA_RESOURCE_PATTERN_LITERAL  = 3
+    #   - RD_KAFKA_RESOURCE_PATTERN_PREFIXED = 4
+    # @param principal [String, nil] principal (e.g., "User:alice") or nil for any
+    # @param host [String, nil] host address or nil for any
+    # @param operation [Integer] rd_kafka_AclOperation_t value:
+    #   - RD_KAFKA_ACL_OPERATION_ALL              = 2
+    #   - RD_KAFKA_ACL_OPERATION_READ             = 3
+    #   - RD_KAFKA_ACL_OPERATION_WRITE            = 4
+    #   - RD_KAFKA_ACL_OPERATION_CREATE           = 5
+    #   - RD_KAFKA_ACL_OPERATION_DELETE           = 6
+    #   - RD_KAFKA_ACL_OPERATION_ALTER            = 7
+    #   - RD_KAFKA_ACL_OPERATION_DESCRIBE         = 8
+    #   - RD_KAFKA_ACL_OPERATION_CLUSTER_ACTION   = 9
+    #   - RD_KAFKA_ACL_OPERATION_DESCRIBE_CONFIGS = 10
+    #   - RD_KAFKA_ACL_OPERATION_ALTER_CONFIGS    = 11
+    #   - RD_KAFKA_ACL_OPERATION_IDEMPOTENT_WRITE = 12
+    # @param permission_type [Integer] rd_kafka_AclPermissionType_t value:
+    #   - RD_KAFKA_ACL_PERMISSION_TYPE_DENY  = 2
+    #   - RD_KAFKA_ACL_PERMISSION_TYPE_ALLOW = 3
     # @return [DescribeAclHandle] Describe acl handle that can be used to wait for the result of fetching acls
-    #
     # @raise [RdkafkaError]
     def describe_acl(resource_type:, resource_name:, resource_pattern_type:, principal:, host:, operation:, permission_type:)
       closed_admin_check(__method__)
@@ -627,14 +665,14 @@ module Rdkafka
       end
 
       if queue_ptr.null?
-        Rdkafka::Bindings.rd_kafka_AclBinding_destroy(new_acl_ptr)
+        Rdkafka::Bindings.rd_kafka_AclBinding_destroy(describe_acl_ptr)
         raise Rdkafka::Config::ConfigError.new("rd_kafka_queue_get_background was NULL")
       end
 
       # Create and register the handle that we will return to the caller
       describe_acl_handle = DescribeAclHandle.new
       describe_acl_handle[:pending] = true
-      describe_acl_handle[:response] = -1
+      describe_acl_handle[:response] = Rdkafka::Bindings::RD_KAFKA_PARTITION_UA
       DescribeAclHandle.register(describe_acl_handle)
 
       admin_options_ptr = @native_kafka.with_inner do |inner|
@@ -664,7 +702,6 @@ module Rdkafka
       describe_acl_handle
     end
 
-
     # Describe configs
     #
     # @param resources [Array<Hash>]  Array where elements are hashes with two keys:
@@ -679,9 +716,17 @@ module Rdkafka
     def describe_configs(resources)
       closed_admin_check(__method__)
 
+      # Parse user input before allocating any native resources or registering the handle, so a
+      # missing :resource_type / :resource_name key raises with nothing to clean up. Previously the
+      # KeyError leaked the background queue, the AdminOptions, the registered handle and any
+      # ConfigResources already built.
+      parsed_resources = resources.map do |resource_details|
+        [resource_details.fetch(:resource_type), resource_details.fetch(:resource_name)]
+      end
+
       handle = DescribeConfigsHandle.new
       handle[:pending] = true
-      handle[:response] = -1
+      handle[:response] = Rdkafka::Bindings::RD_KAFKA_PARTITION_UA
 
       queue_ptr = @native_kafka.with_inner do |inner|
         Rdkafka::Bindings.rd_kafka_queue_get_background(inner)
@@ -701,12 +746,10 @@ module Rdkafka
       DescribeConfigsHandle.register(handle)
       Rdkafka::Bindings.rd_kafka_AdminOptions_set_opaque(admin_options_ptr, handle.to_ptr)
 
-      pointer_array = resources.map do |resource_details|
+      pointer_array = parsed_resources.map do |resource_type, resource_name|
         Rdkafka::Bindings.rd_kafka_ConfigResource_new(
-          resource_details.fetch(:resource_type),
-          FFI::MemoryPointer.from_string(
-            resource_details.fetch(:resource_name)
-          )
+          resource_type,
+          FFI::MemoryPointer.from_string(resource_name)
         )
       end
 
@@ -728,10 +771,15 @@ module Rdkafka
 
         raise
       ensure
-        Rdkafka::Bindings.rd_kafka_ConfigResource_destroy_array(
-          configs_array_ptr,
-          pointer_array.size
-        ) if configs_array_ptr
+        Rdkafka::Bindings.rd_kafka_AdminOptions_destroy(admin_options_ptr)
+        Rdkafka::Bindings.rd_kafka_queue_destroy(queue_ptr)
+
+        if configs_array_ptr
+          Rdkafka::Bindings.rd_kafka_ConfigResource_destroy_array(
+            configs_array_ptr,
+            pointer_array.size
+          )
+        end
       end
 
       handle
@@ -752,9 +800,22 @@ module Rdkafka
     def incremental_alter_configs(resources_with_configs)
       closed_admin_check(__method__)
 
+      # Parse user input before allocating native resources or registering the handle, so a missing
+      # key raises with nothing to clean up. Previously the KeyError leaked the background queue,
+      # the AdminOptions, the registered handle and any ConfigResources already built.
+      parsed_resources = resources_with_configs.map do |resource_details|
+        [
+          resource_details.fetch(:resource_type),
+          resource_details.fetch(:resource_name),
+          resource_details.fetch(:configs).map do |config|
+            [config.fetch(:name), config.fetch(:op_type), config.fetch(:value)]
+          end
+        ]
+      end
+
       handle = IncrementalAlterConfigsHandle.new
       handle[:pending] = true
-      handle[:response] = -1
+      handle[:response] = Rdkafka::Bindings::RD_KAFKA_PARTITION_UA
 
       queue_ptr = @native_kafka.with_inner do |inner|
         Rdkafka::Bindings.rd_kafka_queue_get_background(inner)
@@ -774,23 +835,39 @@ module Rdkafka
       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|
+      add_error = nil
+
+      pointer_array = parsed_resources.map do |resource_type, resource_name, configs|
         # 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_type,
+          FFI::MemoryPointer.from_string(resource_name)
         )
 
-        resource_details.fetch(:configs).each do |config|
-          Bindings.rd_kafka_ConfigResource_add_incremental_config(
+        configs.each do |name, op_type, value|
+          # rd_kafka_ConfigResource_add_incremental_config returns a non-NULL rd_kafka_error_t for
+          # an invalid op_type, an empty/nil name, or a nil value on a non-delete op. The result
+          # used to be ignored: the entry was silently dropped, the alter request still reported
+          # success, and the error object leaked. Capture the first error (always destroying the
+          # native error object) and raise it below, before the request is sent.
+          error_ptr = Bindings.rd_kafka_ConfigResource_add_incremental_config(
             resource_ptr,
-            config.fetch(:name),
-            config.fetch(:op_type),
-            config.fetch(:value)
+            name,
+            op_type,
+            value
           )
+
+          unless error_ptr.null?
+            code = Rdkafka::Bindings.rd_kafka_error_code(error_ptr)
+            Rdkafka::Bindings.rd_kafka_error_destroy(error_ptr)
+
+            unless code == Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
+              add_error ||= Rdkafka::RdkafkaError.new(
+                code,
+                "rd_kafka_ConfigResource_add_incremental_config"
+              )
+            end
+          end
         end
 
         resource_ptr
@@ -799,8 +876,11 @@ module Rdkafka
       configs_array_ptr = FFI::MemoryPointer.new(:pointer, pointer_array.size)
       configs_array_ptr.write_array_of_pointer(pointer_array)
 
-
       begin
+        # Raise only after the full array is built so the ensure below frees every ConfigResource
+        # we created, and before the request is sent so a rejected entry can't report success.
+        raise add_error if add_error
+
         @native_kafka.with_inner do |inner|
           Rdkafka::Bindings.rd_kafka_IncrementalAlterConfigs(
             inner,
@@ -815,10 +895,124 @@ module Rdkafka
 
         raise
       ensure
-        Rdkafka::Bindings.rd_kafka_ConfigResource_destroy_array(
-          configs_array_ptr,
-          pointer_array.size
-        ) if configs_array_ptr
+        Rdkafka::Bindings.rd_kafka_AdminOptions_destroy(admin_options_ptr)
+        Rdkafka::Bindings.rd_kafka_queue_destroy(queue_ptr)
+
+        if configs_array_ptr
+          Rdkafka::Bindings.rd_kafka_ConfigResource_destroy_array(
+            configs_array_ptr,
+            pointer_array.size
+          )
+        end
+      end
+
+      handle
+    end
+
+    # Queries partition offsets by specification (earliest, latest, max_timestamp, or by
+    # timestamp) without requiring a consumer group.
+    #
+    # @param topic_partition_offsets [Hash{String => Array<Hash>}] hash mapping topic names to
+    #   arrays of partition offset specifications. Each specification is a hash with:
+    #   - `:partition` [Integer] partition number
+    #   - `:offset` [Symbol, Integer] offset specification - `:earliest`, `:latest`,
+    #     `:max_timestamp`, or an integer timestamp in milliseconds
+    # @param isolation_level [Integer, nil] optional isolation level:
+    #   - `RD_KAFKA_ISOLATION_LEVEL_READ_UNCOMMITTED` (0) - default
+    #   - `RD_KAFKA_ISOLATION_LEVEL_READ_COMMITTED` (1)
+    #
+    # @return [ListOffsetsHandle] handle that can be used to wait for the result
+    #
+    # @raise [ClosedAdminError] when the admin is closed
+    # @raise [ConfigError] when the background queue is unavailable
+    #
+    # @example Query earliest and latest offsets
+    #   handle = admin.list_offsets(
+    #     { "my_topic" => [
+    #       { partition: 0, offset: :earliest },
+    #       { partition: 1, offset: :latest }
+    #     ] }
+    #   )
+    #   report = handle.wait(max_wait_timeout_ms: 15_000)
+    #   report.offsets
+    #   # => [{ topic: "my_topic", partition: 0, offset: 0, ... }, ...]
+    def list_offsets(topic_partition_offsets, isolation_level: nil)
+      closed_admin_check(__method__)
+
+      # Parse and validate every offset spec before allocating the native list, so a missing key or
+      # an unknown offset specification raises with nothing to clean up. Previously the
+      # ArgumentError (or KeyError) was raised after `rd_kafka_topic_partition_list_new`, leaking
+      # the native list.
+      parsed = topic_partition_offsets.flat_map do |topic, partitions|
+        partitions.map do |spec|
+          offset = spec.fetch(:offset)
+
+          native_offset = case offset
+          when :earliest then Rdkafka::Bindings::RD_KAFKA_OFFSET_SPEC_EARLIEST
+          when :latest then Rdkafka::Bindings::RD_KAFKA_OFFSET_SPEC_LATEST
+          when :max_timestamp then Rdkafka::Bindings::RD_KAFKA_OFFSET_SPEC_MAX_TIMESTAMP
+          when Integer then offset
+          else
+            raise ArgumentError, "Unknown offset specification: #{offset.inspect}"
+          end
+
+          [topic, spec.fetch(:partition), native_offset]
+        end
+      end
+
+      # Build native topic partition list
+      tpl = Rdkafka::Bindings.rd_kafka_topic_partition_list_new(parsed.size)
+
+      parsed.each do |topic, partition, native_offset|
+        Rdkafka::Bindings.rd_kafka_topic_partition_list_add(tpl, topic, partition)
+        Rdkafka::Bindings.rd_kafka_topic_partition_list_set_offset(tpl, topic, partition, native_offset)
+      end
+
+      # Get a pointer to the queue that our request will be enqueued on
+      queue_ptr = @native_kafka.with_inner do |inner|
+        Rdkafka::Bindings.rd_kafka_queue_get_background(inner)
+      end
+
+      if queue_ptr.null?
+        Rdkafka::Bindings.rd_kafka_topic_partition_list_destroy(tpl)
+        raise Rdkafka::Config::ConfigError.new("rd_kafka_queue_get_background was NULL")
+      end
+
+      # Create and register the handle we will return to the caller
+      handle = ListOffsetsHandle.new
+      handle[:pending] = true
+      handle[:response] = Rdkafka::Bindings::RD_KAFKA_PARTITION_UA
+
+      admin_options_ptr = @native_kafka.with_inner do |inner|
+        Rdkafka::Bindings.rd_kafka_AdminOptions_new(
+          inner,
+          Rdkafka::Bindings::RD_KAFKA_ADMIN_OP_LISTOFFSETS
+        )
+      end
+
+      if isolation_level
+        Rdkafka::Bindings.rd_kafka_AdminOptions_set_isolation_level(admin_options_ptr, isolation_level)
+      end
+
+      ListOffsetsHandle.register(handle)
+      Rdkafka::Bindings.rd_kafka_AdminOptions_set_opaque(admin_options_ptr, handle.to_ptr)
+
+      begin
+        @native_kafka.with_inner do |inner|
+          Rdkafka::Bindings.rd_kafka_ListOffsets(
+            inner,
+            tpl,
+            admin_options_ptr,
+            queue_ptr
+          )
+        end
+      rescue Exception
+        ListOffsetsHandle.remove(handle.to_ptr.address)
+        raise
+      ensure
+        Rdkafka::Bindings.rd_kafka_AdminOptions_destroy(admin_options_ptr)
+        Rdkafka::Bindings.rd_kafka_queue_destroy(queue_ptr)
+        Rdkafka::Bindings.rd_kafka_topic_partition_list_destroy(tpl)
       end
 
       handle
@@ -826,8 +1020,12 @@ module Rdkafka
 
     private
 
+    # Checks if the admin is closed and raises an error if so
+    # @param method [Symbol] name of the calling method for error context
+    # @raise [ClosedAdminError] when the admin is closed
     def closed_admin_check(method)
       raise Rdkafka::ClosedAdminError.new(method) if closed?
     end
+    alias_method :closed_check, :closed_admin_check
   end
 end