roundhouse_ui 0.9.0 → 0.10.0

data/lib/roundhouse_ui/duration_collector.rb

@@ -1,8 +1,8 @@
 module RoundhouseUi
   # Opt-in server middleware that records per-class execution time, so the UI can
   # answer "which job classes are slow?" — something Sidekiq doesn't track. Two
-  # cheap Redis writes per job (a counter + a summed-ms float). Off by default;
-  # enable in your Sidekiq server config:
+  # cheap Redis writes per job (a counter + a summed-ms float), pipelined into a
+  # single round-trip. Off by default; enable in your Sidekiq server config:
   #
   #   Sidekiq.configure_server do |config|
   #     config.server_middleware { |chain| chain.add RoundhouseUi::DurationCollector }
@@ -22,9 +22,16 @@ module RoundhouseUi
     def record(klass, elapsed_ms)
       return unless klass
 
+      commands = [
+        [ "HINCRBY", KEY, "#{klass}\x00count", 1 ],
+        [ "HINCRBYFLOAT", KEY, "#{klass}\x00ms", elapsed_ms ]
+      ]
       Sidekiq.redis do |conn|
-        conn.call("HINCRBY", KEY, "#{klass}\x00count", 1)
-        conn.call("HINCRBYFLOAT", KEY, "#{klass}\x00ms", elapsed_ms)
+        if conn.respond_to?(:pipelined) # redis-client and redis-rb 4.5+: one round-trip
+          conn.pipelined { |pipe| commands.each { |c| pipe.call(*c) } }
+        else
+          commands.each { |c| conn.call(*c) }
+        end
       end
     rescue => e
       # Metrics collection must never break a job.

data/lib/roundhouse_ui/error_groups.rb

@@ -14,6 +14,7 @@ module RoundhouseUi
     def initialize(query: nil, limit: DEFAULT_SCAN_LIMIT)
       @query = query.to_s.strip
       @limit = limit
+      @tag_cache = {}
     end
 
     def call
@@ -34,12 +35,22 @@ module RoundhouseUi
       end
 
       list = groups.values.sort_by { |g| -g[:count] }
-      list = list.select { |g| "#{g[:klass]} #{g[:error]}".downcase.include?(@query.downcase) } if @query.present?
+      list = list.select { |g| matches?(g) } if @query.present?
       Result.new(groups: list, scanned: scanned, truncated: truncated)
     end
 
     private
 
+    # Tag values are part of the haystack here for the same reason they are on
+    # the job sets: typing a squad name should find that squad's failures. A
+    # group's entries all share a class, so the tag is constant for the group
+    # and resolves once per group rather than per scanned entry.
+    def matches?(group)
+      haystack = [ group[:klass], group[:error] ]
+      haystack.concat(Tags.for(klass: group[:klass], item: {}, cache: @tag_cache).values) if RoundhouseUi.job_tags
+      haystack.join(" ").downcase.include?(@query.downcase)
+    end
+
     # Sidekiq's native sets, plus the sidekiq-failures `failed` set when opted in
     # and loaded. Its FailureSet is a Sidekiq::JobSet, so it iterates like the rest.
     def sources

data/lib/roundhouse_ui/pause.rb

@@ -7,30 +7,59 @@ module RoundhouseUi
   # Paused queue names live in a Redis set. RoundhouseUi::Fetch consults this set
   # and skips paused queues when pulling work, so a paused queue stops being
   # consumed without stopping the worker process.
+  #
+  # When Sidekiq Pro is loaded we defer to *its* registry instead (see .native?).
+  # Pro reopens Sidekiq::Queue with pause!/unpause!/paused? and prepends pause
+  # support onto Sidekiq::BasicFetch, so pausing is already enforced with no
+  # Roundhouse fetcher installed — and Pro's key ("paused") is not ours
+  # ("roundhouse:paused"), so writing our own set there would do nothing.
   module Pause
     KEY        = "roundhouse:paused"
     FETCH_FLAG = "roundhouse:fetch_alive" # liveness beacon set by the fetcher
+    PRO_KEY    = "paused" # Sidekiq Pro's own registry
 
     module_function
 
