karafka-web 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36ff8195b930f55c0a0780a7009c1940ca807f24e2b202ce0c483dedda9d4f0b
-  data.tar.gz: 7989106b1ee525e3a7b3736bb9cea7f4db0409f2ecb23787d787262305b9f876
+  metadata.gz: 53d7f8aa3ebaa18166dbcc4ef988d88687a22c3862d77dd3d582850afe59e5d1
+  data.tar.gz: bb4066f370418c911e71108643f08c9c07f1b7ea073a4736c0fdc4805670741f
 SHA512:
-  metadata.gz: 43087044c2b58ad9a07d6fc5f216bff82d1123efb8a8a90aabf9e43d33c7322899a7bbd9eaf0cfb7b78ceed9071862bcd9cd65abaf1604ef13e957fe67a875e3
-  data.tar.gz: b26e48d1dd301f59fac2093e7fa91ae54b036430130e7f2c2a39a9f1ad284467eb20c7cf9990df33bc233df7db68c65445e3b4a0eb4781ed43f748ae851057ac
+  metadata.gz: 70ed8bcf8786cef729d9888dc7054de6a53abbd0f10d1c871c32f594dd68332f13889e9a808334c83495535b668bb2700ceb2bcdc87114a3ed98bbe340c2376d
+  data.tar.gz: 45cf0c1e9a621e4fbd718e70e9b791b976caef4faa83bd953cb4659f78ed0c962259f463c90939b160b006f49b7688bd586019da854032b05762bd40f0fb67fa

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Karafka Web Changelog
 
