karafka-web 0.11.5 → 0.11.6

data/lib/karafka/web/ui/models/status/checks/partitions.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if required Web UI topics have the correct number of partitions.
+            #
+            # The consumers states, reports, and metrics topics must have exactly
+            # 1 partition each for the Web UI to function correctly. The errors
+            # topic can have any number of partitions.
+            class Partitions < Base
+              depends_on :topics
+
+              class << self
+                # @return [Hash] empty hash for halted state
+                def halted_details
+                  {}
+                end
+              end
+
+              # Executes the partitions check.
+              #
+              # Verifies that state, reports, and metrics topics have exactly 1 partition.
+              #
+              # @return [Status::Step] result with topic details including partition counts
+              def call
+                details = context.topics_details
+
+                status = :success
+                status = :failure if details[context.topics_consumers_states][:partitions] != 1
+                status = :failure if details[context.topics_consumers_reports][:partitions] != 1
+                status = :failure if details[context.topics_consumers_metrics][:partitions] != 1
+
+                step(status, details)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/pro_subscription.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if Karafka Pro is enabled.
+            #
+            # This is an independent, warning-only check. Not having Pro is not
+            # an error, but users should be aware that some features may not work
+            # without it.
+            class ProSubscription < Base
+              independent!
+
+              # Executes the Pro subscription check.
+              #
+              # @return [Status::Step] success if Pro is enabled, warning otherwise
+              def call
+                step(::Karafka.pro? ? :success : :warning)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/replication.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if topics have adequate replication factors.
+            #
+            # In production environments, replication factor < 2 is a potential
+            # problem because data could be lost if a broker fails. This check
+            # warns about low replication but doesn't fail because it's not
+            # critical for functionality.
+            #
+            # @note Low replication is only a warning in production environments.
+            #   In non-production environments, replication of 1 is acceptable.
+            class Replication < Base
+              depends_on :partitions
+
+              class << self
+                # @return [Hash] empty hash for halted state
+                def halted_details
+                  {}
+                end
+              end
+
+              # Executes the replication check.
+              #
+              # Verifies that all topics have replication factor >= 2 in production.
+              #
+              # @return [Status::Step] result with topic details including replication factors
+              def call
+                details = context.topics_details
+
+                status = :success
+                # Low replication is not an error but just a warning and a potential problem
+                # in case of a crash, this is why we do not fail but warn only
+                status = :warning if details.values.any? { |det| det[:replication] < 2 }
+                # Allow for non-production setups to use replication 1 as it is not that relevant
+                status = :success unless Karafka.env.production?
+
+                step(status, details)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/routing_topics_presence.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if all active topics in the routing exist in the cluster.
+            #
+            # This identifies topics that are configured in the routing but don't
+            # actually exist in Kafka. Pattern-based topics are excluded from this
+            # check since they may not exist yet.
+            #
+            # @note This is a warning-only check - missing topics don't block
+            #   the dependency chain but should be addressed.
+            class RoutingTopicsPresence < Base
+              depends_on :consumers_reports_schema_state
+
+              class << self
+                # @return [Array] empty array for halted state
+                def halted_details
+                  []
+                end
+              end
+
+              # Executes the routing topics presence check.
+              #
+              # Compares routed topics against existing cluster topics.
+              #
+              # @return [Status::Step] success if all exist, warning if any missing
+              def call
+                existing = context.cluster_info.topics.map { |topic| topic[:topic_name] }
+
+                missing = ::Karafka::App
+                  .routes
+                  .flat_map(&:topics)
+                  .flat_map { |topics| topics.map(&:itself) }
+                  .select(&:active?)
+                  .reject { |topic| topic.respond_to?(:patterns?) ? topic.patterns? : nil }
+                  .map(&:name)
+                  .uniq
+                  .then { |routed_topics| routed_topics - existing }
+
+                step(missing.empty? ? :success : :warning, missing)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/state_calculation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if there is a subscription to the reports topic being actively consumed.
+            #
+            # The Web UI requires an active consumer processing the reports topic
+            # to calculate and update the state. This check verifies that subscription
+            # exists.
+            class StateCalculation < Base
+              depends_on :materializing_lag
+
+              # Executes the state calculation check.
+              #
+              # Looks for the reports topic in the list of subscribed topics
+              # from the health data. Caches subscriptions in context.
+              #
+              # @return [Status::Step] success if subscribed, failure otherwise
+              def call
+                context.subscriptions ||= Models::Health
+                  .current(context.current_state)
+                  .values.map { |consumer_group| consumer_group[:topics] }
+                  .flat_map(&:keys)
+
+                subscribed = context.subscriptions.include?(context.topics_consumers_reports)
+
+                step(subscribed ? :success : :failure)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/topics.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if all required Web UI topics exist in the Kafka cluster.
+            #
+            # The Web UI requires several topics to function:
+            # - consumers states topic
+            # - consumers reports topic
+            # - consumers metrics topic
+            # - errors topic
+            class Topics < Base
+              depends_on :connection
+
+              class << self
+                # @return [Hash] empty hash for halted state
+                def halted_details
+                  {}
+                end
+              end
+
+              # Executes the topics check.
+              #
+              # Verifies that all required topics exist by checking the cluster info
+              # cached in the context.
+              #
+              # @return [Status::Step] result with topic details
+              def call
+                details = context.topics_details
+                status = (details.all? { |_, detail| detail[:present] }) ? :success : :failure
+
+                step(status, details)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/context.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          # Shared context container for status checks.
+          #
+          # This class holds cached data that is shared across multiple status checks.
+          # Instead of each check fetching data independently, they share this context
+          # to avoid redundant Kafka calls and ensure consistency.
+          #
+          # The context provides:
+          # - Memoized accessors for expensive data (cluster info, state, metrics)
+          # - Helper methods for topic name configuration
+          # - Computed topic details based on cluster info
+          #
+          # @example Using context in a check
+          #   class MyCheck < Base
+          #     def call
+          #       # Access shared data
+          #       context.current_state
+          #       context.cluster_info
+          #
+          #       # Use topic helpers
+          #       context.topics_consumers_states
+          #     end
+          #   end
+          class Context
+            # @return [Object, nil] cluster metadata from Kafka
+            attr_accessor :cluster_info
+
+            # @return [Float, nil] time in milliseconds to connect to Kafka
+            attr_accessor :connection_time
+
+            # @return [Hash, nil] current consumers state from Kafka
+            attr_accessor :current_state
+
+            # @return [Hash, nil] current consumers metrics from Kafka
+            attr_accessor :current_metrics
+
+            # @return [Array, nil] list of active processes
+            attr_accessor :processes
+
+            # @return [Array, nil] list of topic subscriptions
+            attr_accessor :subscriptions
+
+            # Returns the consumers states topic name from configuration.
+            #
+            # @return [String] the configured consumers states topic name
+            def topics_consumers_states
+              ::Karafka::Web.config.topics.consumers.states.name.to_s
+            end
+
+            # Returns the consumers reports topic name from configuration.
+            #
+            # @return [String] the configured consumers reports topic name
+            def topics_consumers_reports
+              ::Karafka::Web.config.topics.consumers.reports.name.to_s
+            end
+
+            # Returns the consumers metrics topic name from configuration.
+            #
+            # @return [String] the configured consumers metrics topic name
+            def topics_consumers_metrics
+              ::Karafka::Web.config.topics.consumers.metrics.name.to_s
+            end
+
+            # Returns the errors topic name from configuration.
+            #
+            # @return [String] the configured errors topic name
+            def topics_errors
+              ::Karafka::Web.config.topics.errors.name
+            end
+
+            # Returns the consumers commands topic name from configuration.
+            #
+            # @return [String] the configured consumers commands topic name
+            def topics_consumers_commands
+              ::Karafka::Web.config.topics.consumers.commands.name.to_s
+            end
+
+            # Computes and returns details about all Web UI topics.
+            #
+            # For each topic, returns whether it exists, its partition count,
+            # and replication factor. Uses cluster_info to determine actual values.
+            #
+            # @return [Hash] hash with topic names as keys and detail hashes as values
+            # @example Return value
+            #   {
+            #     'karafka_consumers_states' => { present: true, partitions: 1, replication: 3 },
+            #     'karafka_consumers_reports' => { present: false, partitions: 0, replication: 1 }
+            #   }
+            def topics_details
+              @topics_details ||= compute_topics_details
+            end
+
+            # Clears the memoized topics_details cache.
+            #
+            # Call this if cluster_info is updated and you need fresh topic details.
+            def clear_topics_details_cache
+              @topics_details = nil
+            end
+
+            private
+
+            # Computes topic details from cluster info.
+            #
+            # @return [Hash] topic details hash
+            def compute_topics_details
+              base = { present: false, partitions: 0, replication: 1 }
+
+              topics = {
+                topics_consumers_states => base.dup,
+                topics_consumers_reports => base.dup,
+                topics_consumers_metrics => base.dup,
+                topics_errors => base.dup
+              }
+
+              return topics unless cluster_info
+
+              cluster_info.topics.each do |topic|
+                name = topic[:topic_name]
+
+                next unless topics.key?(name)
+
+                topics[name].merge!(
+                  present: true,
+                  partitions: topic[:partition_count],
+                  replication: topic[:partitions].map { |part| part[:replica_count] }.max
+                )
+              end
+
+              topics
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/step.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          # Represents the result of a single status check step.
+          #
+          # Each check in the status flow returns a Step that contains:
+          # - The status of the check (:success, :warning, :failure, or :halted)
+          # - Optional details hash with check-specific information
+          #
+          # @example Creating a successful step
+          #   Step.new(:success, { time: 150 })
+          #
+          # @example Creating a halted step (dependency failed)
+          #   Step.new(:halted, {})
+          Step = Struct.new(:status, :details) do
+            # Checks if the step completed successfully (allows chain to continue).
+            #
+            # Both :success and :warning are considered successful because warnings
+            # don't block the dependency chain - they just notify about potential issues.
+            #
+            # @return [Boolean] true if status is :success or :warning
+            def success?
+              %i[success warning].include?(status)
+            end
+
+            # Returns the partial namespace for rendering the appropriate view.
+            #
+            # Maps the status to a directory name used for view partial lookup:
+            # - :success -> 'successes'
+            # - :warning -> 'warnings'
+            # - :failure -> 'failures'
+            # - :halted  -> 'failures' (halted checks show failure partial)
+            #
+            # @return [String] the partial namespace directory name
+            # @raise [Karafka::Errors::UnsupportedCaseError] if status is unknown
+            def partial_namespace
+              case status
+              when :success then "successes"
+              when :warning then "warnings"
+              when :failure then "failures"
+              when :halted then "failures"
+              else
+                raise ::Karafka::Errors::UnsupportedCaseError, status
+              end
+            end
+
+            # Returns the string representation of the status.
+            #
+            # Used by views to dynamically select the appropriate partial template.
+            #
+            # @return [String] the status as a string
+            def to_s
+              status.to_s
+            end
+          end
+        end
+      end
+    end
+  end
+end