karafka-core 2.6.0 → 2.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2e60176350192fdf31ec49aa111aa1a2cd51e4f7d0785b5d31070422dd07fbd
-  data.tar.gz: 07e237b85c91e7d0886a8c8a91e7d55a8f54aaa59cdd18a1281f1e0cff38357a
+  metadata.gz: 2d9f6ba569f0c3a911cbe3ce80c545f3069b5aa2560782cf88bd11c97baa0432
+  data.tar.gz: 54f274da23e99841809f884ea871ce9a55705d76d3c4e5c40b0ef2ffbe0ae75a
 SHA512:
-  metadata.gz: 52a0a727b505b2f69720aac6be4bc7af9803d347ce9e01f7335a3d58bec4b2e4e6bc4f302c860f6564bcd53a81dbe36e2138e90e81d24bfe11d0c5caee38fa32
-  data.tar.gz: e2b40e1316e748b42301f58a472239458fb4ce34a10b5efe43b436b6aeda70df872df10f2a14fb0d7f851c55fedd045b46bb2e9bb5e896377e2bb2d505e9f5e2
+  metadata.gz: 3a6c6ba64216479cebb2c4f574dff194ae6665189f382b0a60193c5b4ec3ab4d55f4ff97d7fb3fc90800f105a5284da27493b5694adff6e1a6c0738fa5795f65
+  data.tar.gz: 8ea0eddcd9ae95603041f8a74a1a26311cd9aa13744759dd6e7a699eb6ce682fd89596ef85e77ee2fd280d4aa3eca14d8f2ddd7a75dc322fe6e7bb33903ac7b6

data/.github/workflows/ci.yml

@@ -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@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1.310.0
+        uses: ruby/setup-ruby@12fd324f1d0b43274fdc8130f6980590a667c455 # v1.312.0
         with:
           ruby-version: ${{matrix.ruby}}
           bundler: 'latest'
@@ -69,7 +69,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: Set up Ruby
-        uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1.310.0
+        uses: ruby/setup-ruby@12fd324f1d0b43274fdc8130f6980590a667c455 # v1.312.0
         with:
           ruby-version: '4.0.5'
           bundler-cache: true
@@ -86,7 +86,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: Set up Ruby
-        uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1.310.0
+        uses: ruby/setup-ruby@12fd324f1d0b43274fdc8130f6980590a667c455 # v1.312.0
         with:
           ruby-version: '4.0.5'
           bundler-cache: true

data/.github/workflows/push.yml

@@ -24,7 +24,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1.310.0
+        uses: ruby/setup-ruby@12fd324f1d0b43274fdc8130f6980590a667c455 # v1.312.0
         with:
           bundler-cache: false
 

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Karafka Core Changelog
 
+## 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.
+- [Change] Reject reserved setting names with an `ArgumentError` in `Configurable::Node#setting` and `#register`: internal state names (`node_name`, `children`, `nestings`, `compiled`, `configs_refs`, `local_defs`) and the node public API names (`setting`, `configure`, `to_h`, `deep_dup`, `register`, `compile`). Previously such names silently shadowed the node own accessors, breaking `deep_dup` or `to_h`, and assignments like `config.children = value` corrupted the node internal state.
+- [Enhancement] Skip the event name mapping hash lookup in `Monitor#instrument` when no namespace is used and the event id is already a `String`, which is the case for all events in the Karafka ecosystem (~1.2x faster dispatch on the common no-subscribers path). Symbol event ids and namespaced monitors keep going through the mapping.
+- [Enhancement] Mirror config values into instance variables and use `attr_reader` based readers in `Configurable::Node`, yielding ~1.4x faster flat and ~1.6x faster nested settings reads on hot paths. `@configs_refs` remains the canonical store; non-identifier setting names (e.g. registered names with dashes) keep the previous hash-based accessors.
+- [Enhancement] Instantiate each `Configurable::Node` through a per-layout anonymous subclass so the ivar-backed settings do not grow object shape variations on the shared `Node` class (which would degrade ivar access and trigger Ruby performance warnings). `deep_dup` reuses the template's subclass, so duplicated configs share object shapes.
+- [Fix] Symbolize setting names at definition time (`setting`, same as `register`) and on config store writes so `String` setting names work end to end (accessors, `#to_h`, recompilation state) and cannot corrupt node internal state when matching reserved internal names (previously string-named settings were quietly broken as accessors and the store disagreed on the key type).
+- [Change] Config nodes are now instances of anonymous `Node` subclasses: `is_a?(Karafka::Core::Configurable::Node)` still holds, but `instance_of?(Node)` is now `false` and `node.class.name` is `nil`.
+- [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] Replace version-gated `Warning[:performance]` with a `Warning.categories`-based loop that enables all opt-in Ruby warning categories automatically, picking up new categories (e.g. `strict_unused_block` in Ruby 3.4+) without future patches.