+    # True when Sidekiq Pro's queue-pause API is available. Feature-detected on
+    # the method rather than `defined?(Sidekiq::Pro)` so it tracks the actual
+    # capability across Pro versions. Cheap (no Redis), so it isn't memoized —
+    # loading Pro mid-process would otherwise be missed.
+    def native?
+      defined?(::Sidekiq::Queue) && ::Sidekiq::Queue.method_defined?(:pause!)
+    end
+
+    # Under Pro, go through Sidekiq::Queue#pause! rather than writing PRO_KEY
+    # ourselves: Pro's fetchers read that set once at startup and afterwards only
+    # update on the "pro:config" pubsub message that pause! publishes. A bare
+    # SADD would leave running workers pulling the queue until they restarted.
     def pause!(queue)
+      return ::Sidekiq::Queue.new(queue.to_s).pause! if native?
+
       Sidekiq.redis { |conn| conn.call("SADD", KEY, queue.to_s) }
     end
 
     def unpause!(queue)
+      return ::Sidekiq::Queue.new(queue.to_s).unpause! if native?
+
       Sidekiq.redis { |conn| conn.call("SREM", KEY, queue.to_s) }
     end
 
     def paused?(queue)
-      Sidekiq.redis { |conn| conn.call("SISMEMBER", KEY, queue.to_s) } == 1
+      Sidekiq.redis { |conn| conn.call("SISMEMBER", key, queue.to_s) } == 1
     end
 
     def paused_queues
-      Sidekiq.redis { |conn| conn.call("SMEMBERS", KEY) }.sort
+      Sidekiq.redis { |conn| conn.call("SMEMBERS", key) }.sort
     end
 
     def paused_set
-      Set.new(Sidekiq.redis { |conn| conn.call("SMEMBERS", KEY) })
+      Set.new(Sidekiq.redis { |conn| conn.call("SMEMBERS", key) })
+    end
+
+    # Which registry reads come from. Reads are plain set lookups in both cases
+    # (no pubsub involved), so they can share one implementation.
+    def key
+      native? ? PRO_KEY : KEY
     end
 
     # Given the redis queue keys BasicFetch would poll (e.g. "queue:default"),
@@ -52,7 +81,13 @@ module RoundhouseUi
 
     # True when a RoundhouseUi::Fetch has reported in recently — i.e. pausing
     # will take effect. When false, the UI warns instead of pretending.
+    #
+    # Under Pro no beacon is needed: Pro prepends pause support onto
+    # Sidekiq::BasicFetch (and SuperFetch honors it too), so any Pro worker
+    # enforces pauses whether or not our fetcher is installed.
     def fetch_installed?
+      return true if native?
+
       Sidekiq.redis { |conn| conn.call("EXISTS", FETCH_FLAG) } == 1
     end
   end

data/lib/roundhouse_ui/tags.rb

