karafka-core 2.6.1 → 2.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d9f6ba569f0c3a911cbe3ce80c545f3069b5aa2560782cf88bd11c97baa0432
-  data.tar.gz: 54f274da23e99841809f884ea871ce9a55705d76d3c4e5c40b0ef2ffbe0ae75a
+  metadata.gz: b5f044e02de2bc5b5e41fb033c9e4f0a4e66f45890615053d3c1fe1c33ec8058
+  data.tar.gz: 5ad2604a98478db69950c2a94064dcd20d6ceafa6d3eab03d907700b6cadf3eb
 SHA512:
-  metadata.gz: 3a6c6ba64216479cebb2c4f574dff194ae6665189f382b0a60193c5b4ec3ab4d55f4ff97d7fb3fc90800f105a5284da27493b5694adff6e1a6c0738fa5795f65
-  data.tar.gz: 8ea0eddcd9ae95603041f8a74a1a26311cd9aa13744759dd6e7a699eb6ce682fd89596ef85e77ee2fd280d4aa3eca14d8f2ddd7a75dc322fe6e7bb33903ac7b6
+  metadata.gz: 0cd334edd644f023a15d87bd35cfe535ca0edcddb39f37630c283801bed26821f3cfa6bfcb478bdd987fae0a549bbdbda56cb4258430f8f676636c368afcddcc
+  data.tar.gz: 44a3eba562af3a0315391f362b28684c54f543110f6f76dd6e99e576655c749866a737f1235cf1971992c0274ed3a1da21db3cf83b07cc83ec28e76ef8d17424

data/.github/workflows/ci.yml

@@ -29,7 +29,7 @@ jobs:
           - ruby: '4.0'
             coverage: 'true'
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
 
@@ -37,7 +37,7 @@ jobs:
         run: "[ -e $APT_DEPS ] || sudo apt-get install -y --no-install-recommends $APT_DEPS"
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@12fd324f1d0b43274fdc8130f6980590a667c455 # v1.312.0
+        uses: ruby/setup-ruby@9eb537ca036ebaed86729dcb9309076e4c5c3b74 # v1.314.0
         with:
           ruby-version: ${{matrix.ruby}}
           bundler: 'latest'
@@ -65,11 +65,11 @@ jobs:
     env:
       BUNDLE_GEMFILE: Gemfile.lint
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
       - name: Set up Ruby
-        uses: ruby/setup-ruby@12fd324f1d0b43274fdc8130f6980590a667c455 # v1.312.0
+        uses: ruby/setup-ruby@9eb537ca036ebaed86729dcb9309076e4c5c3b74 # v1.314.0
         with:
           ruby-version: '4.0.5'
           bundler-cache: true
@@ -82,11 +82,11 @@ jobs:
     env:
       BUNDLE_GEMFILE: Gemfile.lint
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
       - name: Set up Ruby
-        uses: ruby/setup-ruby@12fd324f1d0b43274fdc8130f6980590a667c455 # v1.312.0
+        uses: ruby/setup-ruby@9eb537ca036ebaed86729dcb9309076e4c5c3b74 # v1.314.0
         with:
           ruby-version: '4.0.5'
           bundler-cache: true
@@ -97,7 +97,7 @@ jobs:
     timeout-minutes: 5
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
       - name: Set up Node.js

data/.github/workflows/push.yml

@@ -19,12 +19,12 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@12fd324f1d0b43274fdc8130f6980590a667c455 # v1.312.0
+        uses: ruby/setup-ruby@9eb537ca036ebaed86729dcb9309076e4c5c3b74 # v1.314.0
         with:
           bundler-cache: false
 
@@ -32,4 +32,4 @@ jobs:
         run: |
           bundle install --jobs 4 --retry 3
 
-      - uses: rubygems/release-gem@6317d8d1f7e28c24d28f6eff169ea854948bd9f7 # v1.2.0
+      - uses: rubygems/release-gem@052cc82692552de3ef2b81fd670e41d13cba8092 # v1.4.0

data/.github/workflows/verify-action-pins.yml

@@ -7,7 +7,7 @@ jobs:
   verify_action_pins:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - name: Check SHA pins
         run: |
           if grep -E -r "uses: .*/.*@(v[0-9]+|main|master)($|[[:space:]]|$)" --include="*.yml" --include="*.yaml" .github/workflows/ | grep -v "#"; then

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Karafka Core Changelog
 