data/Gemfile.lock

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

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

@@ -15,6 +15,49 @@ module Karafka
         # We need to be able to redefine children for deep copy
         attr_accessor :children
 
+        # Names that cannot be used as setting names because they would collide with the node
+        # internal state or the node public API: their accessors would shadow the node own
+        # readers (breaking for example `#deep_dup` or `#to_h`) and writers like `children=`
+        # would overwrite internal ivars. `#setting` and `#register` reject them upfront and
+        # `#ivar_backed?` keeps guarding the ivar mirror as defense in depth.
+        # Private method names are deliberately not reserved: that would make internal
+        # implementation details part of the public contract
+        RESERVED_NAMES = %i[
+          node_name
+          children
+          nestings
+          compiled
+          configs_refs
+          local_defs
+          setting
+          configure
+          to_h
+          deep_dup
+          register
+          compile
+        ].to_h { |name| [name, true] }.freeze
+
+        # Setting names that match this format can be backed by instance variables and use the
+        # fast `attr_reader` based readers. Others (e.g. registered names with dashes) fall back
+        # to the hash-based accessors
+        IVAR_NAMEABLE_FORMAT = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+        private_constant :RESERVED_NAMES, :IVAR_NAMEABLE_FORMAT
+
+        class << self
+          # Builds each node through its own anonymous subclass. Since setting values are
+          # mirrored into instance variables for fast access and each node layout carries a
+          # different set of them, instantiating nodes directly from this class would grow its
+          # object shape variations past the Ruby limit, degrading ivar access for all nodes.
+          # A subclass per layout keeps shape variations per class minimal (late `setting`
+          # calls after inheritance or runtime `register` calls may add a few more, staying
+          # well under the limit). `#deep_dup` reuses the subclass of its template, so
+          # duplicated configs share shapes as well.
+          def new(...)
+            equal?(Node) ? Class.new(self).new(...) : super
+          end
+        end
+
         # @param node_name [Symbol] node name
         # @param nestings [Proc] block for nested settings
         # @param evaluate [Boolean] when false, skip evaluating the nestings block. Used by
@@ -31,12 +74,20 @@ module Karafka
 
         # Allows for a single leaf or nested node definition
         #
-        # @param node_name [Symbol] setting or nested node name
+        # @param node_name [Symbol, String] setting or nested node name
         # @param default [Object] default value
         # @param constructor [#call, nil] callable or nil
         # @param lazy [Boolean] is this a lazy leaf
         # @param block [Proc] block for nested settings
+        # @raise [ArgumentError] when the name is reserved for the node internal state
         def setting(node_name, default: nil, constructor: nil, lazy: false, &block)
+          # Symbolize at definition time (same as `#register`) so the config store, accessors,
+          # `#to_h` and the compile state checks all agree on the key type also when a String
+          # name is provided
+          node_name = node_name.to_sym
+
+          prevent_reserved_names!(node_name)
+
           @children << if block
             Node.new(node_name, block)
           else
@@ -85,7 +136,8 @@ module Karafka
         # and non-side-effect usage on an instance/inherited.
         # @return [Node] duplicated node
         def deep_dup
-          dupped = Node.new(node_name, nestings, evaluate: false)
+          # Same-layout nodes reuse the class of their template so they share object shapes
+          dupped = self.class.new(node_name, nestings, evaluate: false)
 
           children.each do |value|
             dupped.children << if value.is_a?(Leaf)
@@ -116,16 +168,19 @@ module Karafka
         # @param name [Symbol, String] setting name
         # @param value [Object] the setting value assigned immediately; also used as the default
         #   when the node is deep-duped and recompiled on a new instance
-        # @raise [ArgumentError] when the name is already taken
+        # @raise [ArgumentError] when the name is already taken or reserved for the node
+        #   internal state
         def register(name, value)
           name = name.to_sym
 
+          prevent_reserved_names!(name)
+
           raise ArgumentError, "#{name} is already registered" if @configs_refs.key?(name)
 
           leaf = Leaf.new(name, value, nil, true, false)
           @children << leaf
           build_accessors(leaf)
-          @configs_refs[name] = value
+          config_write(name, value)
         end
 
         # Converts the settings definitions into end children
@@ -161,7 +216,7 @@ module Karafka
             if lazy_leaf && !initialized
               build_dynamic_accessor(value)
             else
-              @configs_refs[value.node_name] = initialized
+              config_write(value.node_name, initialized)
             end
           end
 
@@ -207,6 +262,12 @@ module Karafka
 
         # Builds regular accessors for value fetching
         #
