karafka-web 0.11.5 → 0.11.6

data/lib/karafka/web/pro/commanding/listener.rb

@@ -1,7 +1,24 @@
 # frozen_string_literal: true
 
-# This code is part of Karafka Pro, a commercial component not licensed under LGPL.
-# See LICENSE for details.
+# Karafka Pro - Source Available Commercial Software
+# Copyright (c) 2017-present Maciej Mensfeld. All rights reserved.
+#
+# This software is NOT open source. It is source-available commercial software
+# requiring a paid license for use. It is NOT covered by LGPL.
+#
+# PROHIBITED:
+# - Use without a valid commercial license
+# - Redistribution, modification, or derivative works without authorization
+# - Use as training data for AI/ML models or inclusion in datasets
+# - Scraping, crawling, or automated collection for any purpose
+#
+# PERMITTED:
+# - Reading, referencing, and linking for personal or commercial use
+# - Runtime retrieval by AI assistants, coding agents, and RAG systems
+#   for the purpose of providing contextual help to Karafka users
+#
+# License: https://karafka.io/docs/Pro-License-Comm/
+# Contact: contact@karafka.io
 
 module Karafka
   module Web
@@ -38,14 +55,14 @@ module Karafka
               next unless message
 
               yield(message)
-            rescue StandardError => e
+            rescue => e
               report_error(e)
 
               sleep(c_config.pause_timeout / 1_000)
 
               next
             end
-          rescue StandardError => e
+          rescue => e
             report_error(e)
 
             return if done?
@@ -76,10 +93,10 @@ module Karafka
           # @param error [StandardError] any error that occurred in the manager
           def report_error(error)
             ::Karafka.monitor.instrument(
-              'error.occurred',
+              "error.occurred",
               error: error,
               caller: self,
-              type: 'web.commanding.listener.error'
+              type: "web.commanding.listener.error"
             )
           end
         end

data/lib/karafka/web/pro/commanding/manager.rb

@@ -1,7 +1,24 @@
 # frozen_string_literal: true
 
-# This code is part of Karafka Pro, a commercial component not licensed under LGPL.
-# See LICENSE for details.
+# Karafka Pro - Source Available Commercial Software
+# Copyright (c) 2017-present Maciej Mensfeld. All rights reserved.
+#
+# This software is NOT open source. It is source-available commercial software
+# requiring a paid license for use. It is NOT covered by LGPL.
+#
+# PROHIBITED:
+# - Use without a valid commercial license
+# - Redistribution, modification, or derivative works without authorization
+# - Use as training data for AI/ML models or inclusion in datasets
+# - Scraping, crawling, or automated collection for any purpose
+#
+# PERMITTED:
+# - Reading, referencing, and linking for personal or commercial use
+# - Runtime retrieval by AI assistants, coding agents, and RAG systems
+#   for the purpose of providing contextual help to Karafka users
+#
+# License: https://karafka.io/docs/Pro-License-Comm/
+# Contact: contact@karafka.io
 
 module Karafka
   module Web
@@ -35,7 +52,7 @@ module Karafka
           #
           # @param _event [Karafka::Core::Monitoring::Event]
           def on_app_running(_event)
-            async_call('karafka.web.pro.commanding.manager')
+            async_call("karafka.web.pro.commanding.manager")
           end
 
           # When app stops, we stop the manager
@@ -67,12 +84,12 @@ module Karafka
               )
             end
           # This should not happen, if this is happening, please report this as a bug
-          rescue StandardError => e
+          rescue => e
             ::Karafka.monitor.instrument(
-              'error.occurred',
+              "error.occurred",
               error: e,
               caller: self,
-              type: 'web.commanding.manager.error'
+              type: "web.commanding.manager.error"
             )
 
             raise e
@@ -83,23 +100,27 @@ module Karafka
           # @param command [Request] command request
           def control(command)
             action = case command.name