+## 2.6.2 (2026-06-29)
+- [Enhancement] Document that a leaf's `default` value is intentionally shared by reference across the class template and every config instance produced by `Configurable::Node#deep_dup`. This uniform rule (the leaf is shallow-copied) is what lets a shared service object passed as a default (e.g. a logger) keep its identity across all configs; the flip side is that an in-place mutation of a mutable container default (`config.list << :x`) is visible on every instance. Callers that need a per-instance mutable default should assign it inside a `configure` block or dup it themselves rather than relying on a mutable `default:` (e.g. `default: []`). Adds characterization tests covering the shared-default behavior.
+- [Fix] `require "pathname"` explicitly in `lib/karafka-core.rb` (with the other top-level requires). `Karafka::Core.gem_root` returns a `Pathname`, but the gem never required `pathname` -- it only worked because Bundler (or another gem) happened to load it first. In an environment where nothing else loads it, `gem_root` raised `NameError: uninitialized constant Pathname`.
+- [Enhancement] Document the `virtual` rule result contract: a rule must return a freshly built `Array` of `[path, message]` error pairs on every call. `Contract#call` takes ownership of that array and prepends the current scope onto each pair in place (avoiding a per-error allocation), so returning a memoized, shared or frozen array is unsupported -- the in-place scoping would accumulate the scope prefix across validations or raise `FrozenError`. Adds characterization tests for the supported and unsupported patterns.
+- [Fix] `Configurable::Node#register` raises the documented "already registered" `ArgumentError` for a name already used by an unread lazy-with-constructor setting. The duplicate guard only checked `@configs_refs`, but a lazy setting with a constructor is absent from it until first read, so `register` silently overwrote it; it now checks the defined children.
+- [Fix] `Contractable::Contract.nested` now pops its path in an `ensure`. If the block raised while the contract was being defined and the caller rescued it, the path stayed on the nesting stack and was prefixed onto every rule defined afterwards.
+- [Fix] `Contract#call` no longer raises `NoMethodError` when validating a non-Hash root with a 1-key or 2-key rule path; it reports the path as missing, consistent with the 3+-key path (and the non-Hash intermediate handling added in 2.6.1).
+- [Fix] Honor `excluded_keys` containing `"cgrp"` in `StatisticsDecorator` `only_keys` mode. The `cgrp` branch of the structure-aware fast path lacked the exclusion guard that the `brokers` and `topics` branches have, so excluding the consumer-group subtree still decorated it (inconsistent with the full-decoration path).
+- [Fix] Guard the patched rdkafka error callback against a null client pointer. librdkafka can invoke the error callback with a NULL `rd_kafka_t` (e.g. very early in client construction); calling `rd_kafka_name` on it dereferenced the null pointer and could segfault the process. Mirrors the upstream `ErrorCallback`.
+- [Fix] Resolve fatal errors in the patched rdkafka error callback. `ERR__FATAL` is only a generic marker, so the callback now fetches the real underlying error code and description via `RdkafkaError.build_fatal` (`rd_kafka_fatal_error`) instead of reporting the generic fatal code. Mirrors the upstream `ErrorCallback`.
+- [Fix] A lazy setting declared without a constructor (`setting(:x, lazy: true)`) no longer raises when its accessor is read. `lazy: true` only makes sense together with a constructor to (re)evaluate; without one there is nothing to evaluate, so such a setting now behaves like a regular setting backed by its default. Previously reading it raised `NoMethodError` — `nil.arity` through the dynamic accessor for a falsy default, or a missing accessor for a truthy default.
+- [Fix] `Contract#call` no longer raises `NoMethodError` when a virtual rule returns `false`. A virtual rule now signals "no errors" with any non-Array result (`true`/`false`/`nil`); only an `Array` of error pairs is collected. Previously a `false` return reached `false.each` (a `nil` return was already tolerated).
+- [Fix] Manage `CallbacksManager` callbacks copy-on-write: `add`/`delete` rebuild and atomically swap an immutable values snapshot under a mutex, and `#call` iterates that snapshot directly. The previous values cache (introduced in 2.5.11) was lazily invalidated from within `#call`, which could not be done atomically against a concurrent `add`/`delete`, so a callback racing with dispatch could be silently lost — a removed one kept firing forever, or a newly added one never fired. The copy-on-write read takes no lock and allocates nothing per call, so the race is fixed without reintroducing a per-call `#values` allocation. librdkafka statistics/error callbacks fire from a background thread while callbacks are registered/unregistered, so this was reachable in practice.
+- [Fix] Manage `Notifications` subscriptions copy-on-write (`#subscribe`, `#unsubscribe` and `#clear` replace the per-event listener array instead of mutating it in place) so a listener that unsubscribes itself (or another) from within its own handler no longer causes the listener following it to be silently skipped, and concurrent subscribe/unsubscribe during dispatch is safe. Dispatch keeps iterating the live array directly, so there is no per-notification allocation on the hot path.
+- [Fix] Report a freeze duration (`_fd`) of `0` for statistics keys that are newly introduced in an emission (e.g. a broker or partition that appears mid-stream) instead of the elapsed time since the previous emission. A key that did not exist in the prior emission could not have been "frozen" for any duration, so accumulating the inter-emission gap was incorrect and also made the related `StatisticsDecorator` spec flaky on slow CIs (`_fd` depended on the wall-clock gap between the two emissions).
+- [Fix] Make assigning a setting on a frozen `Configurable::Node` atomic. The ivar-backed writer evaluated `@configs_refs[name] = value` before `instance_variable_set`, so a frozen node mutated the canonical store and only then raised `FrozenError`, leaving the store and the ivar-backed reader permanently out of sync. It now raises before touching any state.
+- [Fix] `Configurable::Node#to_h` now evaluates a setting's constructor with its default (arity-aware, matching `#compile`) instead of calling it with no arguments. The documented `->(default) { ... }` constructor form previously raised `ArgumentError: wrong number of arguments` from `#to_h` whenever the value was not yet in the config store (e.g. `#to_h` on an unconfigured instance, or an unread lazy setting).
+- [Fix] Honor `excluded_keys` inside `StatisticsDecorator` `only_keys` decoration. A key listed in both `only_keys` and `excluded_keys` was still decorated because the direct-access decoration loop never consulted `excluded_keys`; exclusion now wins, matching the full-decoration path.
+- [Fix] Strip the tests/specs root directory as an anchored prefix (`sub(/\A.../)`) instead of a global `gsub` in `MinitestLocator` and `RSpecLocator`. When the root directory string recurred later in a test/spec file path, the global replace removed every occurrence and corrupted the derived subject class path; only the leading prefix is now removed.
+
 ## 2.6.1 (2026-06-15)
 - [Enhancement] Speed up `Contract#call` by ~1.25x for minimal and ~1.4x for fully populated data: resolve rule paths with a single `Hash#fetch` per level instead of `key?` + `[]`, inline the per-rule type dispatch into the rules loop, and compare the dig sentinel via `#equal?` so `#==` is never dispatched to the validated (user-provided) values. This is the per-message validation path in WaterDrop producers.
 - [Fix] `Contract#call` with rule paths of 3+ keys no longer raises `NoMethodError` when an intermediate value is not a `Hash` and reports the path as missing instead, consistent with the 2-key path behavior.
