rdkafka 0.22.2 → 0.25.0

data/lib/rdkafka/admin.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Rdkafka
+  # Admin client for Kafka administrative operations
   class Admin
     include Helpers::OAuth
 
@@ -8,7 +9,7 @@ module Rdkafka
       # 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)
@@ -49,6 +50,7 @@ module Rdkafka
     end
 
     # @private
+    # @param native_kafka [NativeKafka] wrapper around the native Kafka handle
     def initialize(native_kafka)
       @native_kafka = native_kafka
 
@@ -69,6 +71,8 @@ module Rdkafka
       end
     end
 
+    # @return [Proc] finalizer proc for closing the admin
+    # @private
     def finalizer
       ->(_) { close }
     end
@@ -78,7 +82,7 @@ module Rdkafka
     # @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)
+    def metadata(topic_name = nil, timeout_ms = Defaults::METADATA_TIMEOUT_MS)
       closed_admin_check(__method__)
 
       @native_kafka.with_inner do |inner|
@@ -100,9 +104,12 @@ 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
@@ -149,7 +156,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 +185,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__)
 
@@ -202,7 +214,7 @@ module Rdkafka
       # 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 +245,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 +272,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 +303,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 +338,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 +365,34 @@ 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_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 +432,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 +465,33 @@ 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_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__)
@@ -534,7 +533,7 @@ module Rdkafka
       # 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 +566,33 @@ 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_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__)
@@ -634,7 +627,7 @@ module Rdkafka
       # 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 +657,6 @@ module Rdkafka
       describe_acl_handle
     end
 
-
     # Describe configs
     #
     # @param resources [Array<Hash>]  Array where elements are hashes with two keys:
@@ -681,7 +673,7 @@ module Rdkafka
 
       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)
@@ -754,7 +746,7 @@ module Rdkafka
 
       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)
@@ -826,6 +818,9 @@ 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

data/lib/rdkafka/bindings.rb

@@ -2,9 +2,20 @@
 
 module Rdkafka
   # @private
+  #
+  # @note
+  #   There are two types of responses related to errors:
+  #     - rd_kafka_error_t - a C object that we need to remap into an error or null when no error
+  #     - rd_kafka_resp_err_t - response error code (numeric) that we can use directly
+  #
+  #   It is critical to ensure, that we handle them correctly. The result type should be:
+  #     - rd_kafka_error_t - :pointer
+  #     - rd_kafka_resp_err_t - :int
   module Bindings
     extend FFI::Library
 
+    # Returns the library extension based on the host OS
+    # @return [String] 'dylib' on macOS, 'so' on other systems
     def self.lib_extension
       if RbConfig::CONFIG['host_os'] =~ /darwin/
         'dylib'
@@ -13,7 +24,39 @@ module Rdkafka
       end
     end
 
