karafka 2.3.3 → 2.4.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 707ae730a3d16f7daa69b4d7fc91f27420e408f0c441aee1b3072a45a03ab18b
-  data.tar.gz: a06597a2361af03cbca21f98a4efc339c0cf582bf21a5794a8b9db1179c8b6c9
+  metadata.gz: 39388f4dff605df6b699b8f8db42062fe8bdece1dcdc86548e91da28956f4eae
+  data.tar.gz: b58710b9e0d1264db8bddc7ff4540fcf697c2c4ca68c43de4fba6f79cbca4b8e
 SHA512:
-  metadata.gz: dbe0771e0764a74a7e86870c208b5c845fbfe9f022e9692db7dc1efe2e95ba65cb79f2a771c249e161cd2e540c2e18e4c4af72419849481a97e01ec70112a0bb
-  data.tar.gz: 9c6e32a5cc8fa7a82f8f0b9d50510863767eb11bfb57a4c356eb836d497e31981b0e0a19c814dfc438f3520320dd2eb973bf9c362cccec994bb4fa6dd0db1e27
+  metadata.gz: 4e43f34d90881642a1a9ad3ffd74d8ff909c68f8eb54cafd8de2e2fb878c2cf3bfdd9506931d379441138afa5a6a29344a69aa744439182e5aef74e71d99dcf8
+  data.tar.gz: 984315866f3b801601970f4da01a7e31ca8a3dde35601fa8906335b1d1b9a002b2ba7b96c3e765a8c9c3081ff441d5937f9a9506b30ff86c1a8a0683ed8516d3

data/.github/workflows/ci.yml

@@ -80,8 +80,6 @@ jobs:
           - '3.1'
           - '3.1.0'
           - '3.0'
-          - '3.0.0'
-          - '2.7'
         include:
           - ruby: '3.3'
             coverage: 'true'
@@ -90,9 +88,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
@@ -122,7 +120,6 @@ jobs:
           - '3.2'
           - '3.1'
           - '3.0'
-          - '2.7'
     steps:
       - uses: actions/checkout@v4
       - name: Install package dependencies
@@ -131,9 +128,9 @@ jobs:
       - name: Remove libzstd-dev to check no supported compressions
         run: sudo apt-get -y remove libzstd-dev
 
-      - 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
@@ -147,26 +144,15 @@ jobs:
 
       - name: Install latest Bundler
         run: |
-          if [[ "$(ruby -v | awk '{print $2}')" == 2.7.8* ]]; then
-            gem install bundler -v 2.4.22 --no-document
-            bundle config set version 2.4.22
-            gem update --system 3.4.22 --no-document
-          else
-            gem install bundler --no-document
-            gem update --system --no-document
-          fi
+          gem install bundler --no-document
+          gem update --system --no-document
 
           bundle config set without 'tools benchmarks docs'
 
       - name: Bundle install
         run: |
           bundle config set without development
-
-          if [[ "$(ruby -v | awk '{print $2}')" == 2.7.8* ]]; then
-            BUNDLER_VERSION=2.4.22 bundle install --jobs 4 --retry 3
-          else
-            bundle install --jobs 4 --retry 3
-          fi
+          bundle install --jobs 4 --retry 3
 
       - name: Wait for Kafka
         run: |
@@ -187,15 +173,14 @@ jobs:
           - '3.2'
           - '3.1'
           - '3.0'
-          - '2.7'
     steps:
       - uses: actions/checkout@v4
       - 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
@@ -205,26 +190,15 @@ jobs:
 
       - name: Install latest Bundler
         run: |
-          if [[ "$(ruby -v | awk '{print $2}')" == 2.7.8* ]]; then
-            gem install bundler -v 2.4.22 --no-document
-            bundle config set version 2.4.22
-            gem update --system 3.4.22 --no-document
-          else
-            gem install bundler --no-document
-            gem update --system --no-document
-          fi
+          gem install bundler --no-document
+          gem update --system --no-document
 
           bundle config set without 'tools benchmarks docs'
 
       - name: Bundle install
         run: |
           bundle config set without development