@@ -33,6 +53,7 @@
 - [Enhancement] Replace `StatisticsDecorator#diff` pending-writes buffer with `keys.each` direct-write iteration, eliminating the buffer and write-back loop for ~13% faster decoration at scale (10 brokers, 20 topics, 2000 partitions).
 - [Enhancement] Reorder `StatisticsDecorator#diff` type checks to test `Numeric` before `Hash`, matching the ~80% numeric value distribution in librdkafka statistics.
 - [Enhancement] Support `only_keys` option in `StatisticsDecorator` to decorate only specified numeric keys (e.g. `consumer_lag`, `committed_offset`). When combined with `excluded_keys`, reduces decoration cost from ~80ms to ~8.5ms per call on large clusters (10 brokers, 20 topics, 2000 partitions) by using structure-aware navigation of the librdkafka statistics tree and direct key access instead of full-hash iteration.
+- [Enhancement] Cache `Tags#to_a` values array and invalidate on `add`/`delete`/`clear` to avoid allocating a new Array and running `uniq` on every call, yielding ~7x faster reads at 5 tags and ~28x faster at 20 tags.
 
 ## 2.5.10 (2026-03-02)
 - [Enhancement] Introduce `MinitestLocator` helper for minitest/spec subject class auto-discovery from test file paths.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    karafka-core (2.6.1)
+    karafka-core (2.6.2)
       karafka-rdkafka (>= 0.20.0)
       logger (>= 1.6.0)
 

data/lib/karafka/core/configurable/node.rb