-                     when Commands::Consumers::Trace.name
-                       Commands::Consumers::Trace
-                     when Commands::Consumers::Stop.name
-                       Commands::Consumers::Stop
-                     when Commands::Consumers::Quiet.name
-                       Commands::Consumers::Quiet
-                     when Commands::Partitions::Seek.name
-                       Commands::Partitions::Seek
-                     when Commands::Partitions::Resume.name
-                       Commands::Partitions::Resume
-                     when Commands::Partitions::Pause.name
-                       Commands::Partitions::Pause
-                     else
-                       # We raise it and will be rescued, reported and ignored. We raise it as
-                       # this should not happen unless there are version conflicts
-                       raise ::Karafka::Errors::UnsupportedCaseError, command.name
-                     end
+            when Commands::Consumers::Trace.name
+              Commands::Consumers::Trace
+            when Commands::Consumers::Stop.name
+              Commands::Consumers::Stop
+            when Commands::Consumers::Quiet.name
+              Commands::Consumers::Quiet
+            when Commands::Partitions::Seek.name
+              Commands::Partitions::Seek
+            when Commands::Partitions::Resume.name
+              Commands::Partitions::Resume
+            when Commands::Partitions::Pause.name
+              Commands::Partitions::Pause
+            when Commands::Topics::Pause.name
+              Commands::Topics::Pause
+            when Commands::Topics::Resume.name
+              Commands::Topics::Resume
+            else
+              # We raise it and will be rescued, reported and ignored. We raise it as
+              # this should not happen unless there are version conflicts
+              raise ::Karafka::Errors::UnsupportedCaseError, command.name
+            end
 
             action.new(command).call
           end

data/lib/karafka/web/pro/commanding/matcher.rb

@@ -1,7 +1,24 @@
 # frozen_string_literal: true
 
-# This code is part of Karafka Pro, a commercial component not licensed under LGPL.
-# See LICENSE for details.
+# Karafka Pro - Source Available Commercial Software
+# Copyright (c) 2017-present Maciej Mensfeld. All rights reserved.
+#
+# This software is NOT open source. It is source-available commercial software
+# requiring a paid license for use. It is NOT covered by LGPL.
+#
+# PROHIBITED:
+# - Use without a valid commercial license
+# - Redistribution, modification, or derivative works without authorization
+# - Use as training data for AI/ML models or inclusion in datasets
+# - Scraping, crawling, or automated collection for any purpose
+#
+# PERMITTED:
+# - Reading, referencing, and linking for personal or commercial use
+# - Runtime retrieval by AI assistants, coding agents, and RAG systems
+#   for the purpose of providing contextual help to Karafka users
+#
+# License: https://karafka.io/docs/Pro-License-Comm/
+# Contact: contact@karafka.io
 
 module Karafka
   module Web
@@ -12,26 +29,37 @@ module Karafka
         #
         # Since we use the `assign`, each process listens to this topic and receives messages
         # with commands targeting all the processes, this is why it needs to be filtered.
+        #
+        # The matcher uses a set of sub-matchers, each responsible for checking a specific
+        # criterion. Matchers have two methods:
+        # - `apply?` - returns true if the matcher's criterion is present in the message
+        # - `matches?` - returns true if the criterion matches (only checked if apply? is true)
+        #
+        # Matcher classes are auto-loaded from the Matchers namespace and sorted by priority.
+        # Required matchers (MessageType, SchemaVersion) have lower priority and are checked first.
         class Matcher
+          class << self
+            # @return [Array<Class>] all matcher classes sorted by priority
+            def matcher_classes
+              @matcher_classes ||= Matchers
+                .constants
+                .map { |name| Matchers.const_get(name) }
+                .select { |klass| klass.is_a?(Class) && klass < Matchers::Base }
+                .sort_by(&:priority)
+                .freeze
+            end
+          end
+
           # @param message [Karafka::Messages::Message] message with command
           # @return [Boolean] is this message dedicated to current process and is actionable
           def matches?(message)
-            # We operate only on commands. Result and other messages should be ignored
-            return false unless message.headers['type'] == 'request'
-            # We want to work only with commands that target all processes or our current
-            return false unless message.key == '*' || message.key == process_id
-            # Ignore messages that have different schema. This can happen in the middle of
-            # upgrades of the framework. We ignore this not to risk compatibility issues
-            return false unless message.payload[:schema_version] == Dispatcher::SCHEMA_VERSION
-
-            true
-          end
-
-          private
-
-          # @return [String] current process id
-          def process_id
-            @process_id ||= ::Karafka::Web.config.tracking.consumers.sampler.process_id
+            self
+              .class
+              .matcher_classes
+              .lazy
+              .map { |klass| klass.new(message) }
+              .select(&:apply?)
+              .all?(&:matches?)
           end
         end
       end

