karafka-web 0.10.3 → 0.11.0.beta1

data/lib/karafka/web/ui/controllers/requests/hookable.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Controllers
+        module Requests
+          # Adds before/after hook support for controller methods.
+          #
+          # This module allows registering callbacks that run before and after
+          # any named method (e.g., `call`, `show`) or for all methods.
+          #
+          # Hooks are inherited from parent controllers, making it easy to
+          # define shared behavior across a hierarchy.
+          #
+          # @example Adding hooks to a controller
+          #   class MyController
+          #     include Hookable
+          #
+          #     before(:call) { puts "before call" }
+          #     after(:call)  { puts "after call" }
+          #
+          #     def call
+          #       run_before_hooks(:call)
+          #       # actual logic
+          #       run_after_hooks(:call)
+          #     end
+          #   end
+          module Hookable
+            # Hook into class inclusion to extend DSL
+            #
+            # @param base [Class] the class including this module
+            def self.included(base)
+              base.extend(ClassMethods)
+            end
+
+            # DSL methods for defining and inheriting hooks
+            module ClassMethods
+              # Inherit parent hooks into subclass
+              #
+              # @param subclass [Class] the subclass inheriting from base controller
+              def inherited(subclass)
+                super
+                subclass.before_hooks.concat(before_hooks)
+                subclass.after_hooks.concat(after_hooks)
+              end
+
+              # @return [Array] accumulated before hooks
+              def before_hooks
+                @before_hooks ||= []
+              end
+
+              # @return [Array] accumulated after hooks
+              def after_hooks
+                @after_hooks ||= []
+              end
+
+              # Register a before hook
+              #
+              # @param actions [Array<Symbol>] optional action names to match (e.g., :call)
+              # @param block [Proc]
+              # @yield a block to execute before matched actions
+              def before(*actions, &block)
+                before_hooks << [actions, block]
+              end
+
+              # Register an after hook
+              #
+              # @param actions [Array<Symbol>] optional action names to match (e.g., :call)
+              # @param block [Proc]
+              # @yield a block to execute after matched actions
+              def after(*actions, &block)
+                after_hooks << [actions, block]
+              end
+            end
+
+            # Run all before hooks matching the action
+            #
+            # @param action_name [Symbol] the method name being invoked
+            def run_before_hooks(action_name)
+              self.class.before_hooks.each do |actions, block|
+                instance_exec(&block) if actions.empty? || actions.include?(action_name)
+              end
+            end
+
+            # Run all after hooks matching the action
+            #
+            # @param action_name [Symbol] the method name being invoked
+            def run_after_hooks(action_name)
+              self.class.after_hooks.each do |actions, block|
+                instance_exec(&block) if actions.empty? || actions.include?(action_name)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/controllers/requests/params.rb

@@ -17,13 +17,51 @@ module Karafka
               days
             ].freeze
 
-            private_constant :ALLOWED_RANGES
+            # What string values true can be in params
+            ALLOWED_BOOLEAN_TRUE = %w[
+              on
+              yes
+              true
+            ].freeze
+
+            private_constant :ALLOWED_RANGES, :ALLOWED_BOOLEAN_TRUE
 
             # @param request_params [Hash] raw hash with params
             def initialize(request_params)
               @request_params = request_params
             end
 
+            # @param key [String, Symbol] params key
+            # @return [Object] value of the requested param
+            def [](key)
+              fetch(key.to_s)
+            end
+
+            # @param args [Symbol, Object] key we want to fetch and other args for `Hash#fetch`
+            # @return [Object] fetched object
+            def fetch(*args)
+              args[0] = args[0].to_s
+              @request_params.fetch(*args)
+            end
+
+            # @param key [String, Symbol] params key
+            # @return [Integer] integer value of the key
+            def int(key)
+              self[key].to_i
+            end
+
+            # @param key [String, Symbol] params key
+            # @return [Boolean] boolean key value
+            def bool(key)
+              ALLOWED_BOOLEAN_TRUE.include?(self[key])
+            end
+
+            # @param key [String, Symbol] params key
+            # @return [String] stringified key value
+            def str(key)
+              self[key].to_s
+            end
+
             # @return [Hash] current search or empty if no search query present
             def current_search
               return @current_search if @current_search

data/lib/karafka/web/ui/controllers/responses/redirect.rb