@@ -116,7 +116,10 @@ module Karafka
               result = if @configs_refs.key?(value.node_name)
                 @configs_refs[value.node_name]
               elsif value.constructor
-                value.constructor.call
+                # Use the arity-aware helper (same as `#compile`) so a `->(default) { ... }`
+                # constructor receives its default instead of being called with no arguments,
+                # which would raise `ArgumentError: wrong number of arguments`.
+                call_constructor(value)
               elsif value.default
                 value.default
               end
@@ -144,6 +147,17 @@ module Karafka
               # After inheritance we need to reload the state so the leafs are recompiled again
               value = value.dup
               value.compiled = false
+
+              # `Struct#dup` is intentionally shallow here: the leaf's `default` value is shared by
+              # reference across the class template and every config instance produced by
+              # `deep_dup`. This is the contract -- one uniform rule for all default types -- and it
+              # is what lets a shared service object passed as a default (e.g. a logger) keep its
+              # identity across all configs instead of being cloned per instance. The flip side is
+              # that an in-place mutation of a mutable container default (e.g. `config.list << :x`)
+              # is visible on every other instance and on the template. A caller that needs a
+              # per-instance mutable default should not rely on a mutable `default:` (e.g.
+              # `default: []`): assign the value inside a `configure` block, or dup it themselves,
+              # so each instance owns its own copy.
               value
             else
               value.deep_dup
@@ -175,7 +189,12 @@ module Karafka
 
           prevent_reserved_names!(name)
 
-          raise ArgumentError, "#{name} is already registered" if @configs_refs.key?(name)
+          # Check the defined children, not just @configs_refs: a lazy setting with a constructor
+          # is not written to @configs_refs until first read, so a `@configs_refs.key?` guard
+          # alone would silently overwrite it instead of raising the documented error.
+          if @children.any? { |child| child.node_name == name }
+            raise ArgumentError, "#{name} is already registered"
+          end
 
           leaf = Leaf.new(name, value, nil, true, false)
           @children << leaf
@@ -190,7 +209,12 @@ module Karafka
             # Do not redefine something that was already set during compilation
             # This will allow us to reconfigure things and skip override with defaults
             skippable = @configs_refs.key?(value.node_name) || (value.is_a?(Leaf) && value.compiled?)
-            lazy_leaf = value.is_a?(Leaf) && value.lazy?
+            # A leaf is only treated as lazy (a dynamically (re)evaluated accessor) when it
+            # actually has a constructor to evaluate. `lazy: true` without a constructor has
+            # nothing to evaluate, so it behaves like a regular setting backed by its default.
+            # Otherwise the lazy path builds a dynamic accessor that calls `constructor.arity`
+            # on a `nil` constructor and crashes on first read.
+            lazy_leaf = value.is_a?(Leaf) && value.lazy? && !value.constructor.nil?
 
             # Do not create accessor for leafs that are lazy as they will get a custom method
             # created instead
@@ -295,7 +319,8 @@ module Karafka
             ivar_name = :"@#{reader_name}"
 
             define_singleton_method(:"#{reader_name}=") do |new_value|
-              instance_variable_set(ivar_name, @configs_refs[reader_name] = new_value)
+              instance_variable_set(ivar_name, new_value)
+              @configs_refs[reader_name] = new_value
             end
           else
             define_singleton_method(:"#{reader_name}=") do |new_value|

data/lib/karafka/core/contractable/contract.rb

@@ -40,8 +40,14 @@ module Karafka
           def nested(path, &)
             init_accu
             @nested << path
-            instance_eval(&)
-            @nested.pop
+            begin
+              instance_eval(&)
+            ensure
+              # Always pop, even if the block raises. Otherwise a rescued exception during
+              # contract definition would leave `path` on @nested and prefix it onto every rule
+              # defined afterwards.
+              @nested.pop
+            end
           end
 
           # Defines a rule for a required field (required means, that will automatically create an
@@ -61,10 +67,19 @@ module Karafka
             @rules << Rule.new(@nested + keys, :optional, block).freeze
           end
 
-          # @param block [Proc] validation rule
+          # Defines a virtual rule that validates the whole data rather than a single key. Unlike
+          # `required`/`optional`, the block receives the full data and returns its own errors.
+          #
+          # @param block [Proc] validation rule, called with `(data, errors, contract)`. It must
+          #   return either a non-Array (`true`/`nil`/`false`) for "no errors", or an `Array` of
+          #   `[path, message]` error pairs (where `path` is itself an `Array` of symbols).
           #
