karafka-core 2.6.5 → 2.6.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 236e0814cbc0a24dc6758f75c71057e7744c0827f1c9cb4b5be5f305bceefc46
-  data.tar.gz: b3d9b8d7b42e9af2aaa2609bd929dab513375aa86ebf49d198c94e11cb81427c
+  metadata.gz: 69c1a45639ef9a5f60dfe01427637a68be3a284a1d3cc6645f35c7f1bc4db60a
+  data.tar.gz: af342b72f3862e8264fbc09e4e6ba473ff13a0b2615ea78738071f5b366e9c48
 SHA512:
-  metadata.gz: e6cabe34dc4bb8449ba87cec2d1dc7d120277fecc771ee7a90509f34454e28705a7ab3e883a68799ac128badd9e5f8ad3d5d6898e2e4d1565568dad3b98f0bb9
-  data.tar.gz: 80072d69c0ae0eb59b933c83d530e3099bf16f16c596b34bdf16c70f0986938c599dbb65c13331c69e7881119cde8c200fc51713729e84a085c15dd6d989fdba
+  metadata.gz: 0ed70ee79bf6cb77ec89df3e68d30829b70c79dadc699b491006c3ac536009230fdd188996a7386c1cce0140625c04002a00575b7c5fda6b7d82a172b241e6e4
+  data.tar.gz: c7d33f57867534c8afa1ab28a00f63b4d806fc2286c61bdb31a0111b8a81048e8a1ce654b8ff5dbc0dd7736d70ad8db92738b264c7ed6d3124ba0fc6da96105e

data/.github/workflows/ci.yml

@@ -36,7 +36,7 @@ jobs:
         run: "[ -e $APT_DEPS ] || sudo apt-get install -y --no-install-recommends $APT_DEPS"
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@651ff0d62c5c79bed6d53ec518387aae20e72c1a # v1.329.0
+        uses: ruby/setup-ruby@824c0e29fdfc7d689c191c27acc969d2d04b7dd8 # v1.331.0
         with:
           ruby-version: ${{matrix.ruby}}
           bundler: 'latest'
@@ -68,7 +68,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: Set up Ruby
-        uses: ruby/setup-ruby@651ff0d62c5c79bed6d53ec518387aae20e72c1a # v1.329.0
+        uses: ruby/setup-ruby@824c0e29fdfc7d689c191c27acc969d2d04b7dd8 # v1.331.0
         with:
           ruby-version: '4.0.7'
           bundler-cache: true
@@ -85,7 +85,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: Set up Ruby
-        uses: ruby/setup-ruby@651ff0d62c5c79bed6d53ec518387aae20e72c1a # v1.329.0
+        uses: ruby/setup-ruby@824c0e29fdfc7d689c191c27acc969d2d04b7dd8 # v1.331.0
         with:
           ruby-version: '4.0.7'
           bundler-cache: true

data/.github/workflows/push.yml

@@ -24,7 +24,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@651ff0d62c5c79bed6d53ec518387aae20e72c1a # v1.329.0
+        uses: ruby/setup-ruby@824c0e29fdfc7d689c191c27acc969d2d04b7dd8 # v1.331.0
         with:
           bundler-cache: false
 

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Karafka Core Changelog
 
+## 2.6.6 (2026-10-25)
+- [Fix] Make `Taggable::Tags` safe to read while another thread adds or removes tags. On JRuby a concurrent read could raise `NullPointerException`.
+- [Fix] Make `Taggable#tags` return one `Tags` per object when several threads call it first. On JRuby each thread could get its own `Tags`, and tags were lost.
+- [Fix] Make `Notifications#register_event` safe while other threads call `#instrument`. On JRuby a concurrent registration could make a registered event look unregistered or dispatch it without its method.
+- [Fix] Make the `Monitor` event name cache thread-safe for a namespace or Symbol event ids, so on JRuby concurrent `#instrument` calls no longer corrupt it.
+
 ## 2.6.5 (2026-10-19)
 - **[EOL]** Drop Ruby 3.2 support due to EOL; require Ruby 3.3+.
 - [Change] Use the offending value (event id, setting name, class or constant name) as the message of errors raised by `Notifications`, `Configurable::Node`, `Configurable::Importer` and the spec locators.
