karafka-core 2.6.3 → 2.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70aa3940193aebd6b4f232950a2b765ee57025aea6b3d3d7c72234429f904de4
-  data.tar.gz: e4a550006b517eea864370ef12534dacdb6fddae40f3adf7308981fa99a1e7a1
+  metadata.gz: b7064756fbbf13ddd1048da55f30969b2ae10d58442b9a4ec8c8b5250a260473
+  data.tar.gz: 9d6fbe9c4257ce42e03017333602354265c6fa408e585099c6c515d3523c368d
 SHA512:
-  metadata.gz: '05908e99fd999ee007bcb3efd46a6a3b949d88e40d980c5ca4e8aa90a3c312755717dc8feef7a7de42c5c7c235e3ac623e26b91e9a3456568e4d552a2d8782ea'
-  data.tar.gz: 61456523b5822db6c78ad36c839ed6e3bdcbd9bc18d56cebfb95947443296aad94b917b3bef7798f093b471d703ae9d5a7f43d1b09d726ea655e0b2a0b091a3c
+  metadata.gz: 4889fd25e48a9f06adfe9797862aa7d52dd6f363cb95839bf31e4bf66b499db9210331d1d5302f9bdf8d221c9895e68dcc58b8aec07b52004c21e7796779ed48
+  data.tar.gz: b154d18d6feeefac2e715d21c0f63c7e5841c145f5f13dbd588386d7dbd54cc0187c2640a1034679b806db66dc6e19ffb8bf5007ca44c914a0e69abb8758f356

data/CHANGELOG.md

@@ -1,36 +1,39 @@
 # Karafka Core Changelog
 
+## 2.6.4 (2026-09-11)
+- [Enhancement] Add `Configurable::Importer`, a subclassable base for injecting memoized config readers into a class. A subclass names the config root once by overriding `.root`, and each use site then names only the attributes it wants. Supports both `include` and `extend`.
+
 ## 2.6.3 (2026-08-31)
 - [Enhancement] Add `Configurable::Injector`, a reusable base for injecting default values into a config hash without overwriting user-provided settings, with support for layering extra defaults on top.
 
 ## 2.6.2 (2026-06-29)
 - [Enhancement] Document that a leaf's `default` value is shared by reference across all config instances, so a mutable default (e.g. `default: []`) mutated in place is visible everywhere. Assign it inside a `configure` block if you need a per-instance copy.
-- [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`.
+- [Fix] `require "pathname"` explicitly in `lib/karafka-core.rb`. `Karafka::Core.gem_root` returns a `Pathname` but the gem never required it, so `gem_root` raised `NameError` wherever nothing else happened to load it first.
 - [Enhancement] Document that a `virtual` rule must return a freshly built `Array` of `[path, message]` error pairs on each call; a memoized, shared or frozen array is unsupported.
-- [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] `Configurable::Node#register` now raises the documented "already registered" `ArgumentError` for a name used by an unread lazy-with-constructor setting, which it previously overwrote silently.
 - [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] Honor `excluded_keys` containing `"cgrp"` in `StatisticsDecorator` `only_keys` mode; the `cgrp` branch lacked the exclusion guard its `brokers` and `topics` siblings have.
+- [Fix] Guard the patched rdkafka error callback against a null client pointer, which librdkafka can pass early in client construction and which could segfault the process.
+- [Fix] Resolve fatal errors in the patched rdkafka error callback via `RdkafkaError.build_fatal`, so the real underlying error is reported instead of the generic `ERR__FATAL` marker.
 - [Fix] A lazy setting declared without a constructor (`setting(:x, lazy: true)`) no longer raises when read; it now behaves like a regular setting backed by its 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] Make `CallbacksManager` thread-safe under concurrent `add`/`delete` during dispatch. A callback registered or removed while callbacks were firing could be lost — kept firing after removal, or never fired after being added. librdkafka fires these from a background thread, so it was reachable in practice.