-          # @note Virtual rules have different result expectations. Please see contracts or specs for
-          #   details.
+          # @note The returned error `Array` is owned by the contract: `#call` prepends the current
+          #   scope onto each pair in place and collects them, so a rule must return a freshly
+          #   built `Array` on every call. Returning a memoized, shared or frozen `Array` is not
+          #   supported -- in-place scoping would accumulate the prefix across validations (or
+          #   raise `FrozenError`). Build the result in the block (e.g. `[[%i[id], :invalid]]`)
+          #   rather than returning a constant.
           def virtual(&block)
             init_accu
             @rules << Rule.new([], :virtual, block).freeze
@@ -94,19 +109,32 @@ module Karafka
         def call(data, scope: EMPTY_ARRAY)
           errors = []
 
+          # A non-Hash root has no keys to dig; resolve it once here so #dig stays on its lean
+          # fast path and is only invoked with a Hash. Non-Hash data makes every required rule
+          # report missing, consistent with the non-Hash intermediate handling inside #dig.
+          data_is_hash = data.is_a?(Hash)
+
           self.class.rules.each do |rule|
             if rule.type == :virtual
               result = rule.validator.call(data, errors, self)
 
-              next if result == true
-
-              result&.each do |sub_result|
+              # A virtual rule signals "no errors" with any non-Array result (true, but also a
+              # falsy `nil`/`false` returned by e.g. `condition && [[...], :err]`). Only an Array
+              # of error pairs is iterated; previously a `false` return reached `false.each` and
+              # raised NoMethodError (a `nil` return was already tolerated by the safe navigation).
+              next unless result.is_a?(Array)
+
+              # Apply the scope prefix in place on the rule's returned pairs and collect them
+              # directly. Per the `virtual` contract the rule hands back a freshly built Array
+              # each call (see `DSL#virtual`), so mutating it here is safe and avoids allocating a
+              # new pair per error.
+              result.each do |sub_result|
                 sub_result[0] = scope + sub_result[0]
               end
 
               errors.push(*result)
             else
-              for_checking = dig(data, rule.path)
+              for_checking = data_is_hash ? dig(data, rule.path) : DIG_MISS
 
               if DIG_MISS.equal?(for_checking)
                 errors << [scope + rule.path, :missing] if rule.type == :required

data/lib/karafka/core/helpers/minitest_locator.rb

@@ -36,7 +36,7 @@ module Karafka
             .first
             .split(":")
             .first