@@ -42,7 +48,7 @@
 - [Change] Assigning a setting on a frozen config node now raises `FrozenError` (previously the write silently mutated internal storage despite the freeze).
 
 ## 2.6.0 (2026-06-10)
-- [Enhancement] Add `Node#register` to allow runtime key-value registration on compiled nodes without going through the static `setting` DSL. Useful for dynamic registries (e.g. named clusters) where setting names are not known at class-load time.
+- [Enhancement] Add `Node#register` to register keys at runtime on compiled nodes, for dynamic registries (e.g. named clusters) whose setting names are not known at class-load time.
 - [Enhancement] Enable all opt-in Ruby warning categories via `Warning.categories`, so new ones (e.g. `strict_unused_block` in Ruby 3.4+) are picked up automatically.
 
 ## 2.5.13 (2026-04-08)
@@ -54,24 +60,24 @@
 ## 2.5.11 (2026-04-02)
 - [Enhancement] Specialize `Contract#dig` for common 1-key and 2-key paths to avoid iterator overhead, yielding ~1.5x faster single-key lookups and ~1.45x faster two-key nested lookups.
 - [Enhancement] Replace `Node#build_accessors` `@local_defs` Array with Hash for O(1) membership checks instead of O(n) `Array#include?`, yielding up to ~5x faster accessor lookups at 50 settings.
-- [Enhancement] Use frozen `EMPTY_ARRAY` constant for `Contract#call` and `#validate!` default `scope` parameter to avoid allocating a new Array on every invocation, yielding ~1.36x faster call dispatch and saving 1 Array allocation per call.
-- [Enhancement] Pre-resolve `@events_methods_map` method name before the listener notification loop in `Notifications#instrument` to avoid repeated Hash lookup per listener, yielding ~1.12x faster event dispatch with multiple listeners.
+- [Enhancement] Stop allocating an Array on every `Contract#call` and `#validate!` call (~1.36x faster dispatch).
+- [Enhancement] Speed up `Notifications#instrument` with multiple listeners (~1.12x faster event dispatch).
 - [Enhancement] Cache a frozen success `Result` singleton via `Result.success` to eliminate 1 object allocation per successful `Contract#call` on the happy path.
-- [Enhancement] Skip nestings block re-evaluation in `Node#deep_dup` to avoid recreating children that are immediately overwritten, yielding ~14x faster deep_dup and reducing allocations from ~620 to ~66 objects for large configs.
-- [Enhancement] Cache `CallbacksManager#call` values snapshot and invalidate on `add`/`delete` to avoid allocating a new Array on every invocation while preserving thread-safety snapshot semantics, saving 1 Array allocation per call.
+- [Enhancement] Speed up `Node#deep_dup` ~14x and cut its allocations from ~620 to ~66 objects for large configs.
+- [Enhancement] Stop allocating an Array on every `CallbacksManager#call` call.
 - [Enhancement] Build the `Event` payload hash lazily on `#payload` access, saving one Hash allocation per `Notifications#instrument` call with `#[]` access, for ~1.7x faster event dispatch.
