karafka-core 2.5.10 → 2.5.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe7a4974267a2a3b2b200e0763a13042d98695c0586931d00d0016087bc5dfe2
-  data.tar.gz: a5bdd9235a999028ad120d79c2986e05986ee1b9df8a5de6b813fff634bc5619
+  metadata.gz: a1ca213972a7e05632f164e423383f6a9172926291140ad6005c822b347855b2
+  data.tar.gz: acb97b8887fed4e6534bed1c8c764a19a38462b6a6581893ed80b3bb1efd7a82
 SHA512:
-  metadata.gz: be10ba6481782906bbb076ea69ab9aa05c80f4c295ce82c2faacc53ee27a8ebd01e4c7a200088205058fda7e7efef494d71ac96492d3cf074f579ea331597148
-  data.tar.gz: a51a53327518e282ab42461fccc3aea78407de1418d97376a64b25dda687b616a54f0c6639b542d0c104534876b1c34d9f7f1434486300c40708f129f03ad267
+  metadata.gz: 0d3ead51c6a1fe7697cb5c13d914acd148c65d0be5b04be88b898d8cb5e220f65095bab181083a993a6085483c2f5815cb69c5cbd31cf92bcd246ea72c2f343a
+  data.tar.gz: 1210463f030fe15c691b0d136498327ae9a83128b5f871a256401bd498ebfd4117391d250ee49a1ab53c1f5f4fd427db292755bc792ea73a99435535bb79d115

data/.github/workflows/ci.yml

@@ -14,7 +14,7 @@ permissions:
   contents: read
 
 jobs:
-  specs:
+  tests:
     timeout-minutes: 15
     runs-on: ubuntu-latest
     strategy:
@@ -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@09a7688d3b55cf0e976497ff046b70949eeaccfd # v1.288.0
+        uses: ruby/setup-ruby@c515ec17f69368147deb311832da000dd229d338 # v1.297.0
         with:
           ruby-version: ${{matrix.ruby}}
           bundler: 'latest'
@@ -69,9 +69,9 @@ jobs:
         with:
           fetch-depth: 0
       - name: Set up Ruby
-        uses: ruby/setup-ruby@09a7688d3b55cf0e976497ff046b70949eeaccfd # v1.288.0
+        uses: ruby/setup-ruby@c515ec17f69368147deb311832da000dd229d338 # v1.297.0
         with:
-          ruby-version: '4.0.1'
+          ruby-version: '4.0.2'
           bundler-cache: true
       - name: Run rubocop
         run: bundle exec rubocop
@@ -86,9 +86,9 @@ jobs:
         with:
           fetch-depth: 0
       - name: Set up Ruby
-        uses: ruby/setup-ruby@09a7688d3b55cf0e976497ff046b70949eeaccfd # v1.288.0
+        uses: ruby/setup-ruby@c515ec17f69368147deb311832da000dd229d338 # v1.297.0
         with:
-          ruby-version: '4.0.1'
+          ruby-version: '4.0.2'
           bundler-cache: true
       - name: Run yard-lint
         run: bundle exec yard-lint lib/
@@ -101,7 +101,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: Set up Node.js
-        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version: '20'
           cache: 'npm'
@@ -116,7 +116,7 @@ jobs:
     if: always()
     needs:
       - rubocop
-      - specs
+      - tests
       - yard-lint
       - lostconf
     steps:

data/.github/workflows/push.yml

@@ -24,7 +24,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@09a7688d3b55cf0e976497ff046b70949eeaccfd # v1.288.0
+        uses: ruby/setup-ruby@c515ec17f69368147deb311832da000dd229d338 # v1.297.0
         with:
           bundler-cache: false
 
@@ -32,4 +32,4 @@ jobs:
         run: |
           bundle install --jobs 4 --retry 3
 
-      - uses: rubygems/release-gem@1c162a739e8b4cb21a676e97b087e8268d8fc40b # v1.1.2
+      - uses: rubygems/release-gem@e9a6361a0b14562539327c2a02373edc56dd3169 # v1.1.4

data/.ruby-version

@@ -1 +1 @@
-4.0.1
+4.0.2

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Karafka Core Changelog
 