-            .gsub(@tests_root_dir, "")
+            .sub(/\A#{::Regexp.escape(@tests_root_dir)}/, "")
             .gsub("_test.rb", "")
             .split("/")
             .delete_if(&:empty?)

data/lib/karafka/core/helpers/rspec_locator.rb

@@ -39,7 +39,7 @@ module Karafka
             .first
             .split(":")
             .first
-            .gsub(@specs_root_dir, "")
+            .sub(/\A#{::Regexp.escape(@specs_root_dir)}/, "")
             .gsub("_spec.rb", "")
             .split("/")
             .delete_if(&:empty?)

data/lib/karafka/core/instrumentation/callbacks_manager.rb

@@ -10,20 +10,21 @@ module Karafka
         # @return [::Karafka::Core::Instrumentation::CallbacksManager]
         def initialize
           @callbacks = {}
-          @values_cache = nil
+          @values = [].freeze
+          @mutex = Mutex.new
         end
 
         # Invokes all the callbacks registered one after another
         #
         # @param args [Object] any args that should go to the callbacks
-        # @note We do not use `#each_value` here on purpose. With it being used, we cannot dispatch
-        #   callbacks and add new at the same time. Since we don't know when and in what thread
-        #   things are going to be added to the manager, we need to extract values into an array and
-        #   run it. That way we can add new things the same time.
-        #   The values snapshot is cached and invalidated on add/delete to avoid allocating a new
-        #   Array on every call while preserving the thread-safety snapshot semantics.
+        # @note Copy-on-write: dispatch iterates an immutable snapshot that `add`/`delete`
+        #   rebuild and swap in under a mutex. Because `#call` never mutates shared state, it
+        #   needs neither a lock nor a per-call `#values` allocation, and a callback registered
+        #   or removed from another thread is never lost; it just takes effect on the next
+        #   `#call`. A cache invalidated from within `#call` could not be updated atomically
+        #   against this read, so a stale write-back would permanently drop callbacks.
         def call(*args)
-          (@values_cache ||= @callbacks.values).each { |callback| callback.call(*args) }
+          @values.each { |callback| callback.call(*args) }
         end
 
         # Adds a callback to the manager
@@ -31,15 +32,19 @@ module Karafka
         # @param id [String] id of the callback (used when deleting it)
         # @param callable [#call] object that responds to a `#call` method
         def add(id, callable)
-          @callbacks[id] = callable
-          @values_cache = nil
+          @mutex.synchronize do
+            @callbacks[id] = callable
+            @values = @callbacks.values.freeze
+          end
         end
 
         # Removes the callback from the manager
         # @param id [String] id of the callback we want to remove
         def delete(id)
-          @callbacks.delete(id)
-          @values_cache = nil
+          @mutex.synchronize do
+            @callbacks.delete(id)
+            @values = @callbacks.values.freeze
+          end
         end
       end
     end

data/lib/karafka/core/monitoring/notifications.rb

@@ -48,8 +48,17 @@ module Karafka
         # @param event_id [String] the key of the event to clear listeners for.
         def clear(event_id = nil)
           @mutex.synchronize do
-            return @listeners.each_value(&:clear) unless event_id
-            return @listeners[event_id].clear if @listeners.key?(event_id)
+            # Copy-on-write: replace the per-event arrays rather than mutating them in place, so a
+            # dispatch iterating a previously captured array is unaffected (see #notify_listeners).
+            unless event_id
+              @listeners.transform_values! { [] }
+              return
+            end
+
+            if @listeners.key?(event_id)
+              @listeners[event_id] = []
+              return
+            end
 
             raise(EventNotRegistered, "#{event_id} not registered!")
           end
@@ -76,14 +85,16 @@ module Karafka
 
               raise EventNotRegistered, event_id unless @listeners.key?(event_id)
 
-              @listeners[event_id] << block
+              # Copy-on-write: append by replacing the array, never mutating the one a concurrent
+              # dispatch may be iterating (see #notify_listeners).
+              @listeners[event_id] += [block]
             else
               listener = event_id_or_listener
 
               @listeners.each_key do |reg_event_id|
                 next unless listener.respond_to?(@events_methods_map[reg_event_id])
 
-                @listeners[reg_event_id] << listener
+                @listeners[reg_event_id] += [listener]
               end
             end
           end
@@ -98,9 +109,9 @@ module Karafka
         #   unsubscribe(my_listener)
         def unsubscribe(listener_or_block)
           @mutex.synchronize do
-            @listeners.each_value do |event_listeners|
-              event_listeners.delete(listener_or_block)
-            end
+            # Copy-on-write: rebuild each array without the listener instead of deleting in place,
+            # so a dispatch iterating a previously captured array still sees the full set.
+            @listeners.transform_values! { |event_listeners| event_listeners - [listener_or_block] }
           end
         end
 

data/lib/karafka/core/monitoring/statistics_decorator.rb

@@ -14,7 +14,16 @@ module Karafka
       #   - KEY_fd - freeze duration - describes how long the delta remains unchanged (zero)
       #              and can be useful for detecting values that "hang" for extended period of time
       #              and do not have any change (delta always zero). This value is in ms for the
-      #              consistency with other time operators we use.
+      #              consistency with other time operators we use. A newly introduced key (one
+      #              that had no value in the previous emission) starts at a freeze duration of
+      #              zero, since there is no prior value it could have been "frozen" against.
+      #
+      # The `_d` and `_fd` suffixes are reserved. For every numeric KEY the decorator writes
+      # `KEY_d` and `KEY_fd` into the same hash, so if the input already contains a real key
+      # literally named `KEY_d` or `KEY_fd` (for another numeric KEY present in that hash) it is
+      # overwritten by the computed delta/freeze duration. librdkafka statistics never use these
+      # suffixes, so this does not happen with real stats; it only matters if you feed custom data
+      # through the decorator.
       class StatisticsDecorator
         include Helpers::Time
 
@@ -28,11 +37,17 @@ module Karafka
         #   duration suffixes. This is useful for skipping large subtrees of the librdkafka
         #   statistics that are not consumed by the application (e.g. broker toppars, window
         #   stats like int_latency, outbuf_latency, throttle, batchsize, batchcnt, req).
-        # @param only_keys [Array<String>] when set, only these numeric keys will be decorated
-        #   with delta/freeze duration suffixes. Hash children are still recursed into for
-        #   structural navigation, but only the listed keys receive _d and _fd computation.
-        #   This drastically reduces work at the partition level where most cost occurs.
-        #   When empty (default), all numeric keys are decorated.
+        # @param only_keys [Array<String>] when set, only these numeric keys are decorated with
+        #   delta/freeze duration suffixes, and only at the levels of the known librdkafka
+        #   statistics tree: the root, each broker, each topic, each partition and cgrp. The
+        #   decorator navigates that known structure directly and decorates the listed keys it
+        #   finds at each of those levels. It deliberately does NOT descend into nested
+        #   sub-objects within a broker, topic, partition or cgrp (e.g. broker window stats like
+        #   rtt/throttle/int_latency, or the toppars map) -- skipping that descent is exactly what
+        #   makes this mode cheap on large clusters. Non-librdkafka hash children found at the
+        #   root are still fully recursed for correctness. If you need a key nested inside one of
+        #   those sub-objects decorated, use the default full-decoration mode. When empty
+        #   (default), all numeric keys at every depth are decorated.
         def initialize(excluded_keys: [], only_keys: [])
           @previous = EMPTY_HASH
           # Operate on ms precision only
@@ -44,9 +59,12 @@ module Karafka
           @excluded_keys = unless excluded_keys.empty?
             excluded_keys.each_with_object({}) { |k, h| h[k] = true }.freeze
           end
-          # Frozen array for direct-access decoration, nil when empty to use full decoration
+          # Frozen array for direct-access decoration, nil when empty to use full decoration.
+          # Exclusions are applied once here (excluded_keys wins over only_keys), so the hot
+          # decoration loop iterates an already-filtered list and never re-checks exclusions.
           @only_keys = unless only_keys.empty?
-            only_keys.freeze
+            effective = @excluded_keys ? only_keys.reject { |k| @excluded_keys.key?(k) } : only_keys
+            effective.freeze
           end
         end
 
@@ -120,18 +138,17 @@ module Karafka
             if value.is_a?(Numeric)
               prev_value = filled_previous[key]
 
+              pair = cache[key] || (cache[key] = ["#{key}_fd".freeze, "#{key}_d".freeze].freeze)
+
               if prev_value.nil?
-                result = 0
-              elsif prev_value.is_a?(Numeric)
-                result = value - prev_value
+                current[pair[0]] = 0
+                current[pair[1]] = 0
               else
-                next
-              end
-
-              pair = cache[key] || (cache[key] = ["#{key}_fd".freeze, "#{key}_d".freeze].freeze)
+                result = value - prev_value
 
-              current[pair[0]] = (result == 0) ? (filled_previous[pair[0]] || 0) + change_d : 0
-              current[pair[1]] = result
+                current[pair[0]] = (result == 0) ? (filled_previous[pair[0]] || 0) + change_d : 0
+                current[pair[1]] = result
+              end
             elsif value.is_a?(Hash)
               diff_all(filled_previous[key], value, change_d)
             end
@@ -156,8 +173,13 @@ module Karafka
         # librdkafka statistics layout: root → brokers → broker, root → topics → topic →
         # partitions → partition, root → cgrp.
         #
-        # For non-librdkafka hash children (e.g. custom or test data), falls back to generic
-        # recursion to maintain correctness with arbitrary nested structures.
+        # Broker, topic, partition and cgrp nodes are decorated as leaves: their listed keys are
+        # decorated, but their nested sub-objects (e.g. broker window stats like rtt/throttle, or
+        # the toppars map) are NOT descended into. Not descending into those large sub-objects is
+        # the whole point of this path, so they are intentionally left untouched here.
+        #
+        # For non-librdkafka hash children at the root (e.g. custom or test data), falls back to
+        # generic recursion to maintain correctness with arbitrary nested structures.
         #
         # @param previous [Object] previous value from the given scope
         # @param current [Hash] current stats hash (root level)
@@ -209,8 +231,10 @@ module Karafka
           end
 
           # Consumer group (leaf-like)
-          cgrp = current["cgrp"]
-          decorate_keys(cgrp, filled_previous["cgrp"] || EMPTY_HASH, change_d) if cgrp.is_a?(Hash)
+          unless excluded&.key?("cgrp")
+            cgrp = current["cgrp"]
+            decorate_keys(cgrp, filled_previous["cgrp"] || EMPTY_HASH, change_d) if cgrp.is_a?(Hash)
+          end
 
           # Fallback: handle any non-standard hash children not in the known structure.
           # This ensures correctness for arbitrary nested data while the known paths above
@@ -275,18 +299,17 @@ module Karafka
 
             prev_value = filled_previous[key]
 
+            pair = cache[key] || (cache[key] = ["#{key}_fd".freeze, "#{key}_d".freeze].freeze)
+
             if prev_value.nil?
-              result = 0
-            elsif prev_value.is_a?(Numeric)
-              result = value - prev_value
+              current[pair[0]] = 0
+              current[pair[1]] = 0
             else
-              next
-            end
-
-            pair = cache[key] || (cache[key] = ["#{key}_fd".freeze, "#{key}_d".freeze].freeze)
+              result = value - prev_value
 
-            current[pair[0]] = (result == 0) ? (filled_previous[pair[0]] || 0) + change_d : 0
-            current[pair[1]] = result
+              current[pair[0]] = (result == 0) ? (filled_previous[pair[0]] || 0) + change_d : 0
+              current[pair[1]] = result
+            end
           end
         end
       end

data/lib/karafka/core/patches/rdkafka/bindings.rb

@@ -27,9 +27,28 @@ module Karafka
               ) do |client_ptr, err_code, reason, _opaque|
                 return nil unless ::Rdkafka::Config.error_callback
 
-                name = ::Rdkafka::Bindings.rd_kafka_name(client_ptr)
+                # Guard against a null client pointer. librdkafka can invoke the error callback
+                # with a NULL `rd_kafka_t` (e.g. very early in client construction), and calling
+                # `rd_kafka_name` on it dereferences the pointer and segfaults the whole process.
+                # Mirrors the upstream `ErrorCallback`.
+                name = client_ptr.null? ? nil : ::Rdkafka::Bindings.rd_kafka_name(client_ptr)
+
+                # Resolve fatal errors to their underlying cause. `ERR__FATAL` is only a generic
+                # marker; the real error code and description must be fetched from librdkafka via
+                # `rd_kafka_fatal_error` (done by `RdkafkaError.build_fatal`). Without this the
+                # callback would report the generic fatal code instead of the actual error.
+                # Mirrors the upstream `ErrorCallback`.
+                error = if err_code == ::Rdkafka::Bindings::RD_KAFKA_RESP_ERR__FATAL
+                  ::Rdkafka::RdkafkaError.build_fatal(
+                    client_ptr,
+                    fallback_error_code: err_code,
+                    fallback_message: reason,
+                    instance_name: name
+                  )
+                else
+                  ::Rdkafka::RdkafkaError.new(err_code, broker_message: reason)
+                end
 
-                error = ::Rdkafka::RdkafkaError.new(err_code, broker_message: reason)
                 error.set_backtrace(caller)
 
                 ::Rdkafka::Config.error_callback.call(name, error)

data/lib/karafka/core/taggable/tags.rb

@@ -10,6 +10,7 @@ module Karafka
         # Creates new tags accumulator
         def initialize
           @accu = {}
+          @values_cache = nil
         end
 
         # Adds a tag with a given name to tags
@@ -17,22 +18,25 @@ module Karafka
         # @param tag [#to_s] any object that can be converted into a string via `#to_s`
         def add(name, tag)
           @accu[name] = tag.to_s
+          @values_cache = nil
         end
 
         # Removes all the tags
         def clear
           @accu.clear
+          @values_cache = nil
         end
 
         # Removes a tag with a given name
         # @param name [Symbol] name of the tag
         def delete(name)
           @accu.delete(name)
+          @values_cache = nil
         end
 
         # @return [Array<String>] all unique tags registered
         def to_a
-          @accu.values.tap(&:uniq!)
+          @values_cache ||= @accu.values.uniq
         end
 
         # @param _args [Object] anything that the standard `to_json` accepts

data/lib/karafka/core/version.rb

@@ -4,6 +4,6 @@ module Karafka
   module Core
     # Current Karafka::Core version
     # We follow the versioning schema of given Karafka version
-    VERSION = "2.6.1"
+    VERSION = "2.6.2"
   end
 end

data/lib/karafka-core.rb

@@ -2,6 +2,7 @@
 
 require "logger"
 require "yaml"
+require "pathname"
 require "rdkafka"
 require "karafka/core"
 require "karafka/core/version"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: karafka-core
 version: !ruby/object:Gem::Version
-  version: 2.6.1
+  version: 2.6.2
 platform: ruby
 authors:
 - Maciej Mensfeld