@@ -16,11 +16,6 @@ module Karafka
               @path = path
               @flashes = flashes
             end
-
-            # @return [Boolean] are we going back via referer and not explicit path
-            def back?
-              @path == :back
-            end
           end
         end
       end

data/lib/karafka/web/ui/controllers/status_controller.rb

@@ -10,6 +10,9 @@ module Karafka
         # page where we check that everything is as expected and if not, we can provide some
         # helpful instructions on how to fix the issues.
         class StatusController < BaseController
+          # Fresh state is needed to generate always correct status
+          before { cache.clear }
+
           # Displays the Web UI setup status
           def show
             @status = Models::Status.new

data/lib/karafka/web/ui/helpers/application_helper.rb

@@ -223,13 +223,22 @@ module Karafka
               title = 'Not available until first offset commit'
               %(<span class="badge badge-secondary" title="#{title}">N/A</span>)
             elsif explore
-              path = explorer_path(topic_name, partition_id, offset)
+              path = explorer_topics_path(topic_name, partition_id, offset)
               %(<a href="#{path}">#{offset}</a>)
             else
               offset.to_s
             end
           end
 
+          # Normalizes the metric value for display. Negative values coming from statistics usually
+          #   mean, that the value is not (yet) available.
+          #
+          # @param value [Integer]
+          # @return [String] input value if not negative or N/A
+          def normalized_metric(value)
+            value.negative? ? 'N/A' : value.to_s
+          end
+
           # @param details [::Karafka::Web::Ui::Models::Partition] partition information with
           #   lso risk state info
           # @return [String] background classes for row marking

data/lib/karafka/web/ui/helpers/paths_helper.rb

@@ -6,6 +6,15 @@ module Karafka
       module Helpers
         # Helper for web ui paths builders
         module PathsHelper
+          # Method that can be used to have conditions in breadcrumbs, etc based on the action
+          # we're in
+          #
+          # @param args [Array<Symbol>] action names we want to check
+          # @return [Boolean] true if any matches the current action name
+          def action?(*args)
+            args.include?(@current_action_name)
+          end
+
           # Helper method to flatten nested hashes and arrays
           # @param prefix [String] The prefix for nested keys, initially an empty string.
           # @param hash [Hash, Array] The nested hash or array to be flattened.
@@ -54,16 +63,51 @@ module Karafka
 
           # Helps build explorer paths. We often link offsets to proper messages, etc so this
           # allows us to short-track this
-          # @param topic_name [String, nil] name of the topic where we want to go within the
-          #   explorer or nil if we want to just go to the explorer root
-          # @param partition_id [Integer, nil] partition we want to display in the explorer or nil
-          #   if we want to go to the topic root
-          # @param offset [Integer, nil] offset of particular message or nil of we want to just go
-          #   to the partition root
-          # @param action [String, nil] specific routed action or nil
+          # @param args [Array<String>] sub-paths
           # @return [String] path to the expected location
-          def explorer_path(topic_name = nil, partition_id = nil, offset = nil, action = nil)
-            root_path(*['explorer', topic_name, partition_id, offset, action].compact)
+          def explorer_path(*args)
+            root_path(*['explorer', args.compact].flatten)
+          end
+
+          # Generates routes for explorer topics paths
+          #
+          # @param args [Array<String>] sub-paths
+          # @return explorer topics path
+          def explorer_topics_path(*args)
+            explorer_path(*['topics', args.compact].flatten)
+          end
+
+          # Generates routes for explorer messages paths
+          #
+          # @param args [Array<String>] sub-paths
+          # @return [String] explorer messages path
+          def explorer_messages_path(*args)
+            explorer_path(*['messages', args.compact].flatten)
+          end
+
+          # Helps build topics paths
+          #
+          # @param args [Array<String>] path params for the topics scope
+          # @return [String] topics scope path
+          def topics_path(*args)
+            root_path('topics', *args)
+          end
+
+          # Helps build consumers paths
+          #
+          # @param args [Array<String>] path params for consumers scope
+          # @return [String] consumers scope path
+          def consumers_path(*args)
+            root_path('consumers', *args)
+          end
+
+          # Helps build per-consumer scope paths
+          #
+          # @param consumer_id [String] consumer process id
+          # @param args [Array<String>] other path components
+          # @return [String] per consumer specific path
+          def consumer_path(consumer_id, *args)
+            consumers_path(consumer_id, *args)
           end
 
           # Helps build scheduled messages paths.
@@ -80,7 +124,7 @@ module Karafka
             action = nil
           )
             root_path(
-              *['scheduled_messages', 'explorer', topic_name, partition_id, offset, action].compact
+              *['scheduled_messages', 'explorer', 'topics', topic_name, partition_id, offset, action].compact
             )
           end
         end

