karafka 2.5.2 → 2.5.3

data/lib/karafka/setup/config_proxy.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Setup
+    # Configuration proxy that wraps the actual config object during the setup phase.
+    #
+    # ## Purpose
+    #
+    # This proxy exists to intercept specific configuration methods during the setup block
+    # execution, allowing for deferred initialization and special handling of certain
+    # configuration aspects without permanently modifying the config object's API.
+    #
+    # The key design principle is: **the proxy only exists during setup and doesn't pollute
+    # the permanent config API**. Once setup is complete, all access goes directly to the
+    # real config object.
+    #
+    # ## Why Use a Proxy?
+    #
+    # During Karafka setup, there's a specific order of operations:
+    #
+    # 1. User configures basic settings (kafka, client_id, etc.)
+    # 2. Config validation runs
+    # 3. Components are initialized based on finalized config
+    # 4. Post-setup hooks execute
+    #
+    # Some configuration needs to happen **after** user settings but **during** component
+    # initialization. The proxy intercepts these special cases during step 1, stores the
+    # instructions, and applies them during step 3.
+    #
+    # ## Current Use Case: Producer Configuration
+    #
+    # The proxy currently intercepts `producer` calls with blocks:
+    #
+    # ```ruby
+    # Karafka::App.setup do |config|
+    #   config.kafka = { 'bootstrap.servers': 'localhost:9092' }
+    #
+    #   # This is intercepted by the proxy
+    #   config.producer do |producer_config|
+    #     producer_config.kafka['compression.type'] = 'snappy'
+    #   end
+    # end
+    # ```
+    #
+    # Without the proxy, we'd have two problems:
+    #
+    # 1. **Permanent API pollution**: Adding a `producer` method to config that accepts blocks
+    #    would change its permanent API, even though this functionality is only needed during
+    #    setup.
+    #
+    # 2. **Timing issues**: The producer doesn't exist yet when the user's setup block runs.
+    #    The producer is created in `configure_components` after all user configuration is
+    #    complete. We need to store the user's producer configuration block and apply it
+    #    later at the right time.
+    #
+    # The proxy solves both:
+    # - It only exists during the setup call
+    # - It stores the producer configuration block in an instance variable
+    # - After setup, the block is passed to `configure_components` for execution
+    # - The proxy is then discarded
+    #
+    # ## Future Use Cases
+    #
+    # This pattern can be extended for other deferred configuration needs:
+    #
+    # - **Monitor configuration**: Intercept monitor setup to configure it after all components
+    #   are initialized
+    # - **Custom component initialization**: Allow users to configure internal components that
+    #   need access to the fully-configured environment
+    # - **Feature toggles**: Enable/disable features based on the complete configuration state
+    #
+    # ## Implementation Details
+    #
+    # The proxy uses Ruby's SimpleDelegator pattern:
+    # 1. Inherits from SimpleDelegator for automatic delegation
+    # 2. Implements specific interceptor methods (currently just `producer`)
+    # 3. Delegates everything else to the wrapped config automatically
+    # 4. Stores deferred configuration in instance variables
+    #
+    # ## Lifecycle
+    #
+    # ```
+    # Setup.setup(&block)
+    #   ↓
+    # proxy = ConfigProxy.new(config)  # Create proxy
+    #   ↓
+    # configure { yield(proxy) }       # User block receives proxy
+    #   ↓
+    # [User calls config methods]      # Most delegate to real config
+    #   ↓
+    # [User calls config.producer {}]  # Intercepted by proxy
+    #   ↓
+    # configure_components(proxy.producer_initialization_block)  # Block retrieved
+    #   ↓
+    # [Block executed with real producer config]
+    #   ↓
+    # proxy = nil                      # Proxy discarded
+    # ```
+    #
+    # ## Example Usage
+    #
+    # ```ruby
+    # class KarafkaApp < Karafka::App
+    #   setup do |config|
+    #     # Standard config access - delegated to real config
+    #     config.kafka = { 'bootstrap.servers': 'localhost:9092' }
+    #     config.client_id = 'my_app'
+    #
+    #     # Special intercepted method - handled by proxy
+    #     config.producer do |producer_config|
+    #       producer_config.kafka['compression.type'] = 'snappy'
+    #       producer_config.kafka['linger.ms'] = 10
+    #       producer_config.max_wait_timeout = 60_000
+    #     end
+    #   end
+    # end
+    # ```
+    #
+    # @see Karafka::Setup::Config.setup
+    # @see Karafka::Setup::Config.configure_components
+    class ConfigProxy < SimpleDelegator
+      # @return [Proc] the stored producer initialization block (defaults to empty lambda)
+      attr_reader :producer_initialization_block
+
+      # Creates a new configuration proxy wrapping the actual config object.
+      #
+      # Uses SimpleDelegator to automatically delegate all method calls to the wrapped config
+      # except for specifically intercepted methods like {#producer}.
+      #
+      # The producer initialization block defaults to an empty lambda, eliminating the need for
+      # nil checks when executing the block in {#configure_components}.
+      #
+      # @param config [Karafka::Setup::Config::Node] the actual config object to wrap
+      #
+      # @example
+      #   proxy = ConfigProxy.new(Karafka::App.config)
+      def initialize(config)
+        super
+        @producer_initialization_block = ->(_) {}
+      end
+
+      # Captures a block for producer configuration or delegates producer assignment to config.
+      #
+      # This method has dual behavior:
+      #
+      # 1. **With a block**: Stores the block for later execution after the producer is created.
+      #    This allows users to customize producer settings without manually creating a producer
+      #    instance.
+      #
+      # 2. **With an instance**: Delegates to `config.producer=` for direct producer assignment.
+      #    This preserves the existing API for users who want to provide their own producer.
+      #
+      # The block is stored in `@producer_initialization_block` and later passed to
+      # `configure_components` where it's executed with the producer's config object.
+      #
+      # ## Why This Exists
+      #
+      # The producer is created in `configure_components` after all user configuration is
+      # complete. This ensures the producer inherits the correct kafka settings. However,
+      # users may want to customize the producer further (add middleware, change timeouts,
+      # etc.) without creating their own producer instance.
+      #
+      # This method bridges the gap: it lets users configure the producer **as if it exists**
+      # during setup, but actually defers the configuration until after it's created.
+      #
+      # ## Block Execution Timing
+      #
+      # ```
+      # setup do |config|
+      #   config.kafka = { ... }        # Runs immediately
+      #
+      #   config.producer do |pc|       # Block STORED (not executed yet)
+      #     pc.kafka['...'] = '...'
+      #   end
+      # end
+      # # User block complete
+      # # Config validation runs
+      # # configure_components creates producer
+      # # NOW the stored block executes: block.call(producer.config)
+      # ```
+      #
+      # @param instance [WaterDrop::Producer, nil] optional producer instance for direct
+      #   assignment
+      # @param block [Proc] optional block for producer configuration. Will be called with
+      #   the producer's config object after the producer is created.
+      # @return [void]
+      #
+      # @example Configuring producer with a block
+      #   config.producer do |producer_config|
+      #     producer_config.kafka['compression.type'] = 'snappy'
+      #     producer_config.max_wait_timeout = 30_000
+      #     producer_config.middleware.append(MyMiddleware.new)
+      #   end
+      #
+      # @example Direct producer assignment
+      #   custom_producer = WaterDrop::Producer.new { |c| c.kafka = { 'bootstrap.servers' => 'localhost:9092' } }
+      #   config.producer = custom_producer
+      def producer(instance = nil, &block)
+        if block
+          # Store the configuration block for later execution
+          @producer_initialization_block = block
+        else
+          # Direct assignment - delegate to real config via __getobj__
+          __getobj__.producer = instance
+        end
+      end
+    end
+  end
+end