-- [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] Speed up `StatisticsDecorator#diff` by ~13% 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 an `only_keys` option in `StatisticsDecorator` to decorate only the listed numeric keys. With `excluded_keys`, this cuts decoration cost from ~80ms to ~8.5ms per call on large clusters.
-- [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.
+- [Enhancement] Cache `Tags#to_a` (~7x faster reads at 5 tags, ~28x at 20 tags).
 
 ## 2.5.10 (2026-03-02)
 - [Enhancement] Introduce `MinitestLocator` helper for minitest/spec subject class auto-discovery from test file paths.
 
 ## 2.5.9 (2026-03-02)
-- [Enhancement] Optimize `StatisticsDecorator` to eliminate per-hash Array allocations by using `each_pair` with a per-call pending-writes buffer instead of `current.keys.each`, reducing allocations from tens of thousands to one per call at scale.
+- [Enhancement] Reduce `StatisticsDecorator` allocations from tens of thousands to one per call at scale.
 - [Enhancement] Inline `StatisticsDecorator#append` and `#suffix_keys_for` into `#diff` to reduce method call overhead by ~96% (from ~915k to ~39k calls at 6400 partitions).
-- [Enhancement] Support `excluded_keys` option in `StatisticsDecorator` to skip decoration of unused librdkafka statistics subtrees (e.g. broker toppars, window stats), yielding ~28% additional speedup at scale.
+- [Enhancement] Support an `excluded_keys` option in `StatisticsDecorator` to skip unused librdkafka statistics subtrees (e.g. broker toppars, window stats), ~28% faster at scale.
 
 ## 2.5.8 (2025-11-23)
 - [Enhancement] Memoize `StatisticsDecorator` suffix keys to reduce string allocations (#268).

data/Gemfile

@@ -5,7 +5,6 @@ source "https://rubygems.org"
 gemspec
 
 group :test do
-  gem "byebug"
   gem "minitest"
   gem "simplecov"
   gem "warning"

data/Gemfile.lock

@@ -1,15 +1,13 @@
 PATH
   remote: .
   specs:
-    karafka-core (2.6.5)
+    karafka-core (2.6.6)
       karafka-rdkafka (>= 0.20.0)
       logger (>= 1.6.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    byebug (13.0.0)
-      reline (>= 0.6.0)
     drb (2.2.3)
     ffi (1.17.4)
     ffi (1.17.4-aarch64-linux-gnu)
@@ -22,7 +20,6 @@ GEM
     ffi (1.17.4-x86_64-darwin)
     ffi (1.17.4-x86_64-linux-gnu)
     ffi (1.17.4-x86_64-linux-musl)
-    io-console (0.9.4)
     json (3.0.2)
     karafka-rdkafka (0.30.2)
       ffi (~> 1.17.1)
@@ -67,8 +64,6 @@ GEM
       prism (~> 1.5)
     prism (1.9.0)
     rake (13.4.2)
-    reline (0.7.0)
-      io-console (~> 0.5)
     simplecov (1.3.2)
     warning (1.6.0)
 
@@ -86,7 +81,6 @@ PLATFORMS
   x86_64-linux-musl
 
 DEPENDENCIES
-  byebug
   karafka-core!
   minitest
   simplecov

data/README.md

@@ -17,6 +17,6 @@ It includes:
 
 First, thank you for considering contributing to the Karafka ecosystem! It's people like you that make the open source community such a great community!
 
-Each pull request must pass all the RSpec specs, integration tests and meet our quality requirements.
+Each pull request must pass all the tests and meet our quality requirements.
 
 Fork it, update and wait for the Github Actions results.

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

@@ -21,6 +21,7 @@ module Karafka
           @notifications_bus = notifications_bus
           @namespace = namespace
           @mapped_events = {}
+          @mutex = Mutex.new
         end
 
         # Passes the instrumentation block (if any) into the notifications bus
@@ -35,7 +36,7 @@ module Karafka
           full_event_name = if @namespace.nil? && event_id.is_a?(String)
             event_id
           else
-            @mapped_events[event_id] ||= [event_id, @namespace].compact.join(".")
+            @mapped_events[event_id] || map_event(event_id)
           end
 
           @notifications_bus.instrument(full_event_name, payload, &)
@@ -65,6 +66,24 @@ module Karafka
         def listeners
           @notifications_bus.listeners
         end
+
+        private
+
+        # Builds and caches the full event name for an event id
+        #
+        # @param event_id [String, Symbol] event id
+        # @return [String] full event name
+        def map_event(event_id)
+          @mutex.synchronize do
+            # Copy-on-write: #instrument reads the Hash without the lock and on JRuby a Hash that
+            # is written by many threads at once can get corrupted, so we replace it instead.
+            @mapped_events[event_id] || begin
+              full_event_name = [event_id, @namespace].compact.join(".")
+              @mapped_events = @mapped_events.merge(event_id => full_event_name).freeze
+              full_event_name
+            end
+          end
+        end
       end
     end
   end

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

@@ -38,8 +38,13 @@ module Karafka
         # @param event_id [String] event id
         def register_event(event_id)
           @mutex.synchronize do
-            @listeners[event_id] = []
-            @events_methods_map[event_id] = :"on_#{event_id.to_s.tr(".", "_")}"
+            # Copy-on-write: #instrument reads both Hashes without the lock, and on JRuby a Hash
+            # that grows while another thread reads it can return nil for a registered key. The
+            # methods map goes first, so an event visible in @listeners always has its method.
+            @events_methods_map = @events_methods_map.merge(
+              event_id => :"on_#{event_id.to_s.tr(".", "_")}"
+            )
+            @listeners = @listeners.merge(event_id => [])
           end
         end
 
@@ -48,15 +53,16 @@ module Karafka
         # @param event_id [String] the key of the event to clear listeners for.
         def clear(event_id = nil)
           @mutex.synchronize do
-            # 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).
+            # Copy-on-write: replace the Hash and the per-event arrays rather than mutating them in
+            # place, so lock-free reads in #instrument and a dispatch iterating a previously
+            # captured array are unaffected (see #register_event and #notify_listeners).
             unless event_id
-              @listeners.transform_values! { [] }
+              @listeners = @listeners.transform_values { [] }
               return
             end
 
             if @listeners.key?(event_id)
-              @listeners[event_id] = []
+              @listeners = @listeners.merge(event_id => [])
               return
             end
 
@@ -85,17 +91,21 @@ module Karafka
 
               raise EventNotRegistered, event_id unless @listeners.key?(event_id)
 
-              # 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]
+              # Copy-on-write: append by replacing the Hash and the array, never mutating the ones
+              # a concurrent #instrument or dispatch may be reading (see #notify_listeners).
+              @listeners = @listeners.merge(event_id => @listeners[event_id] + [block])
             else
               listener = event_id_or_listener
 
-              @listeners.each_key do |reg_event_id|
+              listeners = @listeners.dup
+
+              @listeners.each do |reg_event_id, event_listeners|
                 next unless listener.respond_to?(@events_methods_map[reg_event_id])
 
-                @listeners[reg_event_id] += [listener]
+                listeners[reg_event_id] = event_listeners + [listener]
               end
+
+              @listeners = listeners
             end
           end
         end
@@ -109,9 +119,10 @@ module Karafka
         #   unsubscribe(my_listener)
         def unsubscribe(listener_or_block)
           @mutex.synchronize do
-            # 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] }
+            # Copy-on-write: rebuild the Hash and each array without the listener instead of
+            # deleting in place, so a dispatch iterating a previously captured array still sees
+            # the full set.
+            @listeners = @listeners.transform_values { |event_listeners| event_listeners - [listener_or_block] }
           end
         end
 

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Core
+    module Taggable
+      class Tags
+        # Tags by name and their unique values, published together so a reader never sees one
+        # without the other
+        Snapshot = Struct.new(:tags, :values)
+      end
+    end
+  end
+end

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

@@ -9,34 +9,33 @@ module Karafka
       class Tags
         # Creates new tags accumulator
         def initialize
-          @accu = {}
-          @values_cache = nil
+          @mutex = Mutex.new
+          @snapshot = Snapshot.new({}.freeze, []).freeze
         end
 
         # Adds a tag with a given name to tags
         # @param name [Symbol] name we want to use for a given tag
         # @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
+          value = tag.to_s
+
+          @mutex.synchronize { publish(@snapshot.tags.merge(name => value)) }
         end
 
         # Removes all the tags
         def clear
-          @accu.clear
-          @values_cache = nil
+          @mutex.synchronize { publish({}) }
         end
 
         # Removes a tag with a given name
         # @param name [Symbol] name of the tag
         def delete(name)
-          @accu.delete(name)
-          @values_cache = nil
+          @mutex.synchronize { publish(@snapshot.tags.except(name)) }
         end
 
         # @return [Array<String>] all unique tags registered
         def to_a
-          @values_cache ||= @accu.values.uniq
+          @snapshot.values
         end
 
         # @param _args [Object] anything that the standard `to_json` accepts
@@ -50,6 +49,17 @@ module Karafka
         def as_json(*_args)
           to_a
         end
+
+        private
+
+        # Replaces the snapshot with one built from the given tags. Readers do not lock, so the tags
+        # are never changed in place: each write publishes a new snapshot in one assignment.
+        #
+        # @param tags [Hash{Symbol => String}] all the tags after the change
+        # @return [Snapshot] the published snapshot
+        def publish(tags)
+          @snapshot = Snapshot.new(tags.freeze, tags.values.uniq).freeze
+        end
       end
     end
   end

data/lib/karafka/core/taggable.rb

@@ -8,9 +8,31 @@ module Karafka
     #
     # Tags will be converted to strings when they are added
     module Taggable
+      # One lock for the first `#tags` call of every object. That call is rare, and a lock per
+      # object would need a safe way to create it as well. Kept off the constants, because
+      # constants of this module are visible in every class that includes it.
+      @tags_lock = Mutex.new
+
+      class << self
+        # @return [Mutex] lock guarding the lazy creation of tags
+        attr_reader :tags_lock
+      end
+
       # @return [::Karafka::Core::Taggable::Tags] tags object
       def tags
-        @tags ||= Taggable::Tags.new
+        @tags || taggable_build_tags
+      end
+
+      private
+
+      # Do not inline this into `#tags`. A `#synchronize` block there makes every warm `#tags` call
+      # about 2.5x slower on JRuby, even when `@tags` is already set. A hand-written `lock` /
+      # `ensure unlock` keeps it fast but can leave the lock held when an async exception
+      # (`Thread#raise`, `Timeout`) lands between `lock` and `begin`.
+      #
+      # @return [::Karafka::Core::Taggable::Tags] tags object
+      def taggable_build_tags
+        Taggable.tags_lock.synchronize { @tags ||= Taggable::Tags.new }
       end
     end
   end

data/lib/karafka/core/version.rb

@@ -3,6 +3,6 @@
 module Karafka
   module Core
     # Current Karafka::Core version. We follow the versioning schema of given Karafka version
-    VERSION = "2.6.5"
+    VERSION = "2.6.6"
   end
 end

data/lib/karafka-core.rb

@@ -24,6 +24,7 @@ require "karafka/core/instrumentation"
 require "karafka/core/instrumentation/callbacks_manager"
 require "karafka/core/taggable"
 require "karafka/core/taggable/tags"
+require "karafka/core/taggable/tags/snapshot"
 require "karafka/core/patches/rdkafka/bindings"
 
 # Karafka framework main namespace

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: karafka-core
 version: !ruby/object:Gem::Version
-  version: 2.6.5
+  version: 2.6.6
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -93,6 +93,7 @@ files:
 - lib/karafka/core/patches/rdkafka/bindings.rb
 - lib/karafka/core/taggable.rb
 - lib/karafka/core/taggable/tags.rb
+- lib/karafka/core/taggable/tags/snapshot.rb
 - lib/karafka/core/version.rb
 - log/.gitkeep
 - package-lock.json