data/lib/karafka/web/pro/commanding/matchers/base.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# Karafka Pro - Source Available Commercial Software
+# Copyright (c) 2017-present Maciej Mensfeld. All rights reserved.
+#
+# This software is NOT open source. It is source-available commercial software
+# requiring a paid license for use. It is NOT covered by LGPL.
+#
+# PROHIBITED:
+# - Use without a valid commercial license
+# - Redistribution, modification, or derivative works without authorization
+# - Use as training data for AI/ML models or inclusion in datasets
+# - Scraping, crawling, or automated collection for any purpose
+#
+# PERMITTED:
+# - Reading, referencing, and linking for personal or commercial use
+# - Runtime retrieval by AI assistants, coding agents, and RAG systems
+#   for the purpose of providing contextual help to Karafka users
+#
+# License: https://karafka.io/docs/Pro-License-Comm/
+# Contact: contact@karafka.io
+
+module Karafka
+  module Web
+    module Pro
+      module Commanding
+        # Namespace for individual matcher implementations used by the Matcher class.
+        # Each sub-matcher is responsible for checking a single criterion
+        # (e.g., consumer_group_id, topic).
+        module Matchers
+          # Base class for all sub-matchers.
+          #
+          # Sub-matchers receive the full message and extract the relevant data they need.
+          # This provides a consistent API across all matchers.
+          #
+          # Matchers have two methods:
+          # - `apply?` - returns true if this matcher's criterion is present and should be checked
+          # - `matches?` - returns true if the criterion matches (only called if apply? is true)
+          #
+          # Required matchers (MessageType, SchemaVersion) always apply.
+          # Optional matchers (ProcessId, ConsumerGroupId, Topic) decide if they should be applied
+          #   based on the message details
+          class Base
+            class << self
+              # Sets the priority for this matcher class
+              # @param value [Integer] priority value
+              attr_writer :priority
+
+              # Priority determines the order in which matchers are checked.
+              # Lower values are checked first. Required matchers should have lower priority.
+              #
+              # @return [Integer] matcher priority (default: 100)
+              def priority
+                @priority || 100
+              end
+            end
+
+            # @param message [Karafka::Messages::Message] the command message to match against
+            def initialize(message)
+              @message = message
+            end
+
+            # Checks if this matcher should be applied to the message.
+            # Override in subclasses for optional matchers.
+            #
+            # @return [Boolean] true if this matcher should check the message
+            def apply?
+              true
+            end
+
+            # Checks if the criterion is satisfied.
+            # Only called when apply? returns true.
+            #
+            # @return [Boolean] true if matches
+            def matches?
+              raise NotImplementedError, "Implement in a subclass"
+            end
+
+            private
+
+            attr_reader :message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/pro/commanding/matchers/consumer_group_id.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Karafka Pro - Source Available Commercial Software
+# Copyright (c) 2017-present Maciej Mensfeld. All rights reserved.
+#
+# This software is NOT open source. It is source-available commercial software
+# requiring a paid license for use. It is NOT covered by LGPL.
+#
+# PROHIBITED:
+# - Use without a valid commercial license
+# - Redistribution, modification, or derivative works without authorization
+# - Use as training data for AI/ML models or inclusion in datasets
+# - Scraping, crawling, or automated collection for any purpose
+#
+# PERMITTED:
+# - Reading, referencing, and linking for personal or commercial use
+# - Runtime retrieval by AI assistants, coding agents, and RAG systems
+#   for the purpose of providing contextual help to Karafka users
+#
+# License: https://karafka.io/docs/Pro-License-Comm/
+# Contact: contact@karafka.io
+
+module Karafka
+  module Web
+    module Pro
+      module Commanding
+        module Matchers
+          # Matcher that checks if the current process has any assignments for the consumer
+          # group ID specified in the message matchers. Uses the Karafka assignments tracker
+          # to check actual current assignments rather than just routing configuration.
+          # This is an optional matcher that only applies when consumer_group_id is specified.
+          class ConsumerGroupId < Base
+            # @return [Boolean] true if consumer_group_id criterion is specified in matchers
+            def apply?
+              !consumer_group_id.nil?
+            end
+
+            # Checks if this process has any assignments for the specified consumer group
+            #
+            # @return [Boolean] true if this process has partitions assigned for the consumer group
+            def matches?
+              ::Karafka::App.assignments.any? do |topic, _partitions|
+                topic.consumer_group.id == consumer_group_id
+              end
+            end
+
+            private
+
+            # @return [String, nil] consumer group ID from matchers hash
+            def consumer_group_id
+              message.payload.dig(:matchers, :consumer_group_id)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/pro/commanding/matchers/message_type.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Karafka Pro - Source Available Commercial Software
+# Copyright (c) 2017-present Maciej Mensfeld. All rights reserved.
+#
+# This software is NOT open source. It is source-available commercial software
+# requiring a paid license for use. It is NOT covered by LGPL.
+#
+# PROHIBITED:
+# - Use without a valid commercial license
+# - Redistribution, modification, or derivative works without authorization
+# - Use as training data for AI/ML models or inclusion in datasets
+# - Scraping, crawling, or automated collection for any purpose
+#
+# PERMITTED:
+# - Reading, referencing, and linking for personal or commercial use
+# - Runtime retrieval by AI assistants, coding agents, and RAG systems
+#   for the purpose of providing contextual help to Karafka users
+#
+# License: https://karafka.io/docs/Pro-License-Comm/
+# Contact: contact@karafka.io
+
+module Karafka
+  module Web
+    module Pro
+      module Commanding
+        module Matchers
+          # Matcher that checks if the message type header matches the expected value.
+          # Used to filter command messages from result and other message types.
+          # This is a required matcher that always applies.
+          class MessageType < Base
+            # Required matcher - check first
+            self.priority = 0
+
+            # Expected message type for commands
+            COMMAND_TYPE = "request"
+
+            private_constant :COMMAND_TYPE
+
+            # @return [Boolean] true if message type is a command request
+            def matches?
+              message.headers["type"] == COMMAND_TYPE
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/pro/commanding/matchers/partition_id.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Karafka Pro - Source Available Commercial Software
+# Copyright (c) 2017-present Maciej Mensfeld. All rights reserved.
+#
+# This software is NOT open source. It is source-available commercial software
+# requiring a paid license for use. It is NOT covered by LGPL.
+#
+# PROHIBITED:
+# - Use without a valid commercial license
+# - Redistribution, modification, or derivative works without authorization
+# - Use as training data for AI/ML models or inclusion in datasets
+# - Scraping, crawling, or automated collection for any purpose
+#
+# PERMITTED:
+# - Reading, referencing, and linking for personal or commercial use
+# - Runtime retrieval by AI assistants, coding agents, and RAG systems
+#   for the purpose of providing contextual help to Karafka users
+#
+# License: https://karafka.io/docs/Pro-License-Comm/
+# Contact: contact@karafka.io
+
+module Karafka
+  module Web
+    module Pro
+      module Commanding
+        module Matchers
+          # Matcher that checks if the current process has a specific partition assigned.
+          # Uses the Karafka assignments tracker to check actual current assignments.
+          # This is an optional matcher that only applies when partition_id is specified.
+          #
+          # @note This matcher only checks for partition_id presence across all topics.
+          #   For topic-specific partition matching, use this in combination with the
+          #   Topic matcher.
+          class PartitionId < Base
+            # @return [Boolean] true if partition_id criterion is specified in matchers
+            def apply?
+              !partition_id.nil?
+            end
+
+            # Checks if this process has the specified partition assigned (any topic)
+            #
+            # @return [Boolean] true if this process has the partition assigned
+            def matches?
+              ::Karafka::App.assignments.any? do |_topic, partitions|
+                partitions.include?(partition_id)
+              end
+            end
+
+            private
+
+            # @return [Integer, nil] partition ID from matchers hash
+            def partition_id
+              message.payload.dig(:matchers, :partition_id)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/pro/commanding/matchers/process_id.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Karafka Pro - Source Available Commercial Software
+# Copyright (c) 2017-present Maciej Mensfeld. All rights reserved.
+#
+# This software is NOT open source. It is source-available commercial software
+# requiring a paid license for use. It is NOT covered by LGPL.
+#
+# PROHIBITED:
+# - Use without a valid commercial license
+# - Redistribution, modification, or derivative works without authorization
+# - Use as training data for AI/ML models or inclusion in datasets
+# - Scraping, crawling, or automated collection for any purpose
+#
+# PERMITTED:
+# - Reading, referencing, and linking for personal or commercial use
+# - Runtime retrieval by AI assistants, coding agents, and RAG systems
+#   for the purpose of providing contextual help to Karafka users
+#
+# License: https://karafka.io/docs/Pro-License-Comm/
+# Contact: contact@karafka.io
+
+module Karafka
+  module Web
+    module Pro
+      module Commanding
+        module Matchers
+          # Matcher that checks if the current process ID matches the specified process ID
+          # in the matchers hash. This is an optional matcher that only applies when
+          # process_id is specified in the matchers.
+          class ProcessId < Base
+            # @return [Boolean] true if process_id criterion is specified in matchers
+            def apply?
+              !process_id.nil?
+            end
+
+            # @return [Boolean] true if process ID matches
+            def matches?
+              process_id == current_process_id
+            end
+
+            private
+
+            # @return [String, nil] process ID from matchers hash
+            def process_id
+              message.payload.dig(:matchers, :process_id)
+            end
+
+            # @return [String] current process ID from sampler
+            def current_process_id
+              ::Karafka::Web.config.tracking.consumers.sampler.process_id
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/pro/commanding/matchers/schema_version.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Karafka Pro - Source Available Commercial Software
+# Copyright (c) 2017-present Maciej Mensfeld. All rights reserved.
+#
+# This software is NOT open source. It is source-available commercial software
+# requiring a paid license for use. It is NOT covered by LGPL.
+#
+# PROHIBITED:
+# - Use without a valid commercial license
+# - Redistribution, modification, or derivative works without authorization
+# - Use as training data for AI/ML models or inclusion in datasets
+# - Scraping, crawling, or automated collection for any purpose
+#
+# PERMITTED:
+# - Reading, referencing, and linking for personal or commercial use
+# - Runtime retrieval by AI assistants, coding agents, and RAG systems
+#   for the purpose of providing contextual help to Karafka users
+#
+# License: https://karafka.io/docs/Pro-License-Comm/
+# Contact: contact@karafka.io
+
+module Karafka
+  module Web
+    module Pro
+      module Commanding
+        module Matchers
+          # Matcher that checks if the message schema version matches the current dispatcher
+          # schema version. This ensures compatibility between command producers and consumers.
+          # This is a required matcher that always applies.
+          class SchemaVersion < Base
+            # Required matcher - check second (after message type)
+            self.priority = 1
+
+            # @return [Boolean] true if schema version matches
+            def matches?
+              message.payload[:schema_version] == Dispatcher::SCHEMA_VERSION
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/pro/commanding/matchers/topic.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Karafka Pro - Source Available Commercial Software
+# Copyright (c) 2017-present Maciej Mensfeld. All rights reserved.
+#
+# This software is NOT open source. It is source-available commercial software
+# requiring a paid license for use. It is NOT covered by LGPL.
+#
+# PROHIBITED:
+# - Use without a valid commercial license
+# - Redistribution, modification, or derivative works without authorization
+# - Use as training data for AI/ML models or inclusion in datasets
+# - Scraping, crawling, or automated collection for any purpose
+#
+# PERMITTED:
+# - Reading, referencing, and linking for personal or commercial use
+# - Runtime retrieval by AI assistants, coding agents, and RAG systems
+#   for the purpose of providing contextual help to Karafka users
+#
+# License: https://karafka.io/docs/Pro-License-Comm/
+# Contact: contact@karafka.io
+
+module Karafka
+  module Web
+    module Pro
+      module Commanding
+        module Matchers
+          # Matcher that checks if the current process has any assignments for the topic
+          # specified in the message matchers. Uses the Karafka assignments tracker to check
+          # actual current assignments rather than just routing configuration.
+          # This is an optional matcher that only applies when topic is specified.
+          class Topic < Base
+            # @return [Boolean] true if topic criterion is specified in matchers
+            def apply?
+              !topic_name.nil?
+            end
+
+            # Checks if this process has any partitions assigned for the specified topic
+            #
+            # @return [Boolean] true if this process has partitions assigned for the topic
+            def matches?
+              ::Karafka::App.assignments.any? do |topic, _partitions|
+                topic.name == topic_name
+              end
+            end
+
+            private
+
+            # @return [String, nil] topic name from matchers hash
+            def topic_name
+              message.payload.dig(:matchers, :topic)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/pro/commanding/request.rb

@@ -1,7 +1,24 @@
 # frozen_string_literal: true
 
-# This code is part of Karafka Pro, a commercial component not licensed under LGPL.
-# See LICENSE for details.
+# Karafka Pro - Source Available Commercial Software
+# Copyright (c) 2017-present Maciej Mensfeld. All rights reserved.
+#
+# This software is NOT open source. It is source-available commercial software
+# requiring a paid license for use. It is NOT covered by LGPL.
+#
+# PROHIBITED:
+# - Use without a valid commercial license
+# - Redistribution, modification, or derivative works without authorization
+# - Use as training data for AI/ML models or inclusion in datasets
+# - Scraping, crawling, or automated collection for any purpose
+#
+# PERMITTED:
+# - Reading, referencing, and linking for personal or commercial use
+# - Runtime retrieval by AI assistants, coding agents, and RAG systems
+#   for the purpose of providing contextual help to Karafka users
+#
+# License: https://karafka.io/docs/Pro-License-Comm/
+# Contact: contact@karafka.io
 
 module Karafka
   module Web