data/lib/karafka/setup/contracts/config.rb

@@ -18,7 +18,7 @@ module Karafka
         end
 
         # Topics regexp constant reference for easier usage
-        TOPIC_REGEXP = ::Karafka::Contracts::TOPIC_REGEXP
+        TOPIC_REGEXP = Karafka::Contracts::TOPIC_REGEXP
 
         private_constant :TOPIC_REGEXP
 

data/lib/karafka/swarm/liveness_listener.rb

@@ -13,6 +13,7 @@ module Karafka
         orphaned_exit_code: %i[internal swarm orphaned_exit_code]
       )
 
+      # Initializes the liveness listener
       def initialize
         @last_checked_at = 0
         @mutex = Mutex.new

data/lib/karafka/swarm/manager.rb

@@ -29,6 +29,7 @@ module Karafka
       # @return [Array<Node>] All nodes that manager manages
       attr_reader :nodes
 
+      # Initializes the swarm manager with empty nodes
       def initialize
         @nodes = []
         @statuses = Hash.new { |h, k| h[k] = {} }
@@ -97,7 +98,7 @@ module Karafka
       # If we've issued a stop to this process and it does not want to stop in the period, kills it
       #
       # @param statuses [Hash] hash with statuses transitions with times
-      # @param [Swarm::Node] node we're checking
+      # @param node [Swarm::Node] node we're checking
       # @return [Boolean] should it be the last action taken on this node in this run
       def terminate_if_hanging(statuses, node)
         return false unless statuses.key?(:stop)
@@ -118,7 +119,7 @@ module Karafka
       # reported it is not healthy.
       #
       # @param statuses [Hash] hash with statuses transitions with times