-    ffi_lib File.join(__dir__, "../../ext/librdkafka.#{lib_extension}")
+    # Wrap ffi_lib to provide better error messages for glibc compatibility issues
+    begin
+      ffi_lib File.join(__dir__, "../../ext/librdkafka.#{lib_extension}")
+    rescue LoadError => e
+      error_message = e.message
+
+      # Check if this is a glibc version mismatch error
+      if error_message =~ /GLIBC_[\d.]+['"` ]?\s*not found/i
+        glibc_version = error_message[/GLIBC_([\d.]+)/, 1] || 'unknown'
+
+        raise Rdkafka::LibraryLoadError, <<~ERROR_MSG.strip
+          Failed to load librdkafka due to glibc compatibility issue.
+
+          The precompiled librdkafka binary requires glibc version #{glibc_version} or higher,
+          but your system has an older version installed.
+
+          To resolve this issue, you have two options:
+
+          1. Upgrade your system to a supported platform (recommended)
+
+          2. Force compilation from source by reinstalling without the precompiled binary:
+             gem install rdkafka --platform=ruby
+
+             Or if using Bundler, add to your Gemfile:
+             gem 'rdkafka', force_ruby_platform: true
+
+          Original error: #{error_message}
+        ERROR_MSG
+      else
+        # Re-raise the original error if it's not a glibc issue
+        raise
+      end
+    end
 
     RD_KAFKA_RESP_ERR__ASSIGN_PARTITIONS = -175
     RD_KAFKA_RESP_ERR__REVOKE_PARTITIONS = -174
@@ -26,8 +69,12 @@ module Rdkafka
     RD_KAFKA_OFFSET_STORED    = -1000
     RD_KAFKA_OFFSET_INVALID   = -1001
 
+    RD_KAFKA_PARTITION_UA     = -1
+    RD_KAFKA_PARTITION_UA_STR = RD_KAFKA_PARTITION_UA.to_s.freeze
+
     EMPTY_HASH = {}.freeze
 
+    # FFI struct for size_t pointer wrapper
     class SizePtr < FFI::Struct
       layout :value, :size_t
     end
@@ -51,8 +98,7 @@ module Rdkafka
     attach_function :rd_kafka_metadata, [:pointer, :int, :pointer, :pointer, :int], :int, blocking: true
     attach_function :rd_kafka_metadata_destroy, [:pointer], :void, blocking: true
 
-    # Message struct
-
+    # FFI struct representing a Kafka message (rd_kafka_message_t)
     class Message < FFI::Struct
       layout :err, :int,
              :rkt, :pointer,
@@ -71,8 +117,7 @@ module Rdkafka
     attach_function :rd_kafka_topic_destroy, [:pointer], :pointer
     attach_function :rd_kafka_topic_name, [:pointer], :string
 
-    # TopicPartition ad TopicPartitionList structs
-
+    # FFI struct representing a topic partition (rd_kafka_topic_partition_t)
     class TopicPartition < FFI::Struct
       layout :topic, :string,
              :partition, :int32,
@@ -84,6 +129,7 @@ module Rdkafka
              :_private, :pointer
     end
 
+    # FFI struct representing a topic partition list (rd_kafka_topic_partition_list_t)
     class TopicPartitionList < FFI::Struct
       layout :cnt, :int,
              :size, :int,
@@ -91,17 +137,15 @@ module Rdkafka
     end
 
     attach_function :rd_kafka_topic_partition_list_new, [:int32], :pointer
-    attach_function :rd_kafka_topic_partition_list_add, [:pointer, :string, :int32], :void
+    attach_function :rd_kafka_topic_partition_list_add, [:pointer, :string, :int32], :pointer
     attach_function :rd_kafka_topic_partition_list_set_offset, [:pointer, :string, :int32, :int64], :void
     attach_function :rd_kafka_topic_partition_list_destroy, [:pointer], :void
     attach_function :rd_kafka_topic_partition_list_copy, [:pointer], :pointer
 
-    # Configs management
-    #
-    # Structs for management of configurations
-    # Each configuration is attached to a resource and one resource can have many configuration
-    # details. Each resource will also have separate errors results if obtaining configuration
-    # was not possible for any reason
+    # FFI struct representing a config resource (rd_kafka_ConfigResource_t)
+    # Structs for management of configurations. Each configuration is attached to a resource
+    # and one resource can have many configuration details. Each resource will also have
+    # separate errors results if obtaining configuration was not possible for any reason
     class ConfigResource < FFI::Struct
       layout :type, :int,
              :name, :string
@@ -138,7 +182,7 @@ module Rdkafka
     RD_KAFKA_ALTER_CONFIG_OP_TYPE_APPEND   = 2
     RD_KAFKA_ALTER_CONFIG_OP_TYPE_SUBTRACT = 3
 
-    # Errors
+    # FFI struct for error description (rd_kafka_err_desc)
     class NativeErrorDesc < FFI::Struct
       layout :code, :int,
              :name, :pointer,
@@ -147,6 +191,10 @@ module Rdkafka
 
     attach_function :rd_kafka_err2name, [:int], :string
     attach_function :rd_kafka_err2str, [:int], :string
+    attach_function :rd_kafka_error_is_fatal, [:pointer], :int
+    attach_function :rd_kafka_error_is_retriable, [:pointer], :int
+    attach_function :rd_kafka_error_txn_requires_abort, [:pointer], :int
+    attach_function :rd_kafka_error_destroy, [:pointer], :void
     attach_function :rd_kafka_get_err_descs, [:pointer, :pointer], :void
 
     # Configuration
@@ -221,7 +269,7 @@ module Rdkafka
         # Since this cache is shared, having few consumers and/or producers in one process will
         # automatically improve the querying times even with low refresh times.
         (stats['topics'] || EMPTY_HASH).each do |topic_name, details|
-          partitions_count = details['partitions'].keys.reject { |k| k == '-1' }.size
+          partitions_count = details['partitions'].keys.reject { |k| k == RD_KAFKA_PARTITION_UA_STR }.size
 
           next unless partitions_count.positive?
 
@@ -232,7 +280,7 @@ module Rdkafka
       end
 
       # Return 0 so librdkafka frees the json string
-      0
+      RD_KAFKA_RESP_ERR_NO_ERROR
     end
 
     ErrorCallback = FFI::Function.new(
@@ -355,7 +403,6 @@ module Rdkafka
     attach_function :rd_kafka_query_watermark_offsets, [:pointer, :string, :int, :pointer, :pointer, :int], :int
 
     # Producer
-
     RD_KAFKA_VTYPE_END = 0
     RD_KAFKA_VTYPE_TOPIC = 1
     RD_KAFKA_VTYPE_RKT = 2
@@ -377,16 +424,25 @@ module Rdkafka
     callback :delivery_cb, [:pointer, :pointer, :pointer], :void
     attach_function :rd_kafka_conf_set_dr_msg_cb, [:pointer, :delivery_cb], :void
 
-    # Partitioner
+    # Hash mapping partitioner names to their FFI function symbols
+    # @return [Hash{String => Symbol}]
     PARTITIONERS = %w(random consistent consistent_random murmur2 murmur2_random fnv1a fnv1a_random).each_with_object({}) do |name, hsh|
       method_name = "rd_kafka_msg_partitioner_#{name}".to_sym
       attach_function method_name, [:pointer, :pointer, :size_t, :int32, :pointer, :pointer], :int32
       hsh[name] = method_name
     end
 
+    # Calculates the partition for a message based on the partitioner
+    #
+    # @param topic_ptr [FFI::Pointer] pointer to the topic handle
+    # @param str [String] the partition key string
+    # @param partition_count [Integer, nil] number of partitions
+    # @param partitioner [String] name of the partitioner to use
+    # @return [Integer] partition number or RD_KAFKA_PARTITION_UA if unassigned
+    # @raise [Rdkafka::Config::ConfigError] when an unknown partitioner is specified
     def self.partitioner(topic_ptr, str, partition_count, partitioner = "consistent_random")
       # Return RD_KAFKA_PARTITION_UA(unassigned partition) when partition count is nil/zero.
-      return -1 unless partition_count&.nonzero?
+      return RD_KAFKA_PARTITION_UA unless partition_count&.nonzero?
 
       str_ptr = str.empty? ? FFI::MemoryPointer::NULL : FFI::MemoryPointer.from_string(str)
       method_name = PARTITIONERS.fetch(partitioner) do
@@ -397,7 +453,6 @@ module Rdkafka
     end
 
     # Create Topics
-
     RD_KAFKA_ADMIN_OP_CREATETOPICS     = 1   # rd_kafka_admin_op_t
     RD_KAFKA_EVENT_CREATETOPICS_RESULT = 100 # rd_kafka_event_type_t
 
@@ -409,7 +464,6 @@ module Rdkafka
     attach_function :rd_kafka_CreateTopics_result_topics, [:pointer, :pointer], :pointer, blocking: true
 
     # Delete Topics
-
     RD_KAFKA_ADMIN_OP_DELETETOPICS     = 2   # rd_kafka_admin_op_t
     RD_KAFKA_EVENT_DELETETOPICS_RESULT = 101 # rd_kafka_event_type_t
 
@@ -430,7 +484,6 @@ module Rdkafka
     attach_function :rd_kafka_CreatePartitions_result_topics, [:pointer, :pointer], :pointer
 
     # Delete Group
-
     RD_KAFKA_ADMIN_OP_DELETEGROUPS = 7   # rd_kafka_admin_op_t
     RD_KAFKA_EVENT_DELETEGROUPS_RESULT = 106 # rd_kafka_event_type_t
 
@@ -464,7 +517,6 @@ module Rdkafka
     attach_function :rd_kafka_topic_result_name, [:pointer], :pointer
 
     # Create Acls
-
     RD_KAFKA_ADMIN_OP_CREATEACLS     = 9
     RD_KAFKA_EVENT_CREATEACLS_RESULT = 1024
 
@@ -473,7 +525,6 @@ module Rdkafka
     attach_function :rd_kafka_CreateAcls_result_acls, [:pointer, :pointer], :pointer
 
     # Delete Acls
-
     RD_KAFKA_ADMIN_OP_DELETEACLS     = 11
     RD_KAFKA_EVENT_DELETEACLS_RESULT = 4096
 
@@ -484,7 +535,6 @@ module Rdkafka
     attach_function :rd_kafka_DeleteAcls_result_response_matching_acls, [:pointer, :pointer], :pointer
 
     # Describe Acls
-
     RD_KAFKA_ADMIN_OP_DESCRIBEACLS     = 10
     RD_KAFKA_EVENT_DESCRIBEACLS_RESULT = 2048
 
@@ -506,7 +556,6 @@ module Rdkafka
     attach_function :rd_kafka_AclBinding_destroy, [:pointer], :void
 
     # rd_kafka_ResourceType_t - https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L7307
-
     RD_KAFKA_RESOURCE_ANY   = 1
     RD_KAFKA_RESOURCE_TOPIC = 2
     RD_KAFKA_RESOURCE_GROUP = 3
@@ -514,14 +563,12 @@ module Rdkafka
     RD_KAFKA_RESOURCE_TRANSACTIONAL_ID = 5
 
     # rd_kafka_ResourcePatternType_t - https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L7320
-
     RD_KAFKA_RESOURCE_PATTERN_ANY      = 1
     RD_KAFKA_RESOURCE_PATTERN_MATCH    = 2
     RD_KAFKA_RESOURCE_PATTERN_LITERAL  = 3
     RD_KAFKA_RESOURCE_PATTERN_PREFIXED = 4
 
     # rd_kafka_AclOperation_t - https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L8403
-
     RD_KAFKA_ACL_OPERATION_ANY              = 1
     RD_KAFKA_ACL_OPERATION_ALL              = 2
     RD_KAFKA_ACL_OPERATION_READ             = 3
@@ -536,7 +583,6 @@ module Rdkafka
     RD_KAFKA_ACL_OPERATION_IDEMPOTENT_WRITE = 12
 
     # rd_kafka_AclPermissionType_t - https://github.com/confluentinc/librdkafka/blob/292d2a66b9921b783f08147807992e603c7af059/src/rdkafka.h#L8435
-
     RD_KAFKA_ACL_PERMISSION_TYPE_ANY     = 1
     RD_KAFKA_ACL_PERMISSION_TYPE_DENY    = 2
     RD_KAFKA_ACL_PERMISSION_TYPE_ALLOW   = 3
@@ -550,8 +596,8 @@ module Rdkafka
     attach_function :rd_kafka_AclBinding_error, [:pointer], :pointer
 
 
-    # Extracting data from group results
-    class NativeError < FFI::Struct # rd_kafka_error_t
+    # FFI struct for native error (rd_kafka_error_t)
+    class NativeError < FFI::Struct
       layout :code, :int32,
              :errstr, :pointer,
              :fatal, :u_int8_t,