-
-          if [[ "$(ruby -v | awk '{print $2}')" == 2.7.8* ]]; then
-            BUNDLER_VERSION=2.4.22 bundle install --jobs 4 --retry 3
-          else
-            bundle install --jobs 4 --retry 3
-          fi
+          bundle install --jobs 4 --retry 3
 
       - name: Wait for Kafka
         run: |

data/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Karafka framework changelog
 
+## 2.4.0 (Unreleased)
+
+This release contains **BREAKING** changes. Make sure to read and apply upgrade notes.
+
+- **[Breaking]** Drop Ruby `2.7` support.
+- **[Breaking]** Drop the concept of consumer group mapping.
+- **[Breaking]** `karafka topics migrate` will now perform declarative topics configuration alignment.
+- **[Breaking]** Replace `deserializer` config with `#deserializers` in routing to support key and lazy header deserializers.
+- **[Breaking]** Rename `Karafka::Serializers::JSON::Deserializer` to `Karafka::Deserializers::Payload` to reflect its role.
+- **[Feature]** Support custom OAuth providers (with a lot of help from bruce-szalwinski-he and hotelengine.com).
+- **[Feature]** Provide `karafka topics alter` for declarative topics alignment.
+- **[Feature]** Introduce ability to use direct assignments (Pro).
+- **[Feature]** Provide consumer piping API (Pro).
+- **[Feature]** Introduce `karafka topics plan` to describe changes that will be applied when migrating.
+- **[Feature]** Introduce ability to use custom message key deserializers.
+- **[Feature]** Introduce ability to use custom message headers deserializers.
+- **[Feature]** Provide `Karafka::Admin::Configs` API for cluster and topics configuration management.
+- [Enhancement] Assign names to internal threads for better debuggability when on `TTIN`.
+- [Enhancement] Provide `log_polling` setting to the `Karafka::Instrumentation::LoggerListener` to silence polling in any non-debug mode.
+- [Enhancement] Provide `metadata#message` to be able to retrieve message from metadata.
+- [Enhancement] Include number of attempts prior to DLQ message being dispatched including the dispatch one (Pro).
+- [Enhancement] Provide ability to decide how to dispatch from DLQ (sync / async).
+- [Enhancement] Provide ability to decide how to mark as consumed from DLQ (sync / async).
+- [Enhancement] Allow for usage of a custom Appsignal namespace when logging.
+- [Enhancement] Do not run periodic jobs when LRJ job is running despite polling (LRJ can still start when Periodic runs).
+- [Enhancement] Improve accuracy of periodic jobs and make sure they do not run too early after saturated work.
+- [Enhancement] Introduce ability to async lock other subscription groups polling.
+- [Enhancement] Improve shutdown when using long polling setup (high `max_wait_time`).
+- [Enhancement] Provide `Karafka::Admin#read_lags_with_offsets` for ability to query lags and offsets of a given CG.
+- [Enhancement] Allow direct assignments granular distribution in the Swarm (Pro).
+- [Enhancement] Add a buffer to the supervisor supervision on shutdown to prevent a potential race condition when signal pass lags.
+- [Enhancement] Provide ability to automatically generate and validate fingerprints of encrypted payload.
+- [Enhancement] Support `enable.partition.eof` fast yielding.
+- [Enhancement] Provide `#mark_as_consumed` and `#mark_as_consumed!` to the iterator.
+- [Enhancement] Introduce graceful `#stop` to the iterator instead of recommending of usage of `break`.
+- [Enhancement] Do not run jobs schedulers and other interval based operations on each job queue unlock.
+- [Enhancement] Publish listeners status lifecycle events.
+- [Enhancement] Use proxy wrapper for Admin metadata requests.
+- [Enhancement] Use limited scope topic info data when operating on direct topics instead of full cluster queries.
+- [Enhancement] No longer raise `Karafka::UnsupportedCaseError` for not recognized error types to support dynamic errors reporting.
+- [Change] Do not create new proxy object to Rdkafka with certain low-level operations and re-use existing.
+- [Change] Update `karafka.erb` template with a placeholder for waterdrop and karafka error instrumentation.
+- [Fix] Pro Swarm liveness listener can report incorrect failure when dynamic multiplexing scales down.
+- [Fix] K8s liveness listener can report incorrect failure when dynamic multiplexing scales down.
+- [Fix] Fix a case where connection conductor would not be released during manager state changes.
+- [Fix] Make sure, that all `Admin` operations go through stabilization proxy.
+- [Fix] Fix an issue where coordinator running jobs would not count periodic jobs and revocations.
+- [Fix] Fix a case where critically crashed supervisor would raise incorrect error.
+- [Fix] Re-raise critical supervisor errors before shutdown.
+- [Fix] Fix a case when right-open (infinite) swarm matching would not pass validations.
+- [Fix] Make `#enqueue_all` output compatible with `ActiveJob.perform_all_later` (oozzal)
+- [Fix] Seek consumer group on a topic level is updating only recent partition.
+
+### Upgrade Notes
+
+**PLEASE MAKE SURE TO READ AND APPLY THEM!**
+
+Available [here](https://karafka.io/docs/Upgrades-2.4/).
+
 ## 2.3.3 (2024-02-26)
 - [Enhancement] Routing based topics allocation for swarm (Pro)
 - [Enhancement] Publish the `-1` shutdown reason status for a non-responding node in swarm.

data/Gemfile

@@ -6,11 +6,14 @@ plugin 'diffend'
 
 gemspec
 
-# Karafka gem does not require activejob nor karafka-web  to work
+# Karafka gem does not require activejob nor karafka-web to work
 # They are added here because they are part of the integration suite
+# Since some of those are only needed for some specs, they should never be required automatically
 group :integrations do
-  gem 'activejob'
-  gem 'karafka-web', '>= 0.8.0'
+  gem 'activejob', require: false
+  gem 'karafka-testing', '>= 2.4.0.rc1', require: false
+  gem 'karafka-web', '>= 0.9.0.rc1', require: false
+  gem 'rspec', require: false
 end
 
 group :test do

data/Gemfile.lock

@@ -1,18 +1,18 @@
 PATH
   remote: .
   specs:
-    karafka (2.3.3)
-      karafka-core (>= 2.3.0, < 2.4.0)
-      waterdrop (>= 2.6.12, < 3.0.0)
+    karafka (2.4.0.beta2)
+      karafka-core (>= 2.4.0.rc1, < 2.5.0)
+      waterdrop (>= 2.7.0.rc1, < 3.0.0)
       zeitwerk (~> 2.3)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activejob (7.1.3)
-      activesupport (= 7.1.3)
+    activejob (7.1.3.2)
+      activesupport (= 7.1.3.2)
       globalid (>= 0.3.6)
-    activesupport (7.1.3)
+    activesupport (7.1.3.2)
       base64
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.0.2)
@@ -23,40 +23,42 @@ GEM
       mutex_m
       tzinfo (~> 2.0)
     base64 (0.2.0)