+## 2.5.12 (2026-04-02)
+- [Fix] Exclude `test/` directory from gem releases to reduce package size.
+
+## 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] 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] Store execution time separately in `Event` and build the merged payload hash lazily on `#payload` access, eliminating 1 Hash allocation per `Notifications#instrument` call when listeners use `#[]` access (the common pattern), yielding ~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] 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.
+
 ## 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.5.10)
+    karafka-core (2.5.12)
       karafka-rdkafka (>= 0.20.0)
       logger (>= 1.6.0)
 

data/karafka-core.gemspec

@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ">= 3.2.0"
 
-  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec)/}) }
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test)/}) }
   spec.require_paths = %w[lib]
 
   spec.metadata = {

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

@@ -17,14 +17,16 @@ module Karafka
 
         # @param node_name [Symbol] node name
         # @param nestings [Proc] block for nested settings
-        def initialize(node_name, nestings = ->(_) {})
+        # @param evaluate [Boolean] when false, skip evaluating the nestings block. Used by
+        #   deep_dup to avoid re-creating children that will be overwritten immediately.
+        def initialize(node_name, nestings = ->(_) {}, evaluate: true)
           @node_name = node_name
           @children = []
           @nestings = nestings
           @compiled = false
           @configs_refs = {}
-          @local_defs = []
-          instance_eval(&nestings)
+          @local_defs = {}
+          instance_eval(&nestings) if evaluate
         end
 
         # Allows for a single leaf or nested node definition
@@ -83,7 +85,7 @@ module Karafka
         # and non-side-effect usage on an instance/inherited.
         # @return [Node] duplicated node
         def deep_dup
-          dupped = Node.new(node_name, nestings)
+          dupped = Node.new(node_name, nestings, evaluate: false)
 
           children.each do |value|
             dupped.children << if value.is_a?(Leaf)
@@ -189,8 +191,8 @@ module Karafka
           # object and then we would not redefine it for nodes. This ensures that we only do not
           # redefine our own definitions but we do redefine any user "accidentally" inherited
           # methods
-          if reader_respond ? !@local_defs.include?(reader_name) : true
-            @local_defs << reader_name
+          if reader_respond ? !@local_defs.key?(reader_name) : true
+            @local_defs[reader_name] = true
 
             define_singleton_method(reader_name) do
               @configs_refs[reader_name]

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

@@ -14,7 +14,12 @@ module Karafka
         # prevent additional array allocation
         DIG_MISS = Object.new
 
-        private_constant :DIG_MISS
+        # Empty array for scope default to avoid allocating a new Array on each
+        # `#call` / `#validate!` invocation. Safe because scope is never mutated – it is only
+        # used in `scope + rule.path` which creates a new Array.
+        EMPTY_ARRAY = [].freeze
+
+        private_constant :DIG_MISS, :EMPTY_ARRAY
 
         # Yaml based error messages data
         setting(:error_messages)
@@ -80,7 +85,7 @@ module Karafka
         # @param scope [Array<String>] scope of this contract (if any) or empty array if no parent
         #   scope is needed if contract starts from root
         # @return [Result] validaton result
-        def call(data, scope: [])
+        def call(data, scope: EMPTY_ARRAY)
           errors = []
 
           self.class.rules.each do |rule|
@@ -94,6 +99,8 @@ module Karafka
             end
           end
 
+          return Result.success if errors.empty?
+
           Result.new(errors, self)
         end
 
@@ -104,7 +111,7 @@ module Karafka
         # @return [Boolean] true
         # @raise [StandardError] any error provided in the error_class that inherits from the
         #   standard error
-        def validate!(data, error_class, scope: [])
+        def validate!(data, error_class, scope: EMPTY_ARRAY)
           result = call(data, scope: scope)
 
           return true if result.success?
@@ -183,15 +190,34 @@ module Karafka
         # @param keys [Array<Symbol>]
         # @return [DIG_MISS, Object] found element or DIGG_MISS indicating that not found
         def dig(data, keys)
-          current = data
+          case keys.length
+          when 1
+            key = keys[0]
 
-          keys.each do |nesting|
-            return DIG_MISS unless current.key?(nesting)
+            return DIG_MISS unless data.key?(key)
 
-            current = current[nesting]
-          end
+            data[key]
+          when 2
+            key1 = keys[0]
+
+            return DIG_MISS unless data.key?(key1)
+
+            mid = data[key1]
+
+            return DIG_MISS unless mid.is_a?(Hash) && mid.key?(keys[1])
 
-          current
+            mid[keys[1]]
+          else
+            current = data
+
+            keys.each do |nesting|
+              return DIG_MISS unless current.key?(nesting)
+
+              current = current[nesting]
+            end
+
+            current
+          end
         end
       end
     end

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

@@ -12,6 +12,15 @@ module Karafka
 
         private_constant :EMPTY_HASH
 
+        class << self
+          # @return [Result] cached frozen success result to avoid allocating a new Result on
+          #   every successful contract validation. Safe because successful results are
+          #   identical regardless of contract (they all have @errors = EMPTY_HASH).
+          def success
+            @success ||= new([], nil).freeze
+          end
+        end
+
         # Builds a result object and remaps (if needed) error keys to proper error messages
         #
         # @param errors [Array<Array>] array with sub-arrays with paths and error keys

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

@@ -10,6 +10,7 @@ module Karafka
         # @return [::Karafka::Core::Instrumentation::CallbacksManager]
         def initialize
           @callbacks = {}
+          @values_cache = nil
         end
 
         # Invokes all the callbacks registered one after another
@@ -19,8 +20,10 @@ module Karafka
         #   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.
         def call(*args)
-          @callbacks.values.each { |callback| callback.call(*args) }
+          (@values_cache ||= @callbacks.values).each { |callback| callback.call(*args) }
         end
 
         # Adds a callback to the manager
@@ -29,12 +32,14 @@ module Karafka
         # @param callable [#call] object that responds to a `#call` method
         def add(id, callable)
           @callbacks[id] = callable
+          @values_cache = nil
         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
         end
       end
     end

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

@@ -5,20 +5,37 @@ module Karafka
     module Monitoring
       # Single notification event wrapping payload with id
       class Event
-        attr_reader :id, :payload
+        attr_reader :id
 
         # @param id [String, Symbol] id of the event
         # @param payload [Hash] event payload
-        def initialize(id, payload)
+        # @param time [Float, nil] execution time, stored separately to avoid eager hash
+        #   allocation. Merged into the payload lazily only when `#payload` is accessed.
+        def initialize(id, payload, time = nil)
           @id = id
-          @payload = payload
+          @raw_payload = payload
+          @time = time
+          @payload = nil
+        end
+
+        # @return [Hash] full payload including time (if set). The merged hash is built lazily
+        #   on first access to avoid allocating a new Hash when listeners only use `#[]`.
+        def payload
+          @payload ||= if @time
+            @raw_payload.empty? ? { time: @time } : @raw_payload.merge(time: @time)
+          else
+            @raw_payload
+          end
         end
 
         # Hash access to the payload data (if present)
+        # Provides direct access to time without triggering payload hash construction.
         #
         # @param name [String, Symbol]
         def [](name)
-          @payload.fetch(name)
+          return @time if name == :time && @time
+
+          @raw_payload.fetch(name)
         end
       end
     end

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

@@ -139,36 +139,25 @@ module Karafka
             return
           end
 
-          final_payload = build_payload(payload, time)
-          event = Event.new(event_id, final_payload)
+          event = Event.new(event_id, payload, time)
 
-          notify_listeners(event_id, event, assigned_listeners)
+          notify_listeners(@events_methods_map[event_id], event, assigned_listeners)
 
           result
         end
 
         private
 
-        # Builds the final payload with time information if available
-        # @param payload [Hash] original payload
-        # @param time [Float, nil] execution time if block was given
-        # @return [Hash] final payload
-        def build_payload(payload, time)
-          return payload unless time
-
-          payload.empty? ? { time: time } : payload.merge(time: time)
-        end
-
         # Notifies all assigned listeners about the event
-        # @param event_id [String]
+        # @param method_name [Symbol] pre-resolved method name for object listeners
         # @param event [Event] event with payload to broadcast to listeners
         # @param assigned_listeners [Array] list of listeners to notify
-        def notify_listeners(event_id, event, assigned_listeners)
+        def notify_listeners(method_name, event, assigned_listeners)
           assigned_listeners.each do |listener|
             if listener.is_a?(Proc)
               listener.call(event)
             else
-              listener.send(@events_methods_map[event_id], event)
+              listener.send(method_name, event)
             end
           end
         end