@@ -0,0 +1,115 @@
+module RoundhouseUi
+  # Resolves host-defined tags for a job at read time (no middleware, no
+  # storage — works on every backend and applies retroactively to jobs already
+  # in the sets). The host supplies the resolver; see ADR 0002.
+  #
+  #   RoundhouseUi.job_tags = RoundhouseUi::Tags.from_constant(:OWNER, as: :squad)
+  #   # or any callable:
+  #   RoundhouseUi.job_tags = ->(klass:, item:) { { squad: :growth } }
+  #
+  # Contract: resolver output is normalized to string keys/values, masked via
+  # Redaction (redact_args patterns apply to tag keys), and a raising resolver
+  # yields no tags — tagging must never break a page.
+  module Tags
+    EMPTY = {}.freeze
+
+    module_function
+
+    # Tags for one job entry, as a { "key" => "value" } Hash (EMPTY when no
+    # resolver is configured, the resolver declines, or it raises).
+    #
+    # `klass`/`item` come from the backend entry (entry.klass / entry.item);
+    # the ActiveJob adapter wrapper is unwrapped here, so resolvers always see
+    # the real job class. Pass a Hash as `cache` to memoize per class across a
+    # request — unused (and unneeded) in per-job mode.
+    def for(klass:, item:, cache: nil)
+      resolver = RoundhouseUi.job_tags
+      return EMPTY unless resolver
+
+      effective = effective_klass(klass, item)
+      return EMPTY unless effective
+
+      if RoundhouseUi.job_tags_per_job
+        # Per-job mode still memoizes, keyed by jid rather than class: a job's
+        # tags cannot change within one request, and the same entry is resolved
+        # twice otherwise — once while scanning, once when its badge renders.
+        jid = item["jid"] if item.is_a?(Hash)
+        return resolve(resolver, effective, item) unless cache && jid
+
+        cache.key?(jid) ? cache[jid] : cache[jid] = resolve(resolver, effective, item)
+      elsif cache
+        # Class-cached mode: item is withheld (deliberately — see resolve).
+        cache.key?(effective) ? cache[effective] : cache[effective] = resolve(resolver, effective, nil)
+      else
+        resolve(resolver, effective, nil)
+      end
+    end
+
+    # The class-constant convention (Trainual's OWNER pattern) as a resolver:
+    #
+    #   RoundhouseUi.job_tags = RoundhouseUi::Tags.from_constant(:OWNER, as: :squad)
+    #
+    # Tags every job whose class (or ancestor — inherited constants count, so a
+    # base-class OWNER covers subclasses) defines the constant.
+    def from_constant(const_name, as: const_name.to_s.downcase)
+      lambda do |klass:, item:|
+        k = klass.to_s.safe_constantize
+        { as => k.const_get(const_name) } if k&.const_defined?(const_name)
+      end
+    end
+
+    # The declared filter vocabulary, normalized to { "key" => ["value", ...] },
+    # or nil when the host declared none (the filter UI then discovers values
+    # from the entries it scans). Both the whole setting and individual values
+    # may be callables, so vocabularies can be dynamic.
+    def filters
+      declared = RoundhouseUi.tag_filters
+      declared = declared.call if declared.respond_to?(:call)
+      return nil unless declared.is_a?(Hash)
+
+      declared.each_with_object({}) do |(key, values), out|
+        values = values.call if values.respond_to?(:call)
+        out[key.to_s] = Array(values).map(&:to_s)
+      end
+    rescue => e
+      warn_once("tag_filters failed: #{e.message}")
+      nil
+    end
+
+    # Does a resolved tag Hash match a key/value filter? Exact match on the
+    # normalized (post-redaction) value — so a redacted tag matches only its
+    # mask, and the filter can't be used to probe redacted values.
+    def match?(tags, key, value)
+      tags[key.to_s] == value.to_s
+    end
+
+    # -- internals ----------------------------------------------------------
+
+    # ActiveJob-on-Sidekiq stores the adapter's JobWrapper in item["class"] and
+    # the real job class in item["wrapped"]; Solid Queue and raw Sidekiq
+    # workers put the real class in klass. Resolvers always get the real one.
+    def effective_klass(klass, item)
+      wrapped = item["wrapped"] if item.is_a?(Hash)
+      (wrapped || klass)&.to_s
+    end
+
+    # `item` is nil in class-cached mode: an args-reading resolver cached by
+    # class would poison the cache with first-job-wins values — withholding the
+    # payload makes it fail deterministically (rescued → no tags) instead.
+    # Hosts that need the payload set RoundhouseUi.job_tags_per_job = true.
+    def resolve(resolver, klass, item)
+      tags = resolver.call(klass: klass, item: item)
+      return EMPTY unless tags.is_a?(Hash)
+
+      normalized = tags.each_with_object({}) { |(k, v), out| out[k.to_s] = v.to_s }
+      Redaction.apply(normalized)
+    rescue => e
+      warn_once("job_tags resolver failed for #{klass}: #{e.message}")
+      EMPTY
+    end
+
+    def warn_once(message)
+      Rails.logger&.warn("[roundhouse] #{message}") if defined?(Rails)
+    end
+  end
+end

data/lib/roundhouse_ui/version.rb

@@ -1,3 +1,3 @@
 module RoundhouseUi
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/lib/roundhouse_ui.rb

@@ -7,6 +7,7 @@ require "roundhouse_ui/snapshots"
 require "roundhouse_ui/observability"
 require "roundhouse_ui/audit"
 require "roundhouse_ui/redaction"
