karafka-core 2.6.2 → 2.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5f044e02de2bc5b5e41fb033c9e4f0a4e66f45890615053d3c1fe1c33ec8058
-  data.tar.gz: 5ad2604a98478db69950c2a94064dcd20d6ceafa6d3eab03d907700b6cadf3eb
+  metadata.gz: b7064756fbbf13ddd1048da55f30969b2ae10d58442b9a4ec8c8b5250a260473
+  data.tar.gz: 9d6fbe9c4257ce42e03017333602354265c6fa408e585099c6c515d3523c368d
 SHA512:
-  metadata.gz: 0cd334edd644f023a15d87bd35cfe535ca0edcddb39f37630c283801bed26821f3cfa6bfcb478bdd987fae0a549bbdbda56cb4258430f8f676636c368afcddcc
-  data.tar.gz: 44a3eba562af3a0315391f362b28684c54f543110f6f76dd6e99e576655c749866a737f1235cf1971992c0274ed3a1da21db3cf83b07cc83ec28e76ef8d17424
+  metadata.gz: 4889fd25e48a9f06adfe9797862aa7d52dd6f363cb95839bf31e4bf66b499db9210331d1d5302f9bdf8d221c9895e68dcc58b8aec07b52004c21e7796779ed48
+  data.tar.gz: b154d18d6feeefac2e715d21c0f63c7e5841c145f5f13dbd588386d7dbd54cc0187c2640a1034679b806db66dc6e19ffb8bf5007ca44c914a0e69abb8758f356

data/.github/workflows/ci.yml

@@ -29,7 +29,7 @@ jobs:
           - ruby: '4.0'
             coverage: 'true'
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         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@9eb537ca036ebaed86729dcb9309076e4c5c3b74 # v1.314.0
+        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
         with:
           ruby-version: ${{matrix.ruby}}
           bundler: 'latest'
@@ -65,13 +65,13 @@ jobs:
     env:
       BUNDLE_GEMFILE: Gemfile.lint
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
       - name: Set up Ruby
-        uses: ruby/setup-ruby@9eb537ca036ebaed86729dcb9309076e4c5c3b74 # v1.314.0
+        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
         with:
-          ruby-version: '4.0.5'
+          ruby-version: '4.0.6'
           bundler-cache: true
       - name: Run rubocop
         run: bundle exec rubocop
@@ -82,13 +82,13 @@ jobs:
     env:
       BUNDLE_GEMFILE: Gemfile.lint
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
       - name: Set up Ruby
-        uses: ruby/setup-ruby@9eb537ca036ebaed86729dcb9309076e4c5c3b74 # v1.314.0
+        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
         with:
-          ruby-version: '4.0.5'
+          ruby-version: '4.0.6'
           bundler-cache: true
       - name: Run yard-lint
         run: bundle exec yard-lint lib/
@@ -97,11 +97,11 @@ jobs:
     timeout-minutes: 5
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
       - name: Set up Node.js
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: '20'
           cache: 'npm'

data/.github/workflows/push.yml

@@ -19,12 +19,12 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@9eb537ca036ebaed86729dcb9309076e4c5c3b74 # v1.314.0
+        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
         with:
           bundler-cache: false
 
@@ -32,4 +32,4 @@ jobs:
         run: |
           bundle install --jobs 4 --retry 3
 
-      - uses: rubygems/release-gem@052cc82692552de3ef2b81fd670e41d13cba8092 # v1.4.0
+      - uses: rubygems/release-gem@7f9650160c1a4e7989fdc9855807bdbd421d8b6b # v1.4.1

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

@@ -7,7 +7,7 @@ jobs:
   verify_action_pins:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - 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/.gitignore