+## 1.0.1 (2026-08-24)
+- **[Feature]** Add a generic keyword filtering (search) box to the data-heavy Web UI listings (consumers, controls, jobs, routing, per-process subscriptions, cluster, configs, recurring tasks, the health views and the topic lists), so a specific consumer, topic or job can be found without scrolling. Flat listings also include a field selector to scope the search to a chosen attribute (Pro) (#1073).
+- [Enhancement] Track producer errors from every WaterDrop producer, not only `Karafka.producer` and `Karafka::Web.producer`. Web UI now subscribes its producer error listeners via WaterDrop's class-level (global) monitor, attaching them to each producer as it is configured, so errors from any additional producer a user creates (secondary, transactional, etc.) reach the Web UI. Attaching is idempotent per monitor and skips any listener a user already subscribed themselves, so errors are never counted twice. This also fixes a pre-existing double-counting bug where the default producer's errors were recorded twice, because the old `Karafka.producer == Karafka::Web.producer` guard never matched (the Web producer is a delegator/variant that shares the default producer's monitor), so the same monitor was subscribed twice (#952).
+- [Enhancement] Report the details Karafka publishes on a forceful shutdown (which listeners were still active and which jobs were still in processing, with their blocking status) in the Web UI error details, so a `ForcefulShutdownError` shows what was still blocking (#979).
+- [Enhancement] Show the actual replica and in-sync (ISR) broker ids (not just their counts) in the cluster and topic replication partition views. The leader is emphasized and replicas that have fallen out of sync are highlighted, turning the replication views into an at-a-glance health signal. In Pro, each broker badge links to its broker details page (#1084).
+- [Maintenance] Bump `simplecov` to `1.1.1` and stop parallel test workers from clobbering each other's `coverage/coverage.json`. simplecov `1.1.1` warns (which the test suite escalates to a hard failure) when it detects a concurrent overwrite of the JSON report, and every parallel worker shares one `coverage/` directory. Parallel workers now use the non-writing `SimpleCov::Formatter::SimpleFormatter` and only persist their raw `.resultset.json`; the human-readable report is still produced once by the single `bin/check_coverage` collation step. Non-parallel local runs keep the default HTML formatter (#1214).
+- [Maintenance] Split the oversized `ApplicationHelper` into focused helper modules (`SortingHelper`, `FormattingHelper`, `BadgesHelper`, `PartitionsHelper`), leaving `ApplicationHelper` with only app/layout/hash utilities.
+- [Fix] Force `border-collapse` on the data tables so their 1px cell borders no longer render as a doubled 2px border under daisyUI 5.7 (which switched `.table` to `border-collapse: separate`).
+- [Fix] Make columns that render a sort link actually sortable. Some tables exposed sortable headers for columns missing from the controller's allow-list, so clicking them silently did nothing: the cluster replication view (topic name, partition, leader, replicas, in-sync) and the broker config `value` column in Pro, and the low-offset column in the health offsets view.
+
 ## 1.0.0 (2026-08-05)
 - **[Breaking]** Namespace the commanding pause configuration under `config.commanding.pause`. The flat `config.commanding.pause_timeout` setting has been removed in favor of the nested `config.commanding.pause.timeout` namespace, mirroring the pause configuration namespacing introduced in Karafka.
 - [Enhancement] Link the topic, partition and offset in the Explorer's single-message metadata table to the Explorer, matching the linking on the Errors detail view. The offset points at the message currently being viewed but is kept linked so the whole topic/partition/offset coordinate is navigable (#1179).

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    karafka-web (1.0.0)
+    karafka-web (1.0.1)
       erubi (~> 1.4)
       karafka (>= 2.6.0, < 2.7.0)
       karafka-core (>= 2.6.2, < 2.7.0)
@@ -13,10 +13,10 @@ GEM
   specs:
     byebug (13.0.0)
       reline (>= 0.6.0)
-    concurrent-ruby (1.3.7)
+    concurrent-ruby (1.3.8)
     drb (2.2.3)
     erubi (1.13.1)
-    et-orbi (1.4.0)
+    et-orbi (1.4.1)
       tzinfo
     ffi (1.17.4)
     ffi (1.17.4-aarch64-linux-gnu)
@@ -32,8 +32,8 @@ GEM
     fugit (1.13.0)
       et-orbi (~> 1.4)
       raabro (~> 1.4)
-    io-console (0.8.2)
-    json (2.20.0)
+    io-console (0.9.2)
+    json (2.21.2)
     karafka (2.6.0)
       karafka-core (>= 2.6.2, < 2.7.0)
       karafka-rdkafka (>= 0.28.0)
@@ -106,31 +106,31 @@ GEM
       racc (~> 1.4)
     ostruct (0.6.3)
     prism (1.9.0)
-    raabro (1.4.0)
+    raabro (1.5.0)
     racc (1.8.1)
-    rack (3.2.6)
+    rack (3.2.7)
     rack-test (2.2.0)
       rack (>= 1.3)
     rackup (0.2.3)
       rack (>= 3.0.0.beta1)
       webrick
     rake (13.4.2)
-    reline (0.6.3)
+    reline (0.7.0)
       io-console (~> 0.5)
-    roda (3.105.0)
+    roda (3.107.0)
       rack
     ruby2_keywords (0.0.5)
-    simplecov (1.0.3)
-    tilt (2.7.0)
+    simplecov (1.1.1)
+    tilt (2.9.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     warning (1.6.0)
-    waterdrop (2.10.2)
+    waterdrop (2.10.3)
       karafka-core (>= 2.5.12, < 3.0.0)
       karafka-rdkafka (>= 0.24.0)
       zeitwerk (~> 2.3)
     webrick (1.9.2)
-    zeitwerk (2.8.2)
+    zeitwerk (2.8.3)
 
 PLATFORMS
   aarch64-linux-gnu

data/lib/karafka/web/management/actions/enable.rb

@@ -151,16 +151,9 @@ module Karafka
               ::Karafka.monitor.subscribe(listener)
             end
 
-            # Installs all the producer related listeners into Karafka default listener and
-            # into Karafka::Web listener in case it would be different than the Karafka one
-            ::Karafka::Web.config.tracking.producers.listeners.each do |listener|
-              ::Karafka.producer.monitor.subscribe(listener)
-
-              # Do not instrument twice in case only one default producer is used
-              next if ::Karafka.producer == ::Karafka::Web.producer
-
-              ::Karafka::Web.producer.monitor.subscribe(listener)
-            end
+            # Installs all the producer related listeners so that we track errors from every
+            # producer and not only the default and the Web UI ones
+            subscribe_to_producers
 
             # Installs all the UI related listeners for tracking errors from web processes
             # These listen on Karafka monitor to catch instrumented UI errors
@@ -169,6 +162,77 @@ module Karafka
             end
           end
 
+          # Subscribes the producer tracking listeners to every WaterDrop producer.
+          #
+          # Historically we only instrumented `Karafka.producer` and `Karafka::Web.producer`, so
+          # errors published by any other producer a user created (a secondary producer, a
+          # transactional one, etc.) never reached the Web UI. WaterDrop's class-level monitor
+          # announces every producer as it is configured, so we hook into it and attach our
+          # listeners to each producer's own monitor. Producers that already exist by the time Web
+          # is enabled are not announced again, so we also attach to them explicitly.
+          def subscribe_to_producers
+            @producers_tracking_mutex = Mutex.new
+
+            # A forked child inherits this Enable instance (captured by the subscriptions below)
+            # together with the tracking mutex. Had the parent been mid-subscription while forking,
+            # the child would inherit a locked mutex and deadlock on its first producer
+            # subscription. Karafka forks single-threaded, so we swap in a fresh mutex right after
+            # the fork, before any producer can be announced in the child.
+            ::Karafka.monitor.subscribe("swarm.node.after_fork") do
+              @producers_tracking_mutex = Mutex.new
+            end
+
+            # Any producer configured from now on is announced here; attach to it as it appears
+            ::WaterDrop.monitor.subscribe("producer.configured") do |event|
+              subscribe_producer_listeners(event[:producer])
+            end
+
+            # Producers that already exist will not be re-announced, so attach to them directly.
+            # `Karafka::Web.producer` is either the default producer or a variant of it, so it
+            # shares the default producer's monitor; the per-listener guard below keeps us from
+            # subscribing the same monitor twice.
+            subscribe_producer_listeners(::Karafka.producer)
+            subscribe_producer_listeners(::Karafka::Web.producer)
+          end
+
+          # Subscribes the producer tracking listeners to a single producer's monitor, skipping any
+          # listener that is already subscribed to it. This one guard covers every double-subscribe
+          # case: a variant sharing its parent's monitor, the default and Web producers being the
+          # same monitor, a producer re-announced by the global monitor, and a user having wired
+          # the Web UI producer tracking to their own producer by hand. Subscribing twice would
+          # track each of the producer's events twice.
+          #
+          # @param producer [WaterDrop::Producer, WaterDrop::Producer::Variant] producer whose
+          #   monitor we want to instrument
+          def subscribe_producer_listeners(producer)
+            monitor = producer.monitor
+
+            @producers_tracking_mutex.synchronize do
+              ::Karafka::Web.config.tracking.producers.listeners.each do |listener|
+                next if producer_listener_subscribed?(monitor, listener)
+
+                monitor.subscribe(listener)
+              end
+            end
+          end
+
+          # @param monitor [Object] producer monitor
+          # @param listener [Object] producer tracking listener
+          # @return [Boolean] true if the listener is already subscribed to any of the monitor
+          #   events, false otherwise
+          def producer_listener_subscribed?(monitor, listener)
+            # The default monitor exposes its subscribers, but a non-default notifications backend
+            # may not. When we cannot inspect them, we subscribe rather than risk missing errors.
+            return false unless monitor.respond_to?(:listeners)
+
+            # Snapshot the per-event listener arrays (`#values`) before scanning them, so a
+            # concurrent subscription to the same monitor from outside this class cannot mutate
+            # what we iterate.
+            monitor.listeners.values.any? do |event_listeners|
+              event_listeners.include?(listener)
+            end
+          end
+
           # In most cases we want to close the producer if possible.
           # While we cannot do it easily in user processes and we should rely on WaterDrop
           # finalization logic, we can do it in `karafka server` on terminate

data/lib/karafka/web/pro/ui/app.rb

@@ -36,6 +36,11 @@ module Karafka
       module Ui
         # Main Roda Web App that servers all the metrics and stats
         class App < Web::Ui::Base
+          # Filtering (search) is a Pro-only feature, so its helpers are mixed in here rather than in
+          # the shared OSS base
+          include Helpers::FilteringHelper
+          include Helpers::TopicsFilteringHelper
+
           opts[:root] = Karafka::Web.gem_root.join("lib/karafka/web/pro/ui")
 
           instance_exec(&CONTEXT_DETAILS)
@@ -62,6 +67,14 @@ module Karafka
             raise(Errors::Ui::ForbiddenError)
           end
 
+          # Builds the Pro request params, which add the filtering (search) readers on top of the
+          # OSS ones. Overriding here keeps the filtering param parsing out of the shared params.
+          #
+          # @return [Controllers::Requests::Params] curated Pro params
+          def params
+            Controllers::Requests::Params.new(request.params)
+          end
+
           # Sub-routes for given pieces of the Web UI
           SUB_ROUTES = [
             # Asset handling is exactly the same in both cases

data/lib/karafka/web/pro/ui/controllers/base_controller.rb

@@ -36,6 +36,10 @@ module Karafka
         module Controllers
           # Base Pro controller
           class BaseController < Web::Ui::Controllers::BaseController
+            # Filtering (search) is a Pro-only feature, so it is mixed in here rather than in the
+            # shared OSS base controller
+            include Lib::Filtering
+
             private
 
             # @return [Karafka::Web::Pro::Ui::Lib::Features] features fetcher

data/lib/karafka/web/pro/ui/controllers/cluster_controller.rb

@@ -34,20 +34,39 @@ module Karafka
       module Ui
         module Controllers
           # Cluster details controller
-          class ClusterController < Web::Ui::Controllers::ClusterController
+          class ClusterController < BaseController
+            # A single controller serves the nodes (index), broker config (show) and replication
+            # listings, so the sortable set is the union of every column those tables expose
             self.sortable_attributes = %w[
               id
               name
+              port
+              value
               default?
               read_only?
               synonym?
               sensitive?
-              port
+              topic_name
+              partition_id
+              leader
+              replica_count
+              in_sync_replica_brokers
             ].freeze
 
+            # Each action renders different columns, so we scope the filterable fields per action to
+            # what it actually displays
+            self.filterable_attributes = {
+              index: %i[id name],
+              show: %i[name value],
+              replication: %i[topic_name]
+            }.freeze
+
+            # Cluster state should always be fresh and not from cache
+            before { cache.clear }
+
             # Lists available brokers in the cluster
             def index
-              @brokers = refine(Models::Broker.all)
+              @brokers = filter(sort(Models::Broker.all))
 
               render
             end
@@ -58,10 +77,53 @@ module Karafka
             def show(broker_id)
               @broker = Models::Broker.find(broker_id)
 
-              @configs = refine(@broker.configs)
+              @configs = filter(sort(@broker.configs))
+
+              render
+            end
+
+            # List partitions replication details (same as OSS, plus Pro filtering)
+            def replication
+              @partitions, last_page = Paginators::Arrays.call(
+                filter(sort(replication_partitions)),
+                @params.current_page
+              )
+
+              paginate(@params.current_page, !last_page)
 
               render
             end
+
+            private
+
+            # Expands the displayable cluster topics into one flat row per partition, which the
+            # replication table renders, sorts, filters and paginates. Each row is a partition
+            # carrying its topic (and topic name, so it can be sorted/filtered by name).
+            #
+            # @return [Array<Hash>] partition rows
+            def replication_partitions
+              displayable_topics.flat_map do |topic|
+                topic[:partitions].map do |partition|
+                  partition.merge(
+                    topic: topic,
+                    topic_name: topic.fetch(:topic_name)
+                  )
+                end
+              end
+            end
+
+            # @return [Array<Hash>] cluster topics to display in an alphabetical order, with
+            #   internal topics excluded unless the visibility config allows them
+            def displayable_topics
+              all = Models::ClusterInfo
+                .fetch
+                .topics
+                .sort_by { |topic| topic[:topic_name] }
+
+              return all if ::Karafka::Web.config.ui.visibility.internal_topics
+
+              all.reject { |topic| topic[:topic_name].start_with?("__") }
+            end
           end
         end
       end

data/lib/karafka/web/pro/ui/controllers/consumers/consumers_controller.rb

@@ -69,13 +69,20 @@ module Karafka
                 pending_jobs_count
               ].freeze
 
+              # The list filters processes by their id/topics/tags, while the per-process
+              # subscriptions view filters (at the view level) by topic/consumer/subscription group
+              self.filterable_attributes = {
+                default: %i[id subscribed_topics tags],
+                subscriptions: %i[topic consumer_group subscription_group]
+              }.freeze
+
               # Consumers list
               def index
                 @current_state = Models::ConsumersState.current!
                 @counters = Models::Counters.new(@current_state)
 
                 @processes, last_page = Paginators::Arrays.call(
-                  refine(Models::Processes.active(@current_state)),
+                  filter(sort(Models::Processes.active(@current_state))),
                   @params.current_page
                 )
 
@@ -110,7 +117,7 @@ module Karafka
                   # the underlying hashes for sorting
                   consumer_group.subscription_groups.flat_map(&:topics).flat_map(&:partitions)
 
-                  refine(consumer_group)
+                  sort(consumer_group)
                 end
 
                 render

data/lib/karafka/web/pro/ui/controllers/consumers/controls_controller.rb

@@ -44,6 +44,12 @@ module Karafka
                 lag_hybrid
               ].freeze
 
+              self.filterable_attributes = %i[
+                id
+                subscribed_topics
+                tags
+              ].freeze
+
               # Displays list of consumer processes + options to manage them
               def index
                 features.commanding!

data/lib/karafka/web/pro/ui/controllers/consumers/jobs_controller.rb

@@ -50,6 +50,12 @@ module Karafka
                 updated_at
               ].freeze
 
+              self.filterable_attributes = %i[
+                topic
+                consumer
+                type
+              ].freeze
+
               # Shows all running jobs of a consumer
               # @param process_id [String]
               def running(process_id)
@@ -57,7 +63,7 @@ module Karafka
 
                 @running_jobs = @process.jobs.running
 
-                refine(@running_jobs)
+                filter(sort(@running_jobs))
 
                 render
               end
@@ -69,7 +75,7 @@ module Karafka
 
                 @pending_jobs = @process.jobs.pending
 
-                refine(@pending_jobs)
+                filter(sort(@pending_jobs))
 
                 render
               end

data/lib/karafka/web/pro/ui/controllers/dlq_controller.rb

@@ -35,6 +35,10 @@ module Karafka
         module Controllers
           # DLQ topics overview
           class DlqController < BaseController
+            self.filterable_attributes = %w[
+              topic_name
+            ].freeze
+
             # Lists DLQ topics
             def index
               topics = Karafka::App.consumer_groups.flat_map(&:topics).flat_map(&:to_a)
@@ -52,6 +56,8 @@ module Karafka
                 .select { |topic| dlq?(dlq_topic_patterns, topic[:topic_name]) }
                 .sort_by { |topic| topic[:topic_name] }
 
+              @dlq_topics = filter(@dlq_topics)
+
               render
             end
 

data/lib/karafka/web/pro/ui/controllers/explorer/explorer_controller.rb

@@ -36,6 +36,10 @@ module Karafka
           module Explorer
             # Data explorer controller
             class ExplorerController < BaseController
+              self.filterable_attributes = %w[
+                topic_name
+              ].freeze
+
               # Lists all the topics we can explore
               def index
                 @topics = Models::ClusterInfo
@@ -46,6 +50,8 @@ module Karafka
                   @topics.reject! { |topic| topic[:topic_name].start_with?("__") }
                 end
 
+                @topics = filter(@topics)
+
                 render
               end
 

data/lib/karafka/web/pro/ui/controllers/health_controller.rb

@@ -47,6 +47,7 @@ module Karafka
               committed_offset_fd
               stored_offset
               stored_offset_fd
+              lo_offset
               hi_offset
               hi_offset_fd
               ls_offset
@@ -58,16 +59,29 @@ module Karafka
               poll_state_ch
             ].freeze
 
+            # The health stats are a tree keyed by consumer group and then topic name, so we filter
+            # on those keys rather than on record attributes. Topic keys live under `:topics` in the
+            # overview but directly under the consumer group in the cluster lags view; the key alias
+            # descends leniently, so one declaration covers both shapes without reshaping the data.
+            self.filterable_attributes = [
+              Lib::Filtering.key(:topic, under: :topics),
+              Lib::Filtering.key(:consumer_group)
+            ].freeze
+
             # Displays the current system state
             def overview
               current_state = Models::ConsumersState.current!
               @stats = Models::Health.current(current_state)
 
-              # Refine only on a per topic basis not to resort higher levels
+              # Sort only on a per topic basis not to resort higher levels
               @stats.each_value do |cg_details|
-                cg_details.each_value { |topic_details| refine(topic_details) }
+                cg_details.each_value { |topic_details| sort(topic_details) }
               end
 
+              # Narrow the whole tree down to the consumer groups/topics matching the current filter
+              # (if any). It is safe to prune in place here as the stats are built fresh per request.
+              filter(@stats)
+
               render
             end
 
@@ -86,9 +100,11 @@ module Karafka
               @stats = Models::Health.cluster_lags_with_offsets
 
               @stats.each_value do |cg_details|
-                cg_details.each_value { |topic_details| refine(topic_details) }
+                cg_details.each_value { |topic_details| sort(topic_details) }
               end
 
+              filter(@stats)
+
               render
             end
 

data/lib/karafka/web/pro/ui/controllers/jobs_controller.rb

@@ -35,6 +35,10 @@ module Karafka
         module Controllers
           # Displays list of active jobs
           class JobsController < Web::Ui::Controllers::JobsController
+            # This Pro controller inherits the OSS jobs controller (which has no filtering), so it
+            # pulls in the Pro-only filtering concern directly
+            include Lib::Filtering
+
             self.sortable_attributes = %w[
               id
               topic
@@ -46,6 +50,27 @@ module Karafka
               committed_offset
               updated_at
             ].freeze
+
+            self.filterable_attributes = %i[
+              id
+              topic
+              consumer
+              type
+            ].freeze
+
+            private
+
+            # Adds Pro-only filtering on top of the OSS sort/paginate seam
+            #
+            # @param jobs_total [Array] aggregated jobs
+            def paginate_jobs(jobs_total)
+              @jobs, last_page = Paginators::Arrays.call(
+                filter(sort(jobs_total)),
+                @params.current_page
+              )
+
+              paginate(@params.current_page, !last_page)
+            end
           end
         end
       end

data/lib/karafka/web/pro/ui/controllers/recurring_tasks_controller.rb

@@ -35,6 +35,10 @@ module Karafka
         module Controllers
           # Controller for viewing and managing recurring tasks
           class RecurringTasksController < Web::Ui::Controllers::ClusterController
+            # This Pro controller inherits the OSS cluster controller (which has no filtering), so it
+            # pulls in the Pro-only filtering concern directly
+            include Lib::Filtering
+
             self.sortable_attributes = %w[
               id
               enabled
@@ -43,11 +47,16 @@ module Karafka
               next_time
             ].freeze
 
+            self.filterable_attributes = %i[
+              id
+              cron
+            ].freeze
+
             # Displays the current schedule
             def schedule
               @schedule = Models::RecurringTasks::Schedule.current
 
-              @tasks = refine(@schedule.tasks) if @schedule
+              @tasks = filter(sort(@schedule.tasks)) if @schedule
 
               render
             end

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

@@ -0,0 +1,67 @@
+# 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.
+#
+# The author retains all right, title, and interest in this software,
+# including all copyrights, patents, and other intellectual property rights.
+# No patent rights are granted under this license.
+#
+# PROHIBITED:
+# - Use without a valid commercial license
+# - Redistribution, modification, or derivative works without authorization
+# - Reverse engineering, decompilation, or disassembly of this software
+# - 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
+#
+# Receipt, viewing, or possession of this software does not convey or
+# imply any license or right beyond those expressly stated above.
+#
+# License: https://karafka.io/docs/Pro-License-Comm/
+# Contact: contact@karafka.io
+
+module Karafka
+  module Web
+    module Pro
+      module Ui
+        module Controllers
+          # Namespace for the Pro request wrappers (params, etc.).
+          module Requests
+            # Extends the OSS request params with the Pro-only filtering (search) readers, so the
+            # filtering query parsing never lives in the shared OSS params.
+            class Params < Web::Ui::Controllers::Requests::Params
+              # @return [String] filtering keyword or empty string when no filtering is requested.
+              #   Supports both the plain `filter=keyword` form (keyword filtering) and the
+              #   field-selectable `filter[field]=...&filter[value]=...` form (its value part).
+              def current_filter
+                @current_filter ||= begin
+                  filter = @request_params["filter"]
+
+                  filter.is_a?(Hash) ? filter["value"].to_s.strip : filter.to_s.strip
+                end
+              end
+
+              # @return [String] the attribute selected for field-scoped filtering, or empty string
+              #   when filtering across all allowed attributes (keyword filtering)
+              def current_filter_field
+                @current_filter_field ||= begin
+                  filter = @request_params["filter"]
+
+                  filter.is_a?(Hash) ? filter["field"].to_s.strip : ""
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end