+require "roundhouse_ui/tags"
 require "roundhouse_ui/cancellation"
 require "roundhouse_ui/cancel_middleware"
 require "roundhouse_ui/metrics"
@@ -56,6 +57,39 @@ module RoundhouseUi
     # e.g. RoundhouseUi.redact_args = %w[password token secret]. Default: none.
     attr_accessor :redact_args
 
+    # Host-defined job tags, resolved at read time (see ADR 0002): a callable
+    # given the job's class name and payload, returning a Hash of tags or nil.
+    # `klass` is always the real job class (the ActiveJob adapter wrapper is
+    # unwrapped first). For the class-constant convention there's a shorthand:
+    #
+    #   RoundhouseUi.job_tags = RoundhouseUi::Tags.from_constant(:OWNER, as: :squad)
+    #   # equivalent to:
+    #   RoundhouseUi.job_tags = ->(klass:, item:) {
+    #     k = klass.safe_constantize
+    #     { squad: k.const_get(:OWNER) } if k&.const_defined?(:OWNER)
+    #   }
+    #
+    # Tag values render in the UI and pass through redact_args masking (by tag
+    # key). Must be cheap: by default it's memoized per class per request and
+    # called with item: nil. Default: nil (no tags anywhere).
+    attr_accessor :job_tags
+
+    # Set true when job_tags derives tags from the payload (args, tenant, …):
+    # the resolver is then called once per job with the full item, and nothing
+    # is cached — a 1,000-entry scan means 1,000 calls, so keep it fast. Leave
+    # false for class-derived tags (OWNER-style constants). Default: false.
+    attr_accessor :job_tags_per_job
+
+    # Optional declared filter vocabulary, so tag filter dropdowns are stable
+    # instead of discovered from whatever jobs happen to be visible:
+    #
+    #   RoundhouseUi.tag_filters = { squad: %w[core training growth platform ops ai] }
+    #
+    # Values (or the whole setting) may be callables for dynamic vocabularies.
+    # When set, filtering by an undeclared key matches nothing (fail-closed).
+    # Default: nil — the filter UI discovers values from the entries it scans.
+    attr_accessor :tag_filters
+
     # Opt-in: fold failures recorded by the `sidekiq-failures` gem (its `failed`
     # sorted set) into the grouped Errors view. Off by default, and a no-op
     # unless sidekiq-failures is loaded. Jobs with `retry: false` never enter
@@ -112,4 +146,5 @@ module RoundhouseUi
   self.pause_enabled = true
   self.poll_interval = 5
   self.collect_durations = false
+  self.job_tags_per_job = false
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: roundhouse_ui
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - R.J. Robinson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-24 00:00:00.000000000 Z
+date: 2026-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -72,6 +72,7 @@ files:
 - app/helpers/roundhouse_ui/application_helper.rb
 - app/helpers/roundhouse_ui/nav_helper.rb
 - app/helpers/roundhouse_ui/observability_helper.rb
+- app/helpers/roundhouse_ui/tags_helper.rb
 - app/views/layouts/roundhouse_ui/application.html.erb
 - app/views/roundhouse_ui/audit/index.html.erb
 - app/views/roundhouse_ui/busy/index.html.erb
@@ -89,6 +90,7 @@ files:
 - app/views/roundhouse_ui/retries/index.html.erb
 - app/views/roundhouse_ui/scheduled/index.html.erb
 - app/views/roundhouse_ui/shared/_pager.html.erb
+- app/views/roundhouse_ui/shared/_tag_filter.html.erb
 - app/views/roundhouse_ui/snapshots/index.html.erb
 - app/views/roundhouse_ui/workers/index.html.erb
 - config/routes.rb
@@ -108,6 +110,7 @@ files:
 - lib/roundhouse_ui/pause.rb
 - lib/roundhouse_ui/redaction.rb
 - lib/roundhouse_ui/snapshots.rb
+- lib/roundhouse_ui/tags.rb
 - lib/roundhouse_ui/version.rb
 - lib/tasks/roundhouse_ui_tasks.rake
 homepage: https://github.com/rjrobinson/roundhouse_ui