-    bigdecimal (3.1.6)
+    bigdecimal (3.1.7)
     byebug (11.1.3)
     concurrent-ruby (1.2.3)
     connection_pool (2.4.1)
     diff-lcs (1.5.1)
     docile (1.4.0)
-    drb (2.2.0)
-      ruby2_keywords
+    drb (2.2.1)
     erubi (1.12.0)
-    factory_bot (6.4.5)
+    factory_bot (6.4.6)
       activesupport (>= 5.0.0)
     ffi (1.16.3)
     globalid (1.2.1)
       activesupport (>= 6.1)
-    i18n (1.14.1)
+    i18n (1.14.4)
       concurrent-ruby (~> 1.0)
-    karafka-core (2.3.0)
-      karafka-rdkafka (>= 0.14.8, < 0.15.0)
-    karafka-rdkafka (0.14.10)
+    karafka-core (2.4.0.rc1)
+      karafka-rdkafka (>= 0.15.0.rc1, < 0.16.0)
+    karafka-rdkafka (0.15.0.rc1)
       ffi (~> 1.15)
       mini_portile2 (~> 2.6)
       rake (> 12)
-    karafka-web (0.8.2)
+    karafka-testing (2.4.0.rc1)
+      karafka (>= 2.4.0.beta1, < 2.5.0)
+      waterdrop (>= 2.7.0.rc1)
+    karafka-web (0.9.0.rc1)
       erubi (~> 1.4)