+        # Settings with names that can form valid instance variables get `attr_reader` based
+        # readers backed by an ivar mirror of the config value. This is significantly faster
+        # than a method with a hash lookup, which matters since settings are read on hot paths
+        # across the whole ecosystem. `@configs_refs` remains the canonical store used by
+        # `#to_h`, `#compile` and `#register`, with `#config_write` keeping the mirror in sync.
+        #
         # @param value [Leaf]
         def build_accessors(value)
           reader_name = value.node_name.to_sym
@@ -219,17 +280,64 @@ module Karafka
           if reader_respond ? !@local_defs.key?(reader_name) : true
             @local_defs[reader_name] = true
 
-            define_singleton_method(reader_name) do
-              @configs_refs[reader_name]
+            if ivar_backed?(reader_name)
+              singleton_class.attr_reader(reader_name)
+            else
+              define_singleton_method(reader_name) do
+                @configs_refs[reader_name]
+              end
             end
           end
 
-          return if respond_to?(:"#{value.node_name}=")
+          return if respond_to?(:"#{reader_name}=")
 
-          define_singleton_method(:"#{value.node_name}=") do |new_value|
-            @configs_refs[value.node_name] = new_value
+          if ivar_backed?(reader_name)
+            ivar_name = :"@#{reader_name}"
+
+            define_singleton_method(:"#{reader_name}=") do |new_value|
+              instance_variable_set(ivar_name, @configs_refs[reader_name] = new_value)
+            end
+          else
+            define_singleton_method(:"#{reader_name}=") do |new_value|
+              @configs_refs[reader_name] = new_value
+            end
           end
         end
+
+        # Writes a config value to the canonical store and mirrors it into the backing instance
+        # variable when the setting uses the fast ivar-backed reader
+        #
+        # @param name [Symbol, String] setting name
+        # @param value [Object] config value assigned to the setting
+        def config_write(name, value)
+          # Accessors operate on symbolized names, so the store has to be keyed consistently.
+          # This also guarantees that a String name matching a reserved internal name is
+          # recognized by the `ivar_backed?` guard and cannot corrupt the node internal state
+          name = name.to_sym
+
+          @configs_refs[name] = value
+          instance_variable_set(:"@#{name}", value) if ivar_backed?(name)
+        end
+
+        # @param name [Symbol] setting name
+        # @return [Boolean] true if this setting can be backed by an instance variable and use
+        #   the fast `attr_reader` based reader
+        def ivar_backed?(name)
+          !RESERVED_NAMES.key?(name) && IVAR_NAMEABLE_FORMAT.match?(name)
+        end
+
+        # Rejects setting names that would collide with the node internal state. Without this,
+        # such names would shadow the node own accessors, breaking `#deep_dup` and silently
+        # corrupting internals on assignment (e.g. `config.children = value` hitting the node
+        # own `attr_writer`)
+        #
+        # @param name [Symbol] already symbolized setting name
+        # @raise [ArgumentError] when the name is reserved
+        def prevent_reserved_names!(name)
+          return unless RESERVED_NAMES.key?(name)
+
+          raise ArgumentError, "#{name} is a reserved name and cannot be used as a setting name"
+        end
       end
     end
   end

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

@@ -15,7 +15,7 @@ module Karafka
         DIG_MISS = Object.new
 
         # 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
+        # `#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
 
@@ -81,6 +81,12 @@ module Karafka
 
         # Runs the validation
         #
+        # The per-rule handling is inlined instead of dispatching to per-type methods because
+        # this runs per rule per validation, including the per-message validations in
+        # WaterDrop. Required and optional rules share the whole flow except the missing-key
+        # handling. `DIG_MISS` is compared via `#equal?` so we never dispatch `#==` to the
+        # validated (user-provided) values.
+        #
         # @param data [Hash] hash with data we want to validate
         # @param scope [Array<String>] scope of this contract (if any) or empty array if no parent
         #   scope is needed if contract starts from root
@@ -89,13 +95,28 @@ module Karafka
           errors = []
 
           self.class.rules.each do |rule|
-            case rule.type
-            when :required
-              validate_required(data, rule, errors, scope)
-            when :optional
-              validate_optional(data, rule, errors, scope)
-            when :virtual
-              validate_virtual(data, rule, errors, scope)
+            if rule.type == :virtual
+              result = rule.validator.call(data, errors, self)
+
+              next if result == true
+
+              result&.each do |sub_result|
+                sub_result[0] = scope + sub_result[0]
+              end
+
+              errors.push(*result)
+            else
+              for_checking = dig(data, rule.path)
+
+              if DIG_MISS.equal?(for_checking)
+                errors << [scope + rule.path, :missing] if rule.type == :required
+              else
+                result = rule.validator.call(for_checking, data, errors, self)
+
+                next if result == true
+
+                errors << [scope + rule.path, result || :format]
+              end
             end
           end
 
@@ -121,98 +142,39 @@ module Karafka
 
         private
 