data/lib/karafka/web/ui/lib/admin.rb

@@ -17,7 +17,7 @@ module Karafka
           class << self
             extend Forwardable
 
-            def_delegators ::Karafka::Admin, :read_watermark_offsets, :cluster_info
+            def_delegators ::Karafka::Admin, :read_watermark_offsets, :cluster_info, :topic_info
 
             # Allows us to read messages from the topic
             #

data/lib/karafka/web/ui/lib/cache.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Lib
+        # Thread-safe in-memory cache with metadata tracking.
+        #
+        # This cache supports storing computed values, tracking the last update time,
+        # and computing a hash of the contents for change detection.
+        # It's designed for ephemeral, per-instance caching in Karafka Web controllers or libs.
+        #
+        # The cache ensures safe concurrent access via a mutex and provides utilities
+        # for cache invalidation based on external session state (timestamp + hash).
+        #
+        # @note All cache operations are mutex-synchronized for thread safety.
+        #
+        # @note We do not have granular level caching because our Web UI cache is fairly simple
+        #   and we do not want to overcomplicate things.
+        class Cache
+          # Initializes an empty cache instance
+          # @param ttl_ms [Integer] time to live of the whole cache. After this time cache will be
+          #   cleaned whether or not it is expired.
+          def initialize(ttl_ms)
+            @ttl_ms = ttl_ms
+            @values = {}
+            @timestamp = nil
+            @hash = nil
+            @mutex = Mutex.new
+          end
+
+          # Fetches or computes and stores a value under the given key.
+          #
+          # If the key already exists, returns the cached value.
+          # Otherwise, computes it via the provided block, stores it,
+          # and updates metadata (timestamp + hash).
+          #
+          # @param key [Object] key to retrieve
+          # @yield block to compute the value if key is not present
+          # @return [Object] cached or computed value
+          def fetch(key)
+            @mutex.synchronize do
+              return @values[key] if @values.key?(key)
+
+              @values[key] = yield
+              @hash = Digest::SHA256.hexdigest(
+                @values.sort.to_h.to_json
+              )
+              @timestamp = Time.now.to_f
+              @values[key]
+            end
+          end
+
+          # Clears the cache and resets metadata (timestamp and hash).
+          #
+          # If the mutex is already owned by the current thread, clears immediately.
+          # Otherwise, synchronizes first.
+          #
+          # @return [void]
+          def clear
+            cleaning = lambda do
+              @values.clear
+              @timestamp = nil
+              @hash = nil
+            end
+
+            return cleaning.call if @mutex.owned?
+
+            @mutex.synchronize do
+              cleaning.call
+            end
+          end
+
+          # Checks whether any values have been cached yet
+          #
+          # @return [Boolean] true if the cache has been written to
+          def exist?
+            !timestamp.nil?
+          end
+
+          # Returns the last update timestamp of the cache
+          #
+          # @return [Integer, nil] Unix timestamp or nil if never set
+          def timestamp
+            @mutex.synchronize { @timestamp }
+          end
+
+          # Returns the hash representing the current cached data state
+          #
+          # @return [String, nil] SHA256 hex digest or nil if never set
+          def hash
+            @mutex.synchronize { @hash }
+          end
+
+          # Clears the cache if the provided session hash and timestamp differ
+          #
+          # This is used to invalidate the cache if the external session data indicates
+          # a newer or inconsistent state.
+          #
+          # @param session_hash [String, nil] hash from the session or remote side
+          # @param session_timestamp [Integer, nil] timestamp from the session
+          # @return [Boolean] true if the cache was cleared, false otherwise
+          def clear_if_needed(session_hash, session_timestamp)
+            @mutex.synchronize do
+              return unless should_refresh?(session_hash, session_timestamp)
+
+              clear
+            end
+          end
+
+          private
+
+          # Determines whether the cache should be refreshed based on session data
+          #
+          # @param session_hash [String, nil]
+          # @param session_timestamp [Integer, nil]
+          # @return [Boolean] true if cache should be refreshed
+          def should_refresh?(session_hash, session_timestamp)
+            return true if @hash.nil? || @timestamp.nil?
+            return true if session_hash.nil? || session_timestamp.nil?
+
+            now = (Time.now.to_f * 1_000).to_i
+
+            return true if now - (@timestamp * 1_000) > @ttl_ms
+
+            return false if @hash == session_hash
+            return false if @timestamp > session_timestamp
+
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/broker.rb