+- [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; only an `Array` of error pairs is collected.
+- [Fix] Make `CallbacksManager` thread-safe under concurrent `add`/`delete` during dispatch, so a callback registered or removed while callbacks were firing is no longer lost.
 - [Fix] Make `Notifications` subscriptions thread-safe: a listener that unsubscribes itself (or another) from within its own handler no longer causes the next listener to be skipped, and concurrent subscribe/unsubscribe during dispatch is now safe.
 - [Fix] Report a freeze duration (`_fd`) of `0` for statistics keys that first appear mid-stream (e.g. a new broker or partition) instead of the time since the previous emission, which was incorrect and made the related spec flaky.
-- [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] Make assigning a setting on a frozen `Configurable::Node` atomic; it previously mutated the canonical store before raising `FrozenError`, leaving the store and the reader permanently out of sync.
 - [Fix] `Configurable::Node#to_h` no longer raises for a setting using the `->(default) { ... }` constructor form when its value has not been set yet (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.
+- [Fix] Strip the tests/specs root directory as an anchored prefix instead of a global `gsub` in `MinitestLocator` and `RSpecLocator`, which corrupted the derived subject path when the root string recurred later in it.
 
 ## 2.6.1 (2026-06-15)
 - [Enhancement] Speed up `Contract#call` by ~1.25–1.4x, 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.
+- [Change] Reject reserved setting names with an `ArgumentError` in `Configurable::Node#setting` and `#register` (internal state names and the node public API names). Such names previously shadowed the node's own accessors and could corrupt its internal state.
 - [Enhancement] Speed up `Monitor#instrument` dispatch (~1.2x) on the common no-subscribers path.
 - [Enhancement] Speed up `Configurable::Node` settings reads (~1.4x flat, ~1.6x nested) on hot paths.
-- [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).
+- [Enhancement] Instantiate each `Configurable::Node` through a per-layout anonymous subclass so ivar-backed settings do not grow object shape variations on the shared `Node` class. `deep_dup` reuses the template's subclass.
+- [Fix] Symbolize setting names at definition time and on config store writes, so `String` setting names work end to end and cannot corrupt node internal state when they match reserved internal names.
 - [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).
 
@@ -55,7 +58,7 @@
 - [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.
+- [Enhancement] Support an `only_keys` option in `StatisticsDecorator` to decorate only specified numeric keys. Combined with `excluded_keys`, this cuts decoration cost from ~80ms to ~8.5ms per call on large clusters (10 brokers, 20 topics, 2000 partitions).
 - [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)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    karafka-core (2.6.3)
+    karafka-core (2.6.4)
       karafka-rdkafka (>= 0.20.0)
       logger (>= 1.6.0)
 
@@ -22,7 +22,7 @@ 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.8.2)
+    io-console (0.9.2)
     json (2.21.2)
     karafka-rdkafka (0.28.0)
       ffi (~> 1.17.1)
@@ -67,7 +67,7 @@ GEM
       prism (~> 1.5)
     prism (1.9.0)
     rake (13.4.2)
-    reline (0.6.3)
+    reline (0.7.0)
       io-console (~> 0.5)
     simplecov (1.1.1)
     warning (1.6.0)

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

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Core
+    module Configurable
+      # Base class for config importers.
+      #
+      # An importer builds memoized config readers on a target, so a class can read a few config
+      # values under short, local names instead of spelling out the full config path at every
+      # call site.
+      #
+      # The config root is not hardcoded and is not passed per use site: it is defined once, by
+      # overriding {root} in a subclass. Each consumer therefore ships one importer subclass
+      # pointing at its own config tree (e.g. `Karafka::App.config` or `Karafka::Web.config`),
+      # and every use site only names the attributes it wants.
+      #
+      # {root} is a method rather than a stored config object, so it is resolved lazily, on the
+      # first read of a given attribute. That matters because importers are typically built while
+      # a class body is being loaded, which is usually before the config itself has been set up.
+      #
+      # Each attribute is memoized per target, so the path is walked only once and every later
+      # read is a plain instance variable lookup. Memoization is `||=`-based, so an attribute
+      # whose configured value is `nil` or `false` is re-read on each call.
+      #
+      # @example Define the importer once, with the root
+      #   module Karafka
+      #     module Web
+      #       module Helpers
+      #         class ConfigImporter < Karafka::Core::Configurable::Importer
+      #           class << self
+      #             def root
+      #               Karafka::Web.config
+      #             end
+      #           end
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      # @example Import instance-level readers
+      #   class LagStats
+      #     include Karafka::Web::Helpers::ConfigImporter.new(
+      #       skew_threshold: %i[ui health lags skew_threshold]
+      #     )
+      #
+      #     def skewed?(lag)
+      #       lag > skew_threshold
+      #     end
+      #   end
+      #
+      # @example Import class-level readers
+      #   class Message
+      #     extend Karafka::Web::Helpers::ConfigImporter.new(per_page: %i[ui per_page])
+      #   end
+      #
+      #   Message.per_page
+      #
+      # @example Import the whole config root under `#config` (the default)
+      #   class Consumer
+      #     include Karafka::Web::Helpers::ConfigImporter.new
+      #   end
+      #
+      # @note The base class defines no root of its own; it is not useful directly and is expected
+      #   to be subclassed. Reading an attribute off an importer whose class defines no {root}
+      #   raises `NotImplementedError`.
+      #
+      # @note The readers are defined directly on the target, so an attribute name that collides
+      #   with an existing method silently replaces it.
+      class Importer < Module
+        # Default attributes map, exposing the whole config root under `#config`.
+        DEFAULT_ATTRIBUTES = { config: %i[itself] }.freeze
+
+        private_constant :DEFAULT_ATTRIBUTES
+
+        class << self
+          # @return [Object] config root the attribute paths are resolved against. Override in
+          #   subclasses; the base class defines none. Called on each memoization miss rather
+          #   than when the importer is built, so it may safely reference a config that does not
+          #   exist yet at load time.
+          # @raise [NotImplementedError] when called on a class that does not define a root
+          def root
+            raise(
+              NotImplementedError,
+              "Define .root in a Karafka::Core::Configurable::Importer subclass"
+            )
+          end
+        end
+
+        # @param attributes [Hash{Symbol => Array<Symbol>}] map defining what to import. The key
+        #   is the name the reader will be available under and the value is the path to the
+        #   attribute, relative to the root, as an array of message names.
+        def initialize(attributes = DEFAULT_ATTRIBUTES)
+          super()
+          @attributes = attributes
+        end
+
+        # @return [Object] config root this importer resolves against, as defined by its class
+        def root
+          self.class.root
+        end
+
+        # Defines the readers as instance methods on the target.
+        #
+        # @param model [Object] object to which we want to add the config fetchers
+        # @return [void]
+        def included(model)
+          super
+
+          define_readers(model, :define_method)
+        end
+
+        # Defines the readers as class-level methods on the target.
+        #
+        # @param model [Object] object to which we want to add the config fetchers on a class
+        #   level
+        # @return [void]
+        def extended(model)
+          super
+
+          define_readers(model, :define_singleton_method)
+        end
+
+        private
+
+        # Defines one memoized reader per configured attribute on the target.
+        #
+        # @param model [Object] object the readers are defined on
+        # @param definer [Symbol] method used to define them, either `:define_method` for
+        #   instance-level readers or `:define_singleton_method` for class-level ones
+        # @return [void]
+        def define_readers(model, definer)
+          importer = self
+
+          @attributes.each do |name, path|
+            ivar = :"@#{name}"
+
+            model.public_send(definer, name) do
+              instance_variable_get(ivar) || instance_variable_set(
+                ivar,
+                path.reduce(importer.root) { |node, part| node.public_send(part) }
+              )
+            end
+          end
+        end
+      end
+    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.3"
+    VERSION = "2.6.4"
   end
 end

data/lib/karafka-core.rb

@@ -16,6 +16,7 @@ require "karafka/core/configurable"
 require "karafka/core/configurable/leaf"
 require "karafka/core/configurable/node"
 require "karafka/core/configurable/injector"
+require "karafka/core/configurable/importer"
 require "karafka/core/contractable/contract"
 require "karafka/core/contractable/result"
 require "karafka/core/contractable/rule"

data/package-lock.json

@@ -103,9 +103,9 @@
       }
     },
     "node_modules/fastq": {
-      "version": "1.20.1",
-      "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.20.1.tgz",
-      "integrity": "sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw==",
+      "version": "1.20.2",
+      "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.20.2.tgz",
+      "integrity": "sha512-UpGiiODyCGprM8EPP6JodP6jC9Rws6TCuiDOD+nn0CJhR8guI3g/ozo4ugL0vJ+Yz1UtJuuRPqvQuybVOF1VQA==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -286,9 +286,9 @@
       }
     },
     "node_modules/smol-toml": {
-      "version": "1.7.1",
-      "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.7.1.tgz",
-      "integrity": "sha512-PPlsspAZ4jbMBu5DMFhfUGDQLu/vrL4SyBROVS37x8ynnVmFIs1VPBz1Co8Xks3TvpIaZXmU85y4DrQ+UyVFoQ==",
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.8.0.tgz",
+      "integrity": "sha512-kCZr2V3ch9i00x8zXRhjUNVcjG9ijES5dDudkXvUVCT5QlJNQWElSJdZqyPemffHoLNUYwOcou0Fy+ojN0uHSQ==",
       "dev": true,
       "license": "BSD-3-Clause",
       "engines": {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: karafka-core
 version: !ruby/object:Gem::Version
-  version: 2.6.3
+  version: 2.6.4
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -72,6 +72,7 @@ files:
 - lib/karafka-core.rb
 - lib/karafka/core.rb
 - lib/karafka/core/configurable.rb
+- lib/karafka/core/configurable/importer.rb
 - lib/karafka/core/configurable/injector.rb
 - lib/karafka/core/configurable/leaf.rb
 - lib/karafka/core/configurable/node.rb