-      karafka (>= 2.3.0, < 2.4.0)
-      karafka-core (>= 2.3.0, < 2.4.0)
+      karafka (>= 2.4.0.beta1, < 2.5.0)
+      karafka-core (>= 2.4.0.rc1, < 2.5.0)
       roda (~> 3.68, >= 3.69)
       tilt (~> 2.0)
     mini_portile2 (2.8.5)
-    minitest (5.21.2)
+    minitest (5.22.3)
     mutex_m (0.2.0)
-    rack (3.0.9)
-    rake (13.1.0)
-    roda (3.77.0)
+    rack (3.0.10)
+    rake (13.2.1)
+    roda (3.78.0)
       rack
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
@@ -70,8 +72,7 @@ GEM
     rspec-mocks (3.13.0)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.0)
-    ruby2_keywords (0.0.5)
+    rspec-support (3.13.1)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
@@ -81,8 +82,8 @@ GEM
     tilt (2.3.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    waterdrop (2.6.14)
-      karafka-core (>= 2.2.3, < 3.0.0)
+    waterdrop (2.7.0.rc1)
+      karafka-core (>= 2.4.0.rc1, < 3.0.0)
       zeitwerk (~> 2.3)
     zeitwerk (2.6.13)
 
@@ -95,9 +96,10 @@ DEPENDENCIES
   byebug
   factory_bot
   karafka!
-  karafka-web (>= 0.8.0)
+  karafka-testing (>= 2.4.0.rc1)
+  karafka-web (>= 0.9.0.rc1)
   rspec
   simplecov
 
 BUNDLED WITH
-   2.5.4
+   2.5.7

data/bin/integrations

@@ -28,7 +28,7 @@ ROOT_PATH = Pathname.new(File.expand_path(File.join(File.dirname(__FILE__), '../
 CONCURRENCY = ENV.key?('CI') ? 5 : Etc.nprocessors * 3
 
 # How may bytes do we want to keep from the stdout in the buffer for when we need to print it
-MAX_BUFFER_OUTPUT = 102_400
+MAX_BUFFER_OUTPUT = 307_200
 
 # Abstraction around a single test scenario execution process
 class Scenario

data/config/locales/errors.yml

@@ -7,12 +7,13 @@ en:
 
       missing: needs to be present
       client_id_format: 'needs to be a string with a Kafka accepted format'
+      group_id_format: 'needs to be a string with a Kafka accepted format'
       concurrency_format: needs to be an integer bigger than 0
-      consumer_mapper_format: needs to be present
       consumer_persistence_format: needs to be either true or false
       pause_timeout_format: needs to be an integer bigger than 0
       pause_max_timeout_format: needs to be an integer bigger than 0
       pause_with_exponential_backoff_format: needs to be either true or false
+      strict_topics_namespacing_format: needs to be either true or false
       shutdown_timeout_format: needs to be an integer bigger than 0
       max_wait_time_format: needs to be an integer bigger than 0
       max_wait_time_max_wait_time_vs_swarm_node_report_timeout: >
@@ -23,6 +24,8 @@ en:
       max_timeout_vs_pause_max_timeout: pause_timeout must be less or equal to pause_max_timeout
       shutdown_timeout_vs_max_wait_time: shutdown_timeout must be more than max_wait_time
 
+      oauth.token_provider_listener_format: 'must be false or respond to #on_oauthbearer_token_refresh'
+
       internal.processing.jobs_builder_format: cannot be nil
       internal.processing.jobs_queue_class_format: cannot be nil
       internal.processing.scheduler_class_format: cannot be nil
@@ -55,6 +58,11 @@ en:
       internal.connection.proxy.committed.timeout_format: needs to be an integer bigger than 0
       internal.connection.proxy.committed.max_attempts_format: needs to be an integer bigger than 0
       internal.connection.proxy.committed.wait_time_format: needs to be an integer bigger than 0
+      internal.connection.proxy.commit.max_attempts_format: needs to be an integer bigger than 0
+      internal.connection.proxy.commit.wait_time_format: needs to be an integer bigger than 0
+      internal.connection.proxy.metadata.timeout_format: needs to be an integer bigger than 0
+      internal.connection.proxy.metadata.max_attempts_format: needs to be an integer bigger than 0
+      internal.connection.proxy.metadata.wait_time_format: needs to be an integer bigger than 0
 
       internal.swarm.manager_format: cannot be nil
       internal.swarm.orphaned_exit_code_format: needs to be an integer bigger or equal to 0
@@ -87,7 +95,7 @@ en:
       max_messages_format: 'needs to be an integer bigger than 0'
       max_wait_time_format: 'needs to be an integer bigger than 0'
       name_format: 'needs to be a string with a Kafka accepted format'
-      deserializer_format: needs to be present
+      deserializers_format: needs to be present
       consumer_format: needs to be present
       id_format: 'needs to be a string with a Kafka accepted format'
       initial_offset_format: needs to be either earliest or latest
@@ -96,20 +104,31 @@ en:
       manual_offset_management_must_be_enabled: cannot be disabled for ActiveJob topics
       inline_insights.active_format: needs to be either true or false
       consumer_active_job_missing: ActiveJob needs to be available
+
       dead_letter_queue.max_retries_format: needs to be equal or bigger than 0
       dead_letter_queue.topic_format: 'needs to be a string with a Kafka accepted format'
       dead_letter_queue.active_format: needs to be either true or false
       dead_letter_queue.independent_format: needs to be either true or false
       dead_letter_queue.transactional_format: needs to be either true or false
+      dead_letter_queue.dispatch_method_format: 'needs to be either #produce_sync or #produce_async'
+      dead_letter_queue.marking_method_format: 'needs to be either #mark_as_consumed or #mark_as_consumed!'
+
       active_format: needs to be either true or false
+
       declaratives.partitions_format: needs to be more or equal to 1
       declaratives.active_format: needs to be true
       declaratives.replication_factor_format: needs to be more or equal to 1
       declaratives.details_format: needs to be a hash with only symbol keys
+
       inconsistent_namespacing: |
         needs to be consistent namespacing style
         disable this validation by setting config.strict_topics_namespacing to false
 
+      deserializers.active_format: 'needs to be true'
+      deserializers.payload_format: 'needs to respond to #call'
+      deserializers.key_format: 'needs to respond to #call'
+      deserializers.headers_format: 'needs to respond to #call'
+
     consumer_group:
       missing: needs to be present
       topics_names_not_unique: all topic names within a single consumer group must be unique

data/config/locales/pro_errors.yml

@@ -59,13 +59,23 @@ en:
       subscription_group_details.multiplexing_boot_not_dynamic: 'needs to be equal to max when not in dynamic mode'
 
       swarm.active_format: needs to be true
-      swarm.nodes_format: needs to be a range or an array of nodes ids
+      swarm.nodes_format: needs to be a range, array of nodes ids or a hash with direct assignments
       swarm_nodes_with_non_existent_nodes: includes unreachable nodes ids
 
+      direct_assignments.active_missing: needs to be present
+      direct_assignments.active_format: 'needs to be boolean'
+      direct_assignments.partitions_missing: 'needs to be present'
+      direct_assignments.partitions_format: 'needs to be true, list of partitions or a range of partitions (finite)'
+      direct_assignments_active_but_empty: 'cannot be empty and active at the same time'
+      direct_assignments_swarm_not_complete: 'cannot have partitions that are assigned but not allocated'
+      direct_assignments_swarm_overbooked: 'cannot allocate partitions in swarm that were not assigned'
+      direct_assignments_patterns_active: 'patterns cannot be used with direct assignments'
+
     consumer_group:
       patterns_format: must be an array with hashes
       patterns_missing: needs to be present
       patterns_regexps_not_unique: 'must be unique within consumer group'
+      direct_assignments_homogenous: 'single consumer group cannot mix regular and direct assignments'
 
     pattern:
       regexp_format: must be a regular expression
@@ -82,6 +92,11 @@ en:
       encryption.version_format: must be a non-empty string
       encryption.public_key_format: 'is not a valid public RSA key'
       encryption.private_keys_invalid: 'contains an invalid private RSA key string'
+      encryption.fingerprinter_missing: 'needs to be false or respond to #hexdigest method'
+      encryption.fingerprinter_format: 'needs to be false or respond to #hexdigest method'
 
       patterns.ttl_format: needs to be an integer bigger than 0
       patterns.ttl_missing: needs to be present
+
+    routing:
+      swarm_nodes_not_used: 'At least one of the nodes has no assignments'

data/karafka.gemspec

@@ -21,10 +21,12 @@ Gem::Specification.new do |spec|
     without having to focus on things that are not your business domain.
   DESC
 
-  spec.add_dependency 'karafka-core', '>= 2.3.0', '< 2.4.0'
-  spec.add_dependency 'waterdrop', '>= 2.6.12', '< 3.0.0'
+  spec.add_dependency 'karafka-core', '>= 2.4.0.rc1', '< 2.5.0'
+  spec.add_dependency 'waterdrop', '>= 2.7.0.rc1', '< 3.0.0'
   spec.add_dependency 'zeitwerk', '~> 2.3'
 
+  spec.required_ruby_version = '>= 3.0.0'
+
   if $PROGRAM_NAME.end_with?('gem')
     spec.signing_key = File.expand_path('~/.ssh/gem-private_key.pem')
   end

data/lib/active_job/queue_adapters/karafka_adapter.rb

@@ -16,8 +16,10 @@ module ActiveJob
 
       # Enqueues multiple jobs in one go
       # @param jobs [Array<Object>] jobs that we want to enqueue
+      # @return [Integer] number of jobs enqueued (required by Rails)
       def enqueue_all(jobs)
         ::Karafka::App.config.internal.active_job.dispatcher.dispatch_many(jobs)
+        jobs.size
       end
 
       # Raises info, that Karafka backend does not support scheduling jobs

data/lib/karafka/admin/configs/config.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Admin
+    module Configs
+      # Represents a single config entry that is related to a resource
+      class Config
+        attr_reader :name, :value, :synonyms
+
+        class << self
+          # Creates a single config entry from the Rdkafka config result entry
+          #
+          # @param rd_kafka_config [Rdkafka::Admin::ConfigBindingResult]
+          # @return [Config]
+          def from_rd_kafka(rd_kafka_config)
+            new(
+              name: rd_kafka_config.name,
+              value: rd_kafka_config.value,
+              read_only: rd_kafka_config.read_only,
+              default: rd_kafka_config.default,
+              sensitive: rd_kafka_config.sensitive,
+              synonym: rd_kafka_config.synonym,
+              synonyms: rd_kafka_config.synonyms.map do |rd_kafka_synonym|
+                from_rd_kafka(rd_kafka_synonym)
+              end
+            )
+          end
+        end
+
+        # Creates new config instance either for reading or as part of altering operation
+        #
+        # @param name [String] config name
+        # @param value [String] config value
+        # @param default [Integer] 1 if default
+        # @param read_only [Integer] 1 if read only
+        # @param sensitive [Integer] 1 if sensitive
+        # @param synonym [Integer] 1 if synonym
+        # @param synonyms [Array] given config synonyms (if any)
+        #
+        # @note For alter operations only `name` and `value` are needed
+        def initialize(
+          name:,
+          value:,
+          default: -1,
+          read_only: -1,
+          sensitive: -1,
+          synonym: -1,
+          synonyms: []
+        )
+          @name = name
+          @value = value
+          @synonyms = []
+          @default = default
+          @read_only = read_only
+          @sensitive = sensitive
+          @synonym = synonym
+          @synonyms = synonyms
+        end
+
+        # @return [Boolean] Is the config property is set to its default value on the broker
+        def default? = @default.positive?
+
+        # @return [Boolean] Is the config property is read-only on the broker
+        def read_only? = @read_only.positive?
+
+        # @return [Boolean] if the config property contains sensitive information (such as
+        #   security configuration
+        def sensitive? = @sensitive.positive?
+
+        # @return [Boolean] is this entry is a synonym
+        def synonym? = @synonym.positive?
+
+        # @return [Hash] hash that we can use to operate with rdkafka
+        def to_native_hash = {
+          name: name,
+          value: value
+        }.freeze
+      end
+    end
+  end
+end

data/lib/karafka/admin/configs/resource.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Admin
+    module Configs
+      # Represents a single resource in the context of configuration management
+      class Resource
+        # Types of resources that have workable configs.
+        RESOURCE_TYPES_MAP = {
+          # use when you want to assign acl to a given topic
+          topic: Rdkafka::Bindings::RD_KAFKA_RESOURCE_TOPIC,
+          # use when you want to assign acl to a given broker
+          broker: Rdkafka::Bindings::RD_KAFKA_RESOURCE_BROKER
+        }.freeze
+
+        # Map for operations we may perform on the resource configs
+        OPERATIONS_TYPES_MAP = {
+          set: Rdkafka::Bindings::RD_KAFKA_ALTER_CONFIG_OP_TYPE_SET,
+          delete: Rdkafka::Bindings::RD_KAFKA_ALTER_CONFIG_OP_TYPE_DELETE,
+          append: Rdkafka::Bindings::RD_KAFKA_ALTER_CONFIG_OP_TYPE_APPEND,
+          subtract: Rdkafka::Bindings::RD_KAFKA_ALTER_CONFIG_OP_TYPE_SUBTRACT
+        }.freeze
+
+        private_constant :RESOURCE_TYPES_MAP, :OPERATIONS_TYPES_MAP
+
+        attr_reader :type, :name, :configs
+
+        # @param type [Symbol, Integer] type of resource as a symbol for mapping or integer
+        # @param name [String] name of the resource. It's the broker id or topic name
+        # @return [Resource]
+        def initialize(type:, name:)
+          @type = map_type(type)
+          @name = name.to_s
+          @configs = []
+          @operations = Hash.new { |h, k| h[k] = [] }
+
+          freeze
+        end
+
+        OPERATIONS_TYPES_MAP.each do |op_name, op_value|
+          # Adds an outgoing operation to a given resource of a given type
+          # Useful since we alter in batches and not one at a time
+          class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            # @param name [String] name of the config to alter
+            # @param value [String] value of the config
+            def #{op_name}(name, value #{op_name == :delete ? ' = nil' : ''})
+              @operations[#{op_value}] << Config.new(name: name, value: value.to_s)
+            end
+          RUBY
+        end
+
+        # @return [Hash] resource converted to a hash that rdkafka can work with
+        # @note Configs include the operation type and are expected to be used only for the
+        #   incremental alter API.
+        def to_native_hash
+          configs_with_operations = []
+
+          @operations.each do |op_type, configs|
+            configs.each do |config|
+              configs_with_operations << config.to_native_hash.merge(op_type: op_type)
+            end
+          end
+
+          {
+            resource_type: RESOURCE_TYPES_MAP.fetch(type),
+            resource_name: name,
+            configs: configs_with_operations
+          }.freeze
+        end
+
+        private
+
+        # Recognizes whether the type is provided and remaps it to a symbol representation if
+        # needed
+        #
+        # @param type [Symbol, Integer]
+        # @return [Symbol]
+        def map_type(type)
+          inverted = RESOURCE_TYPES_MAP.invert
+
+          return inverted[type] if inverted.key?(type)
+
+          RESOURCE_TYPES_MAP.fetch(type) ? type : nil
+        end
+      end
+    end
+  end
+end