@@ -9,8 +9,7 @@ module Karafka
           class << self
             # @return [Array<Broker>] all brokers in the cluster
             def all
-              # We do not cache here because we want the most recent state of brokers possible
-              ClusterInfo.fetch(cached: false).brokers.map do |broker|
+              ClusterInfo.fetch.brokers.map do |broker|
                 new(broker)
               end
             end

data/lib/karafka/web/ui/models/cluster_info.rb

@@ -10,26 +10,18 @@ module Karafka
           class << self
             # Gets us all the cluster metadata info
             #
-            # @param cached [Boolean] should we use cached data (true by default)
             # @return [Rdkafka::Metadata] cluster metadata info
-            def fetch(cached: true)
-              cache = ::Karafka::Web.config.ui.cache
-
-              cluster_info = cache.read(:cluster_info)
-
-              if cluster_info.nil? || !cached
-                cluster_info = cache.write(:cluster_info, Lib::Admin.cluster_info)
+            def fetch
+              Karafka::Web.config.ui.cache.fetch(:cluster_info) do
+                Lib::Admin.cluster_info
               end
-
-              cluster_info
             end
 
             # Returns us all the info about available topics from the cluster
             #
-            # @param cached [Boolean] should we use cached data (true by default)
             # @return [Array<Ui::Models::Topic>] topics details
-            def topics(cached: true)
-              fetch(cached: cached)
+            def topics
+              fetch
                 .topics
                 .map { |topic| Topic.new(topic) }
             end
@@ -37,19 +29,21 @@ module Karafka
             # Fetches us details about particular topic
             #
             # @param topic_name [String] name of the topic we are looking for
-            # @param cached [Boolean] should we use cached data (true by default)
             # @return [Ui::Models::Topic] topic details
-            def topic(topic_name, cached: true)
-              topics(cached: cached)
-                .find { |topic_data| topic_data.topic_name == topic_name }
-                .tap { |topic| topic || raise(Web::Errors::Ui::NotFoundError, topic_name) }
+            def topic(topic_name)
+              Lib::Admin
+                .topic_info(topic_name)
+                .then { |topic| Topic.new(topic) }
+            rescue Rdkafka::RdkafkaError => e
+              raise e unless e.code == :unknown_topic_or_part
+
+              raise(Web::Errors::Ui::NotFoundError, topic_name)
             end
 
             # @param topic_name [String] name of the topic we are looking for
-            # @param cached [Boolean] should we use cached data (true by default)
             # @return [Integer] number of partitions in a given topic
-            def partitions_count(topic_name, cached: true)
-              topic(topic_name, cached: cached).partition_count
+            def partitions_count(topic_name)
+              topic(topic_name).partition_count
             end
           end
         end

data/lib/karafka/web/ui/models/consumers_metrics.rb