-        # Runs validation for rules on fields that are required and adds errors (if any) to the
-        # errors array
-        #
-        # @param data [Hash] input hash
-        # @param rule [Rule] validation rule
-        # @param errors [Array] array with errors from previous rules (if any)
-        # @param scope [Array<String>]
-        def validate_required(data, rule, errors, scope)
-          for_checking = dig(data, rule.path)
-
-          # We need to compare `DIG_MISS` against stuff because of the ownership of the `#==` method
-          if for_checking == DIG_MISS
-            errors << [scope + rule.path, :missing]
-          else
-            result = rule.validator.call(for_checking, data, errors, self)
-
-            return if result == true
-
-            errors << [scope + rule.path, result || :format]
-          end
-        end
-
-        # Runs validation for rules on fields that are optional and adds errors (if any) to the
-        # errors array
-        #
-        # @param data [Hash] input hash
-        # @param rule [Rule] validation rule
-        # @param errors [Array] array with errors from previous rules (if any)
-        # @param scope [Array<String>]
-        def validate_optional(data, rule, errors, scope)
-          for_checking = dig(data, rule.path)
-
-          return if for_checking == DIG_MISS
-
-          result = rule.validator.call(for_checking, data, errors, self)
-
-          return if result == true
-
-          errors << [scope + rule.path, result || :format]
-        end
-
-        # Runs validation for rules on virtual fields (aggregates, etc) and adds errors (if any) to
-        # the errors array
-        #
-        # @param data [Hash] input hash
-        # @param rule [Rule] validation rule
-        # @param errors [Array] array with errors from previous rules (if any)
-        # @param scope [Array<String>]
-        def validate_virtual(data, rule, errors, scope)
-          result = rule.validator.call(data, errors, self)
-
-          return if result == true
-
-          result&.each do |sub_result|
-            sub_result[0] = scope + sub_result[0]
-          end
-
-          errors.push(*result)
-        end
-
         # Tries to dig for a given key in a hash and returns it with indication whether or not it
         # was possible to find it (dig returns nil and we don't know if it wasn't the digged key
         # value)
         #
+        # Uses `Hash#fetch` with the `DIG_MISS` sentinel as the default, which resolves presence
+        # and value in a single hash lookup instead of a `key?` check followed by `[]`. This
+        # runs per rule per validation, including the per-message validations in WaterDrop,
+        # hence the lookup count matters. `fetch` with a default ignores `default_proc`, same
+        # as the previous `key?` based logic.
+        #
         # @param data [Hash]
         # @param keys [Array<Symbol>]
         # @return [DIG_MISS, Object] found element or DIGG_MISS indicating that not found
         def dig(data, keys)
           case keys.length
           when 1
-            key = keys[0]
-
-            return DIG_MISS unless data.key?(key)
-
-            data[key]
+            data.fetch(keys[0], DIG_MISS)
           when 2
-            key1 = keys[0]
-
-            return DIG_MISS unless data.key?(key1)
+            mid = data.fetch(keys[0], DIG_MISS)
 
-            mid = data[key1]
+            return DIG_MISS if DIG_MISS.equal?(mid)
+            return DIG_MISS unless mid.is_a?(Hash)
 
-            return DIG_MISS unless mid.is_a?(Hash) && mid.key?(keys[1])
-
-            mid[keys[1]]
+            mid.fetch(keys[1], DIG_MISS)
           else
             current = data
 
             keys.each do |nesting|
-              return DIG_MISS unless current.key?(nesting)
+              return DIG_MISS unless current.is_a?(Hash)
+
+              current = current.fetch(nesting, DIG_MISS)
 
-              current = current[nesting]
+              return DIG_MISS if DIG_MISS.equal?(current)
             end
 
             current

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

@@ -28,7 +28,15 @@ module Karafka
         # @param event_id [String, Symbol] event id
         # @param payload [Hash]
         def instrument(event_id, payload = EMPTY_HASH, &)
-          full_event_name = @mapped_events[event_id] ||= [event_id, @namespace].compact.join(".")
+          # With no namespace, string event ids already are the full event names. This is the
+          # case for all the events in the Karafka ecosystem, so we can skip the mapping hash
+          # lookup on this hot path. Symbols still go through the mapping to be converted into
+          # strings without allocating on each call.
+          full_event_name = if @namespace.nil? && event_id.is_a?(String)
+            event_id
+          else
+            @mapped_events[event_id] ||= [event_id, @namespace].compact.join(".")
+          end
 
           @notifications_bus.instrument(full_event_name, payload, &)
         end

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.0"
+    VERSION = "2.6.1"
   end
 end

data/renovate.json

@@ -15,7 +15,7 @@
     {
       "minimumReleaseAge": "7 days",
       "matchDepNames": [
-        "/*/"
+        "*"
       ]
     },
     {

metadata

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