-      # @param [Swarm::Node] node we're checking
+      # @param node [Swarm::Node] node we're checking
       # @return [Boolean] should it be the last action taken on this node in this run
       def stop_if_not_healthy(statuses, node)
         status = node.status
@@ -146,7 +147,7 @@ module Karafka
       # If node stopped responding, starts the stopping procedure.
       #
       # @param statuses [Hash] hash with statuses transitions with times
-      # @param [Swarm::Node] node we're checking
+      # @param node [Swarm::Node] node we're checking
       # @return [Boolean] should it be the last action taken on this node in this run
       def stop_if_not_responding(statuses, node)
         # Do nothing if already stopping
@@ -171,7 +172,7 @@ module Karafka
       # Cleans up a dead process and remembers time of death for restart after a period.
       #
       # @param statuses [Hash] hash with statuses transitions with times
-      # @param [Swarm::Node] node we're checking
+      # @param node [Swarm::Node] node we're checking
       # @return [Boolean] should it be the last action taken on this node in this run
       def cleanup_one(statuses, node)
         return false if statuses.key?(:dead_since)
@@ -188,7 +189,7 @@ module Karafka
       # killed for some external reason.
       #
       # @param statuses [Hash] hash with statuses transitions with times
-      # @param [Swarm::Node] node we're checking
+      # @param node [Swarm::Node] node we're checking
       # @return [Boolean] should it be the last action taken on this node in this run
       def restart_after_timeout(statuses, node)
         return false unless over?(statuses[:dead_since], node_restart_timeout)
@@ -200,7 +201,7 @@ module Karafka
 
       # Starts a new node (or restarts dead)
       #
-      # @param [Swarm::Node] node we're starting
+      # @param node [Swarm::Node] node we're starting
       def start_one(node)
         instr_args = { caller: self, node: node }
 

data/lib/karafka/swarm/node.rb

@@ -73,7 +73,7 @@ module Karafka
           old_producer_config = old_producer.config
 
           # Supervisor producer is closed, hence we need a new one here
-          config.producer = ::WaterDrop::Producer.new do |p_config|
+          config.producer = WaterDrop::Producer.new do |p_config|
             p_config.kafka = Setup::AttributesMap.producer(kafka.dup)
             p_config.logger = config.logger
 

data/lib/karafka/swarm/supervisor.rb

@@ -34,6 +34,7 @@ module Karafka
 
       private_constant :SHUTDOWN_GRACE_PERIOD
 
+      # Initializes the swarm supervisor
       def initialize
         @mutex = Mutex.new
         @queue = Queue.new

data/lib/karafka/time_trackers/base.rb

@@ -8,7 +8,7 @@ module Karafka
   module TimeTrackers
     # Base class for all the time-trackers.
     class Base
-      include ::Karafka::Core::Helpers::Time
+      include Karafka::Core::Helpers::Time
     end
   end
 end

data/lib/karafka/version.rb

@@ -3,5 +3,5 @@
 # Main module namespace
 module Karafka
   # Current Karafka version
-  VERSION = '2.5.2'
+  VERSION = '2.5.3'
 end

data/lib/karafka.rb

@@ -34,7 +34,7 @@ module Karafka
       env.replace(environment.to_s)
     end
 
-    # @return [Logger] logger that we want to use. Will use ::Karafka::Logger by default
+    # @return [Logger] logger that we want to use. Will use Karafka::Logger by default
     def logger
       @logger ||= App.config.logger
     end
@@ -148,7 +148,7 @@ module Karafka
     #
     # This method refreshes the things that might have been altered by the configuration
     def refresh!
-      config = ::Karafka::App.config
+      config = Karafka::App.config
 
       @logger = config.logger
       @producer = config.producer

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: karafka
 version: !ruby/object:Gem::Version
-  version: 2.5.2
+  version: 2.5.3
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -49,21 +49,21 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.22.0
+        version: 0.23.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.22.0
+        version: 0.23.1
 - !ruby/object:Gem::Dependency
   name: waterdrop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.8.9
+        version: 2.8.14
     - - "<"
       - !ruby/object:Gem::Version
         version: 3.0.0
@@ -73,7 +73,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.8.9
+        version: 2.8.14
     - - "<"
       - !ruby/object:Gem::Version
         version: 3.0.0
@@ -118,6 +118,7 @@ files:
 - ".rspec"
 - ".ruby-gemset"
 - ".ruby-version"
+- ".yard-lint.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
@@ -586,6 +587,7 @@ files:
 - lib/karafka/server.rb
 - lib/karafka/setup/attributes_map.rb
 - lib/karafka/setup/config.rb
+- lib/karafka/setup/config_proxy.rb
 - lib/karafka/setup/contracts/config.rb
 - lib/karafka/setup/defaults_injector.rb
 - lib/karafka/setup/dsl.rb