karafka-web 0.10.4 → 0.11.0

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

@@ -129,76 +129,6 @@ module Karafka
             parts.join('.')
           end
 
-          # @param time [Float] UTC time float
-          # @return [String] relative time tag for timeago.js
-          def relative_time(time)
-            stamp = Time.at(time).getutc.iso8601(3)
-            %(<time class="ltr" dir="ltr" title="#{stamp}" datetime="#{stamp}">#{time}</time>)
-          end
-
-          # @param time [Time] time object we want to present with detailed ms label
-          # @return [String] span tag with raw timestamp as a title and time as a value
-          def time_with_label(time)
-            stamp = (time.to_f * 1000).to_i
-
-            %(<span title="#{stamp}">#{time}</span>)
-          end
-
-          # Converts raw second count into human readable form like "12.2 minutes". etc based on
-          # number of seconds
-          #
-          # @param seconds [Numeric] number of seconds
-          # @return [String] human readable time
-          def human_readable_time(seconds)
-            case seconds
-            when 0..59
-              "#{seconds.round(2)} seconds"
-            when 60..3_599
-              minutes = seconds / 60.0
-              "#{minutes.round(2)} minutes"
-            when 3_600..86_399
-              hours = seconds / 3_600.0
-              "#{hours.round(2)} hours"
-            else
-              days = seconds / 86_400.0
-              "#{days.round(2)} days"
-            end
-          end
-
-          # @param state [String] poll state
-          # @param state_ch [Integer] time until next change of the poll state
-          #   (from paused to active)
-          # @return [String] span tag with label and title with change time if present
-          def poll_state_with_change_time_label(state, state_ch)
-            year_in_seconds = 131_556_926
-            state_ch_in_seconds = state_ch / 1_000.0
-
-            # If state is active, there is no date of change
-            if state == 'active'
-              %(
-                <span class="badge #{kafka_state_badge(state)}">#{state}</span>
-              )
-            elsif state_ch_in_seconds > year_in_seconds
-              %(
-                <span
-                  class="badge #{kafka_state_badge(state)}"
-                  title="until manual resume"
-                >
-                  #{state}
-                </span>
-              )
-            else
-              %(
-                <span
-                  class="badge #{kafka_state_badge(state)} time-title"
-                  title="#{Time.now + state_ch_in_seconds}"
-                >
-                  #{state}
-                </span>
-              )
-            end
-          end
-
           # @param lag [Integer] lag
           # @return [String] lag if correct or `N/A` with labeled explanation
           # @see #offset_with_label
@@ -223,13 +153,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/helpers/time_helper.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Helpers
+        # Helper with time-related methods
+        module TimeHelper
+          # @param time [Float] UTC time float
+          # @return [String] relative time tag for timeago.js
+          def relative_time(time)
+            stamp = Time.at(time).getutc.iso8601(3)
+            %(<time class="ltr" dir="ltr" title="#{stamp}" datetime="#{stamp}">#{time}</time>)
+          end
+
+          # @param time [Time] time object we want to present with detailed ms label
+          # @return [String] span tag with raw timestamp as a title and time as a value
+          def time_with_label(time)
+            stamp = (time.to_f * 1000).to_i
+
+            %(<span title="#{stamp}">#{time}</span>)
+          end
+
+          # Converts raw second count into human readable form like "12.2 minutes". etc based on
+          # number of seconds
+          #
+          # @param seconds [Numeric] number of seconds
+          # @return [String] human readable time
+          def human_readable_time(seconds)
+            case seconds
+            when 0..59
+              "#{seconds.round(2)} seconds"
+            when 60..3_599
+              minutes = seconds / 60.0
+              "#{minutes.round(2)} minutes"
+            when 3_600..86_399
+              hours = seconds / 3_600.0
+              "#{hours.round(2)} hours"
+            else
+              days = seconds / 86_400.0
+              "#{days.round(2)} days"
+            end
+          end
+
+          # @param state [String] poll state
+          # @param state_ch [Integer] time until next change of the poll state
+          #   (from paused to active)
+          # @return [String] span tag with label and title with change time if present
+          def poll_state_with_change_time_label(state, state_ch)
+            year_in_seconds = 131_556_926
+            state_ch_in_seconds = state_ch / 1_000.0
+
+            # If state is active, there is no date of change
+            if state == 'active'
+              %(
+                <span class="badge #{kafka_state_badge(state)}">#{state}</span>
+              )
+            elsif state_ch_in_seconds > year_in_seconds
+              %(
+                <span
+                  class="badge #{kafka_state_badge(state)}"
+                  title="until manual resume"
+                >
+                  #{state}
+                </span>
+              )
+            else
+              %(
+                <span
+                  class="badge #{kafka_state_badge(state)} time-title"
+                  title="#{Time.now + state_ch_in_seconds}"
+                >
+                  #{state}
+                </span>
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Helpers
+        # Helper module for formatting Kafka topic and partition information
+        # in various contexts within the Karafka Web UI.
+        #
+        # This module provides consistent formatting for topic-partition assignments
+        # across different display contexts like inline text, labels, and identifiers.
+        #
+        # @see https://karafka.io/docs/Development-Naming-Conventions
+        module TopicsHelper
+          # Default limit for displaying partitions before truncation
+          DEFAULT_LIMIT = 5
+
+          # Formats topic and partitions for inline text display in views.
+          #
+          # This method is optimized for compact display in assignments, logs, and
+          # other inline contexts where space is limited.
+          #
+          # @param topic [String] the Kafka topic name
+          # @param partitions [Array<Integer>, Integer] partition number(s) to format
+          # @param limit [Integer] maximum number of partitions to display before truncation
+          # @return [String] formatted topic-partition string
+          #
+          # @example Single partition
+          #   topics_assignment_text("user-events", 0)
+          #   # => "user-events-[0]"
+          #
+          # @example Multiple consecutive partitions
+          #   topics_assignment_text("user-events", [0, 1, 2, 3])
+          #   # => "user-events-[0-3]"
+          #
+          # @example Multiple non-consecutive partitions
+          #   topics_assignment_text("user-events", [0, 2, 4])
+          #   # => "user-events-[0,2,4]"
+          #
+          # @example Truncated partitions list
+          #   topics_assignment_text("user-events", [0, 1, 2, 3, 4, 5, 6], limit: 3)
+          #   # => "user-events-[0,1,2...]"
+          #
+          # @example Empty partitions
+          #   topics_assignment_text("user-events", [])
+          #   # => "user-events"
+          def topics_assignment_text(topic, partitions, limit: DEFAULT_LIMIT)
+            partitions = Array(partitions)
+
+            if partitions.empty?
+              topic
+            elsif partitions.size == 1
+              "#{topic}-[#{partitions.first}]"
+            else
+              sorted_partitions = partitions.map(&:to_i).sort
+              # Check for consecutive first (best representation)
+              if topics_consecutive?(sorted_partitions) && sorted_partitions.size > 2
+                "#{topic}-[#{sorted_partitions.first}-#{sorted_partitions.last}]"
+              # Apply limit if specified and partitions exceed it
+              elsif limit && sorted_partitions.size > limit
+                displayed_partitions = sorted_partitions.first(limit)
+                "#{topic}-[#{displayed_partitions.join(',')}...]"
+              else
+                "#{topic}-[#{sorted_partitions.join(',')}]"
+              end
+            end
+          end
+
+          # Formats topic and partitions for human-readable labels and headers.
+          #
+          # This method provides more descriptive formatting suitable for page titles,
+          # section headers, and other contexts where additional context is helpful.
+          #
+          # @param topic [String] the Kafka topic name
+          # @param partitions [Array<Integer>, Integer] partition number(s) to format
+          # @param limit [Integer] maximum number of partitions to display before truncation
+          # @return [String] formatted topic-partition label with additional context
+          #
+          # @example Consecutive partitions with count
+          #   topics_assignment_label("user-events", [0, 1, 2, 3])
+          #   # => "user-events-[0-3] (4 partitions total)"
+          #
+          # @example Truncated with remaining count
+          #   topics_assignment_label("user-events", [0, 1, 2, 3, 4, 5], limit: 3)
+          #   # => "user-events-[0,1,2] (+3 more)"
+          #
+          # @example Non-consecutive partitions
+          #   topics_assignment_label("user-events", [0, 2, 4])
+          #   # => "user-events-[0,2,4]"
+          def topics_assignment_label(topic, partitions, limit: DEFAULT_LIMIT)
+            partitions = Array(partitions)
+
+            sorted_partitions = partitions.map(&:to_i).sort
+            if topics_consecutive?(sorted_partitions)
+              "#{topic}-[#{sorted_partitions.first}-#{sorted_partitions.last}] " \
+                "(#{partitions.size} partitions total)"
+            elsif sorted_partitions.size > limit
+              displayed = sorted_partitions.first(limit)
+              remaining = sorted_partitions.size - limit
+              "#{topic}-[#{displayed.join(',')}] (+#{remaining} more)"
+            else
+              "#{topic}-[#{sorted_partitions.join(',')}]"
+            end
+          end
+
+          # Creates a specific identifier for topic-partition combinations.
+          #
+          # This method generates consistent identifiers used in metrics collection,
+          # cache keys, and other contexts requiring unique topic-partition identification.
+          #
+          # @param topic [String] the Kafka topic name
+          # @param partition [Integer] the partition number
+          # @return [String] formatted topic-partition identifier
+          #
+          # @example Basic identifier
+          #   topics_partition_identifier("user-events", 0)
+          #   # => "user-events-0"
+          #
+          # @example Used for cache keys
+          #   cache_key = topics_partition_identifier("orders", 3)
+          #   Rails.cache.fetch(cache_key) { expensive_operation }
+          def topics_partition_identifier(topic, partition)
+            "#{topic}-#{partition}"
+          end
+
+          private
+
+          # Checks if an array of sorted integers contains consecutive numbers.
+          #
+          # This helper method determines whether partition numbers form a continuous
+          # sequence, which allows for more compact display formatting.
+          #
+          # @param sorted_array [Array<Integer>] array of sorted integers to check
+          # @return [Boolean] true if all numbers are consecutive, false otherwise
+          #
+          # @example Consecutive numbers
+          #   topics_consecutive?([1, 2, 3, 4])  # => true
+          #
+          # @example Non-consecutive numbers
+          #   topics_consecutive?([1, 3, 5, 7])  # => false
+          #
+          # @example Single element (not consecutive)
+          #   topics_consecutive?([1])  # => false
+          #
+          # @example Empty array (not consecutive)
+          #   topics_consecutive?([])  # => false
+          def topics_consecutive?(sorted_array)
+            return false if sorted_array.size < 2
+
+            sorted_array.each_cons(2).all? { |a, b| b == a + 1 }
+          end
+        end
+      end
+    end
+  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