@@ -19,6 +19,7 @@ db/*.sqlite3
 *.rbc
 *.sassc
 .byebug_history
+.claude/
 .redcar/
 .capistrano/
 .sass-cache

data/.ruby-version

@@ -1 +1 @@
-4.0.5
+4.0.6

data/.yard-lint.yml

@@ -62,6 +62,34 @@ Documentation/BlankLineBeforeDefinition:
     SingleBlankLine: true
     OrphanedDocs: true
 
+Documentation/DuplicateNamespaceComment:
+  Description: Detects namespaces documented with a YARD comment in more than one file.
+  Enabled: true
+  Severity: error
+
+Documentation/UnderfilledLines:
+  Description: Detects documentation prose that wraps too early and wastes horizontal space.
+  Enabled: true
+  Severity: error
+  # Aligned with RuboCop's Layout/LineLength (Max: 100) so documentation prose
+  # wraps to the same width as code.
+  MaxLength: 100
+
+Documentation/LineLength:
+  Description: Detects documentation lines that exceed the maximum length.
+  Enabled: true
+  Severity: error
+  # Aligned with RuboCop's Layout/LineLength (Max: 100).
+  MaxLength: 100
+
+Documentation/TextSubstitution:
+  Description: Detects em/en-dashes in documentation and replaces them with hyphens.
+  Enabled: true
+  Severity: error
+  Substitutions:
+    "—": "-"    # em-dash (U+2014)
+    "–": "-"    # en-dash (U+2013)
+
 # Tags validators
 Tags/Order:
   Description: Enforces consistent ordering of YARD tags.
@@ -142,7 +170,7 @@ Tags/OptionTags:
 Tags/ExampleSyntax:
   Description: Validates Ruby syntax in @example tags.
   Enabled: true
-  Severity: warning
+  Severity: error
 
 Tags/RedundantParamDescription:
   Description: Detects meaningless parameter descriptions that add no value.

data/CHANGELOG.md

@@ -1,33 +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 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.
+- [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`. `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` 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] 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` 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; 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; 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.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.
+- [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.
-- [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] 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 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).
 
@@ -52,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.lint.lock

@@ -55,11 +55,11 @@ GEM
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
-    yard (0.9.38)
-    yard-lint (1.4.0)
+    yard (0.9.45)
+    yard-lint (1.10.1)
       yard (~> 0.9)
       zeitwerk (~> 2.6)
-    zeitwerk (2.7.4)
+    zeitwerk (2.8.2)
 
 PLATFORMS
   ruby
@@ -75,6 +75,7 @@ DEPENDENCIES
 
 CHECKSUMS
   ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
+  bundler (4.0.17) sha256=214e21431b5665dd2f99df8a5511c6b151d7a72e8015c8b38f8b775b61cbb6c1
   json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
   language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
@@ -95,9 +96,9 @@ CHECKSUMS
   standard-performance (1.9.0) sha256=49483d31be448292951d80e5e67cdcb576c2502103c7b40aec6f1b6e9c88e3f2
   unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
   unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
-  yard (0.9.38) sha256=721fb82afb10532aa49860655f6cc2eaa7130889df291b052e1e6b268283010f
-  yard-lint (1.4.0) sha256=7dd88fbb08fd77cb840bea899d58812817b36d92291b5693dd0eeb3af9f91f0f
-  zeitwerk (2.7.4) sha256=2bef90f356bdafe9a6c2bd32bcd804f83a4f9b8bc27f3600fff051eb3edcec8b
+  yard (0.9.45) sha256=52e211493f7cb8a3ebf7e104a25a1e73937a3103092545d34cb88fafebb3dc51
+  yard-lint (1.10.1) sha256=172ea1905304580bd515c093d82831ec4889e725100c49d5bf77e62101f49129
+  zeitwerk (2.8.2) sha256=7212a61311083c604184b1ea2574b9aa05cd14f855a0841c06985cabe9181d12
 
 BUNDLED WITH
-  4.0.3
+  4.0.17

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    karafka-core (2.6.2)
+    karafka-core (2.6.4)
       karafka-rdkafka (>= 0.20.0)
       logger (>= 1.6.0)
 
@@ -10,7 +10,6 @@ GEM
   specs:
     byebug (13.0.0)
       reline (>= 0.6.0)
-    docile (1.4.1)
     drb (2.2.3)
     ffi (1.17.4)
     ffi (1.17.4-aarch64-linux-gnu)
@@ -23,39 +22,39 @@ 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)
-    json (2.19.7)
-    karafka-rdkafka (0.27.2)
+    io-console (0.9.2)
+    json (2.21.2)
+    karafka-rdkafka (0.28.0)
       ffi (~> 1.17.1)
       json (> 2.0)
       logger
       mini_portile2 (~> 2.6)
       rake (> 12)
-    karafka-rdkafka (0.27.2-aarch64-linux-gnu)
+    karafka-rdkafka (0.28.0-aarch64-linux-gnu)
       ffi (~> 1.17.1)
       json (> 2.0)
       logger
       mini_portile2 (~> 2.6)
       rake (> 12)
-    karafka-rdkafka (0.27.2-aarch64-linux-musl)
+    karafka-rdkafka (0.28.0-aarch64-linux-musl)
       ffi (~> 1.17.1)
       json (> 2.0)
       logger
       mini_portile2 (~> 2.6)
       rake (> 12)
-    karafka-rdkafka (0.27.2-arm64-darwin)
+    karafka-rdkafka (0.28.0-arm64-darwin)
       ffi (~> 1.17.1)
       json (> 2.0)
       logger
       mini_portile2 (~> 2.6)
       rake (> 12)
-    karafka-rdkafka (0.27.2-x86_64-linux-gnu)
+    karafka-rdkafka (0.28.0-x86_64-linux-gnu)
       ffi (~> 1.17.1)
       json (> 2.0)
       logger
       mini_portile2 (~> 2.6)
       rake (> 12)
-    karafka-rdkafka (0.27.2-x86_64-linux-musl)
+    karafka-rdkafka (0.28.0-x86_64-linux-musl)
       ffi (~> 1.17.1)
       json (> 2.0)
       logger
@@ -68,14 +67,9 @@ 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 (0.22.0)
-      docile (~> 1.1)
-      simplecov-html (~> 0.11)
-      simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.2)
-    simplecov_json_formatter (0.1.4)
+    simplecov (1.1.1)
     warning (1.6.0)
 
 PLATFORMS

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/configurable/injector.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Core
+    module Configurable
+      # Base class for config defaults injectors.
+      #
+      # An injector enriches a config-like hash with a set of default values, applying each
+      # default only when the corresponding key is not already present. This lets a component
+      # ship sane defaults while still letting users override any of them by pre-populating the
+      # key themselves.
+      #
+      # Injectors are meant to be layered. A base (e.g. OSS) injector defines its {defaults} and
+      # an extension (e.g. Pro) prepends a module onto the singleton class and calls `super` to
+      # contribute additional defaults on top:
+      #
+      #   Base.singleton_class.prepend(Extension)
+      #
+      # The only-if-absent rule applies to the target being enriched, not to the defaults
+      # themselves: a key the user already set in the target is never touched. How two layers
+      # resolve a key they both define is up to the layers -- e.g. an extension using
+      # `super.merge(extra)` lets its own value win, while `extra.merge(super)` would keep the
+      # base value.
+      #
+      # @example Define an injector with defaults
+      #   class MyInjector < Karafka::Core::Configurable::Injector
+      #     DEFAULTS = { 'a' => 1, 'b' => 2 }.freeze
+      #
+      #     class << self
+      #       def defaults
+      #         DEFAULTS
+      #       end
+      #     end
+      #   end
+      #
+      #   MyInjector.call({ 'b' => 20 }) #=> { 'b' => 20, 'a' => 1 }
+      #
+      # @example Layer extra defaults (e.g. Pro) via prepend + super
+      #   module ProDefaults
+      #     def defaults
+      #       super.merge('c' => 3)
+      #     end
+      #   end
+      #
+      #   MyInjector.singleton_class.prepend(ProDefaults)
+      #   MyInjector.call({}) #=> { 'a' => 1, 'b' => 2, 'c' => 3 }
+      #
+      # @note The base class holds no state and defines no defaults on its own; it is not useful
+      #   directly and is expected to be subclassed. Subclasses should return the same defaults
+      #   object (e.g. a frozen constant) on each call so that a prepended layer doing
+      #   `super.merge(...)` never mutates it.
+      #
+      # @note Default values are injected by reference, not copied. A mutable default (an array or
+      #   hash) is therefore shared across every target it is injected into, and mutating it in one
+      #   place is visible everywhere. When a per-target mutable value is needed, the defaults
+      #   layer should hand out a copy (e.g. `dup` it in `.defaults`).
+      class Injector
+        # Empty, immutable defaults used by the base class, which defines none of its own.
+        EMPTY_DEFAULTS = {}.freeze
+
+        private_constant :EMPTY_DEFAULTS
+
+        class << self
+          # Enriches the target with the defaults, without overwriting any key that is already
+          # present in it. The target is mutated in place.
+          #
+          # @param target [Hash] config hash to enrich in place
+          # @return [Hash] the same target, enriched with the missing defaults
+          def call(target)
+            defaults.each do |key, value|
+              next if target.key?(key)
+
+              target[key] = value
+            end
+
+            target
+          end
+
+          # @return [Hash] default values to inject. Override in subclasses; extensions may
+          #   prepend a module onto the singleton class and call `super` to contribute additional
+          #   defaults on top. The base class defines none.
+          def defaults
+            EMPTY_DEFAULTS
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,8 +3,7 @@
 module Karafka
   module Core
     module Configurable
-      # Single non-leaf node
-      # This is a core component for the configurable settings
+      # Single non-leaf node. This is a core component for the configurable settings
       #
       # The idea here is simple: we collect settings (leafs) and children (nodes) information and
       # we only compile/initialize the values prior to user running the `#configure` API. This API

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

@@ -24,7 +24,7 @@ module Karafka
           this = self
           # Allows "auto subject" definitions for the `describe` method, as it will figure
           # out the proper class that we want to describe
-          # @param block [Proc] block with tests
+          # block - block with tests
           minitest_module.define_singleton_method :describe_current do |&block|
             describe(this.inherited, &block)
           end

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

@@ -27,7 +27,7 @@ module Karafka
           this = self
           # Allows "auto subject" definitions for the `#describe` method, as it will figure
           # out the proper class that we want to describe
-          # @param block [Proc] block with specs
+          # block - block with specs
           rspec.define_singleton_method :describe_current do |&block|
             describe(this.inherited, &block)
           end

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

@@ -2,7 +2,6 @@
 
 module Karafka
   module Core
-    # Karafka instrumentation related shared components
     module Instrumentation
       # This manager allows us to register multiple callbacks into a hook that is suppose to support
       # a single callback

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

@@ -100,8 +100,8 @@ module Karafka
           end
         end
 
-        # Allows for unsubscription from events
-        # This method will remove the listener/block from all events where it's currently subscribed.
+        # Allows for unsubscription from events. This method will remove the listener/block from all
+        # events where it's currently subscribed.
         #
         # @param listener_or_block [Object] listener object or block to remove from all events
         #

data/lib/karafka/core/monitoring.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-# Main module namespace
 module Karafka
   module Core
     # Monitoring for Karafka and WaterDrop

data/lib/karafka/core/version.rb

@@ -2,8 +2,7 @@
 
 module Karafka
   module Core
-    # Current Karafka::Core version
-    # We follow the versioning schema of given Karafka version
-    VERSION = "2.6.2"
+    # Current Karafka::Core version. We follow the versioning schema of given Karafka version
+    VERSION = "2.6.4"
   end
 end

data/lib/karafka-core.rb

@@ -15,6 +15,8 @@ require "karafka/core/monitoring/statistics_decorator"
 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"
@@ -36,12 +38,12 @@ rd_config = Rdkafka::Config
 
 # Rdkafka uses a single global callback for things. We bypass that by injecting a manager for
 # each callback type. Callback manager allows us to register more than one callback
-# @note Those managers are also used by Karafka for consumer related statistics
+# Those managers are also used by Karafka for consumer related statistics
 rd_config.statistics_callback = instrumentation.statistics_callbacks
 rd_config.error_callback = instrumentation.error_callbacks
 rd_config.oauthbearer_token_refresh_callback = instrumentation.oauthbearer_token_refresh_callbacks
 
 # This loads librdkafka components into memory prior to initializing the client.
 # This mitigates macos forking issues.
-# @see https://github.com/confluentinc/librdkafka/issues/4590
+# See https://github.com/confluentinc/librdkafka/issues/4590
 Rdkafka::Bindings.rd_kafka_global_init if Rdkafka::Bindings.respond_to?(:rd_kafka_global_init)

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.6.1",
-      "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.6.1.tgz",
-      "integrity": "sha512-dWUG8F5sIIARXih1DTaQAX4SsiTXhInKf1buxdY9DIg4ZYPZK5nGM1VRIYmEbDbsHt7USo99xSLFu5Q1IqTmsg==",
+      "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.2
+  version: 2.6.4
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -72,6 +72,8 @@ 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
 - lib/karafka/core/contractable.rb
@@ -120,7 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Karafka ecosystem core modules
 test_files: []