@@ -33,7 +33,7 @@ module Karafka
             # @return [::Karafka::Messages::Message, nil] most recent state or nil if none
             def fetch
               Lib::Admin.read_topic(
-                Karafka::Web.config.topics.consumers.metrics,
+                Karafka::Web.config.topics.consumers.metrics.name,
                 0,
                 # We need to take last two and not the last because in case of a transactional
                 # producer, the last one will match the transaction commit message

data/lib/karafka/web/ui/models/consumers_state.rb

@@ -42,7 +42,7 @@ module Karafka
             # @return [::Karafka::Messages::Message, nil] most recent state or nil if none
             def fetch
               Lib::Admin.read_topic(
-                Karafka::Web.config.topics.consumers.states,
+                Karafka::Web.config.topics.consumers.states.name,
                 0,
                 # We need to take last two and not the last because in case of a transactional
                 # producer, the last one will match the transaction commit message

data/lib/karafka/web/ui/models/counters.rb

@@ -32,7 +32,7 @@ module Karafka
             MAX_ERROR_PARTITIONS.times do |partition|
               begin
                 offsets = Lib::Admin.read_watermark_offsets(
-                  ::Karafka::Web.config.topics.errors,
+                  ::Karafka::Web.config.topics.errors.name,
                   partition
                 )
               # We estimate that way instead of using `#cluster_info` to get the partitions count

data/lib/karafka/web/ui/models/health.rb

@@ -50,15 +50,17 @@ module Karafka
             # @param state [Hash]
             # @param stats [Hash] hash where we will store all the aggregated data
             def fetch_topics_data(state, stats)
-              iterate_partitions(state) do |process, consumer_group, topic, partition|
-                cg_name = consumer_group.id
+              iterate_partitions(state) do |process, consumer_group, subscription_group, topic, partition|
+                cg_id = consumer_group.id
+                sg_id = subscription_group.id
                 t_name = topic.name
                 pt_id = partition.id
 
-                stats[cg_name] ||= { topics: {} }
-                stats[cg_name][:topics][t_name] ||= {}
-                stats[cg_name][:topics][t_name][pt_id] = partition
-                stats[cg_name][:topics][t_name][pt_id][:process] = process
+                stats[cg_id] ||= { topics: {} }
+                stats[cg_id][:topics][t_name] ||= {}
+                stats[cg_id][:topics][t_name][pt_id] = partition
+                stats[cg_id][:topics][t_name][pt_id][:process] = process
+                stats[cg_id][:topics][t_name][pt_id][:subscription_group_id] = sg_id
               end
             end
 
@@ -99,7 +101,7 @@ module Karafka
                   consumer_group.subscription_groups.each do |subscription_group|
                     subscription_group.topics.each do |topic|
                       topic.partitions.each do |partition|
-                        yield(process, consumer_group, topic, partition)
+                        yield(process, consumer_group, subscription_group, topic, partition)
                       end
                     end
                   end

data/lib/karafka/web/ui/models/process.rb

@@ -74,6 +74,20 @@ module Karafka
               .flat_map(&:partitions)
               .count
           end
+
+          # @return [Boolean] consumer process data is only compatible if the version of its schema
+          #   matches the Web UI version of the schema. Some users have gradual deployment where
+          #   they slowly rollout new versions of consumers and for this time, we want to indicate
+          #   which instances have incompatible schema. This will allow us to show those processes
+          #   to indicate they exist, so users are not confused with them missing, but will also
+          #   block all capabilities until the full update of all components.
+          #
+          # @note We do not differentiate between reporting older or newer against Web UI Puma
+          #   instance. Any incompatibility will cause reporting of incompatible. That's for the
+          #   sake of simplicity as the long term goal for user is anyhow to align those.
+          def schema_compatible?
+            schema_version == ::Karafka::Web::Tracking::Consumers::Sampler::SCHEMA_VERSION
+          end
         end
       end
     end

data/lib/karafka/web/ui/models/processes.rb

@@ -45,7 +45,7 @@ module Karafka
                         .sort
 
               Lib::Admin.read_topic(
-                ::Karafka::Web.config.topics.consumers.reports,
+                ::Karafka::Web.config.topics.consumers.reports.name,
                 0,
                 # We set 10k here because we start from the latest offset of the reports, hence
                 # we will never get this much. Do do not know however exactly how many reports
@@ -83,7 +83,7 @@ module Karafka
             # @param processes [Array<Hash>]
             # @return [Array<Hash>] sorted processes data
             def sort_processes(processes)
-              processes.sort_by { |consumer| consumer[:process][:id] }
+              processes.sort_by { |consumer| consumer[:process].fetch(:id) }
             end
           end
         end

data/lib/karafka/web/ui/models/recurring_tasks/schedule.rb

@@ -22,7 +22,7 @@ module Karafka
               #   get it because requested topic/partition does not exist or nothing was present
               def current
                 messages = Karafka::Admin.read_topic(
-                  config.topics.schedules,
+                  config.topics.schedules.name,
                   0,
                   # We work here with the assumption that users won't click so fast to load
                   # more than 20 commands prior to a state flush. If that happens, this will