roundhouse_ui 0.9.1 → 0.11.0

data/lib/roundhouse_ui.rb

@@ -7,6 +7,14 @@ require "roundhouse_ui/snapshots"
 require "roundhouse_ui/observability"
 require "roundhouse_ui/audit"
 require "roundhouse_ui/redaction"
+require "roundhouse_ui/queue_summary"
+require "roundhouse_ui/theme"
+require "roundhouse_ui/tags"
+require "roundhouse_ui/filter_query"
+require "roundhouse_ui/runbooks"
+require "roundhouse_ui/icons"
+require "roundhouse_ui/history"
+require "roundhouse_ui/recurring"
 require "roundhouse_ui/cancellation"
 require "roundhouse_ui/cancel_middleware"
 require "roundhouse_ui/metrics"
@@ -19,6 +27,14 @@ require "roundhouse_ui/backends/solid_queue"
 # Brand name is "Roundhouse"; the gem and Ruby namespace are RoundhouseUi
 # (matching the published gem name `roundhouse_ui`).
 module RoundhouseUi
+  # A well-formed Ruby constant path, and a sane bound on its length. Used to
+  # decide what may reach String#safe_constantize — see .job_class.
+  JOB_CLASS_NAME = /\A[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*\z/
+  MAX_JOB_CLASS_NAME = 200
+
+  # How many distinct warning messages .warn_once remembers before resetting.
+  WARN_MEMO_CAP = 200
+
   class << self
     # When true, destructive actions (purge, retry, delete, …) are disabled.
     # Mount Roundhouse read-only where operators should only observe.
@@ -56,6 +72,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
@@ -73,13 +122,60 @@ module RoundhouseUi
     # load. Default 5s; raise it if polling shows up in your traces.
     attr_accessor :poll_interval
 
-    # Queue pause/resume is only enforced when RoundhouseUi::Fetch is installed
-    # as the server's fetch strategy. If you run reliable fetch (Sidekiq
-    # Pro/Enterprise super_fetch) you can't also run our fetcher, so pause can't
-    # be enforced — set this to false to hide the pause controls and the
-    # "not enforced" warning entirely. Default: true.
+    # On OSS Sidekiq, pause is enforced only with RoundhouseUi::Fetch installed as the
+    # server's fetch strategy; the UI warns until it is. Sidekiq Pro and Solid Queue
+    # enforce it natively with no fetcher, so leave this on there. Default: true.
     attr_accessor :pause_enabled
 
+    # Cancellation only does something if the host opted into it — either by
+    # installing RoundhouseUi::CancelMiddleware as server middleware, or by
+    # having long-running jobs poll RoundhouseUi.cancelled?(jid) themselves.
+    # With neither, cancel! writes a JID that nothing ever reads, so the Busy
+    # page's button would be inert. Default false: the button appears once you
+    # say the check exists. Also requires a backend that supports :cancel.
+    attr_accessor :cancel_enabled
+
+    # Override any of the UI's colour tokens, as pure CSS custom properties:
+    #
+    #   RoundhouseUi.theme = { accent: "#FF2BD1", accent_2: "#00E5FF" }
+    #   RoundhouseUi.theme = { dark: { bg: "#0A0511" }, light: { bg: "#FFF7FB" } }
+    #   RoundhouseUi.theme = RoundhouseUi::Theme::PRESETS[:cyberpunk]
+    #
+    # Unset tokens keep their shipped values, so a partial theme is fine. Only
+    # known tokens are emitted and values are shape-checked — this is
+    # interpolated into a stylesheet, where escaping does not make arbitrary
+    # input safe. Default: nil.
+    attr_accessor :theme
+
+    # Named palettes a viewer can choose between on the Settings page:
+    #
+    #   RoundhouseUi.themes = { cyberpunk: RoundhouseUi::Theme::PRESETS[:cyberpunk] }
+    #
+    # `theme` sets the default for everyone; this is the menu each person picks
+    # from in their own browser. Default: the shipped presets.
+    attr_accessor :themes
+
+    # How icons render. `:svg` (default) inlines them — no font, no request, no
+    # CSP change. `:font_awesome` or a Hash of `{ name => "class names" }` emits
+    # class names instead, for hosts that already ship an icon font; Roundhouse
+    # never loads one itself either way.
+    attr_accessor :icons
+
+    # Where the runbook for a job class lives. A callable, or a Hash keyed by
+    # class name:
+    #
+    #   c.job_runbooks = RoundhouseUi::Runbooks.from_constant(:RUNBOOK)
+    #   c.job_runbooks = { "Billing::SyncWorker" => "https://wiki/billing" }
+    #
+    # Resolved at read time like job_tags, so it applies to jobs already in the
+    # sets. Only http(s) URLs are rendered. Default: nil.
+    attr_accessor :job_runbooks
+
+    # Set false where an operator should not be able to recolour a production
+    # console. Settings then hides palette selection and everyone keeps the
+    # host's `theme`. Default: true.
+    attr_accessor :allow_theme_selection
+
     # Configure in an initializer:
     #
     #   RoundhouseUi.configure do |c|
@@ -98,6 +194,135 @@ module RoundhouseUi
       @backend ||= Backends::Sidekiq.new
     end
 
+    # 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, and Solid Queue's synthetic item never carries
+    # a "wrapped" key — so this is a no-op there and safe to call unconditionally.
+    #
+    # Reading item["wrapped"] rather than matching on the wrapper's name also
+    # covers Sidekiq 7+/8's native Sidekiq::ActiveJob::Wrapper for free.
+    #
+    # Use for display, search, grouping and APM links, so all four agree on one
+    # string. NOT for re-enqueue: a payload pushed back to Redis must keep
+    # item["class"] exactly as Sidekiq stored it, or the job is re-created as a
+    # raw worker and fails on every attempt.
+    def unwrapped_class(klass, item)
+      wrapped = item["wrapped"] if item.is_a?(Hash)
+      (wrapped || klass)&.to_s
+    end
+
+    # When a job was enqueued, as a Time, or nil if the payload does not say.
+    #
+    # Two formats exist three orders of magnitude apart: Sidekiq 8 writes integer
+    # epoch milliseconds, 6.5 and 7 write float epoch seconds. Reading one as the
+    # other does not give a slightly wrong time, it gives 1970 or the year 58000.
+    def enqueued_at(item)
+      raw = item["enqueued_at"] || item["created_at"] if item.is_a?(Hash)
+      return nil unless raw
+
+      raw.is_a?(Float) ? Time.at(raw) : Time.at(raw / 1000.0)
+    rescue StandardError
+      nil
+    end
+
+    # Optional allowlist for constant resolution. When set, only these
+    # namespaces may be resolved from a job payload:
+    #
+    #   c.job_class_namespaces = %w[Workers Jobs Billing]
+    #
+    # This is the only control here that actually restricts what can be loaded.
+    # Shape checks do not: Ruby rejects a malformed constant path before it
+    # attempts any lookup, so a name like "../../etc/passwd" never reaches
+    # autoloading in the first place — only well-formed names do, and those are
+    # exactly what a shape check permits.
+    #
+    # Default nil (no restriction), because most apps do not need it: production
+    # Rails sets `eager_load = true`, so every app constant is already loaded and
+    # resolving one executes no new file. Set it where the job payload is not
+    # fully trusted and you would rather bound the blast radius anyway.
+    attr_accessor :job_class_namespaces
+
+    # Resolve a job class name to its Class, for resolvers that read constants
+    # off the class (Tags.from_constant, Runbooks.from_constant).
+    #
+    # The name comes from the job payload — `item["class"]` or `item["wrapped"]`
+    # — which is data, not code. Three narrowings, and it is worth being precise
+    # about which of them is a security control and which are not:
+    #
+    #   * The namespace allowlist, when configured, IS one. It runs before the
+    #     constant lookup and is the only thing here that decides what may be
+    #     resolved.
+    #   * The shape and length checks are NOT. They reject names Ruby would
+    #     reject anyway, before it attempts a lookup; they are here so the
+    #     rejection is explicit and a pathological string is bounded early.
+    #   * Requiring a Module back is robustness: a name resolving to an Array
+    #     would otherwise be sent `const_defined?`, which it does not answer.
+    #
+    # What nothing at this layer can do is stop a chosen name for a class that
+    # genuinely exists — reading a constant requires loading the class. Hosts who
+    # want no constant resolution at all should supply a resolver that does none:
+    # a Hash keyed by class name serves both tags and runbooks and never
+    # constantizes.
+    def job_class(name)
+      str = name.to_s
+      return nil unless str.length <= MAX_JOB_CLASS_NAME && str.match?(JOB_CLASS_NAME)
+      return nil unless namespace_allowed?(str)
+
+      klass = str.safe_constantize
+      klass if klass.is_a?(Module)
+    end
+
+    def namespace_allowed?(str)
+      allowed = job_class_namespaces
+      return true if allowed.nil? || Array(allowed).empty?
+
+      Array(allowed).any? { |ns| str == ns.to_s || str.start_with?("#{ns}::") }
+    end
+
+    # Durations, in one place. This lived in a view helper, which meant anything
+    # in lib/ that wanted to print a duration had to reinvent it — and did, five
+    # different ways, including the health signal that reported an hour-old queue
+    # as "3616s" (#31). Views reach this through the `duration` helper.
+    def duration(seconds)
+      return "—" if seconds.nil?
+
+      secs = seconds.to_f.abs
+      # Sub-minute keeps a decimal: 0.4s and 12s are a real distinction here.
+      return "#{secs.round(1)}s" if secs < 60
+      return "#{(secs / 60).floor}m #{(secs % 60).round}s" if secs < 3_600
+      return "#{(secs / 3_600).floor}h #{((secs % 3_600) / 60).round}m" if secs < 86_400
+
+      "#{(secs / 86_400).floor}d #{((secs % 86_400) / 3_600).round}h"
+    end
+
+    def duration_ms(ms)
+      return "—" if ms.nil?
+      return "#{ms.to_f.abs.round}ms" if ms.to_f.abs < 1_000
+
+      duration(ms.to_f / 1_000)
+    end
+
+    # Log a resolver failure at most once per process per distinct message.
+    #
+    # It was named warn_once and warned every time. A resolver that raises raises
+    # for every entry in a scan, so one broken job_tags lambda wrote a line per
+    # job — a thousand identical lines in the log for a single page render, which
+    # is how a warning stops being read at all.
+    #
+    # Bounded by WARN_MEMO_CAP, because the message carries the class name and the
+    # exception's own text: a resolver whose message varies could otherwise grow
+    # this without limit. At the cap it resets rather than leaking or going silent.
+    def warn_once(message)
+      return unless defined?(Rails)
+
+      @warned ||= {}
+      return if @warned.key?(message)
+
+      @warned.clear if @warned.size >= WARN_MEMO_CAP
+      @warned[message] = true
+      Rails.logger&.warn("[roundhouse] #{message}")
+    end
+
     # Cooperative cancellation check for long-running jobs:
     #   raise SomeStop if RoundhouseUi.cancelled?(jid)
     def cancelled?(jid)
@@ -110,6 +335,11 @@ module RoundhouseUi
   self.redact_args = []
   self.show_sidekiq_failures = false
   self.pause_enabled = true
+  self.cancel_enabled = false
   self.poll_interval = 5
   self.collect_durations = false
+  self.job_tags_per_job = false
+  self.allow_theme_selection = true
+  self.icons = :svg
+  self.themes = Theme::PRESETS
 end

data/lib/tasks/roundhouse_ui_tasks.rake

@@ -1,4 +1,84 @@
-# desc "Explaining what the task does"
-# task :roundhouse_ui do
-#   # Task goes here
-# end
+# frozen_string_literal: true
+
+namespace :roundhouse_ui do
+  namespace :demo do
+    desc "Enqueue demo jobs for N minutes (default 10, hard cap 20): rake roundhouse_ui:demo:load[10]"
+    task :load, [ :minutes ] => :environment do |_task, args|
+      require "roundhouse_ui/demo"
+
+      abort "refusing to run in #{Rails.env}" unless Rails.env.development?
+
+      # Ask the connection where it actually is. Reading configuration cannot
+      # answer that, and Sidekiq falls back to database 0 when nothing set it.
+      db = Sidekiq.redis { |c| c.call("CLIENT", "INFO") }.to_s[/\bdb=(\d+)/, 1]
+      abort "refusing to enqueue against Redis database 0" if db.nil? || db == "0"
+
+      # Capped, and capped in one place. A load generator you have to remember to
+      # stop is a load generator that runs all night.
+      minutes = [ (args[:minutes] || 10).to_f, 20.0 ].min
+      minutes = 1.0 if minutes <= 0
+
+      mono = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      started = mono.call
+      deadline = started + (minutes * 60)
+      enqueued = Hash.new(0)
+      tick = 0
+
+      puts "Enqueueing to Redis db=#{db} for #{minutes.round(1)} min " \
+           "(#{RoundhouseUi::Demo::ALL.size} worker classes). Ctrl-C to stop early."
+
+      begin
+        while mono.call < deadline
+          tick += 1
+          # A rate that moves, so the dashboard's throughput line and the drain
+          # forecast have something to say. Peaks roughly every two minutes.
+          phase = Math.sin(tick / 12.0)
+          batch = (6 + (phase.abs * 18)).round
+
+          batch.times do
+            worker = RoundhouseUi::Demo::ALL.sample
+            worker.set(queue: worker::QUEUE).perform_async(
+              "account_id" => 40_000 + rand(600),
+              "user_id" => 900_000 + rand(9_000),
+              # Deliberately named to be masked by redact_args in the UI.
+              "api_token" => "sk_live_#{SecureRandom.hex(8)}"
+            )
+            enqueued[worker.name.split("::").last] += 1
+          end
+
+          if (tick % 10).zero?
+            left = ((deadline - mono.call) / 60).round(1)
+            puts "  +#{enqueued.values.sum} enqueued, #{left} min left"
+          end
+          sleep 1.5
+        end
+      rescue Interrupt
+        puts "\n  stopped early"
+      end
+
+      puts "\nDone after #{((mono.call - started) / 60).round(1)} min:"
+      enqueued.sort_by { |_k, v| -v }.each { |k, v| puts format("  %-22s %5d", k, v) }
+      puts format("  %-22s %5d", "TOTAL", enqueued.values.sum)
+    end
+
+    desc "Remove everything the demo seeded or enqueued"
+    task clean: :environment do
+      require "roundhouse_ui/demo"
+      abort "refusing to run in #{Rails.env}" unless Rails.env.development?
+      removed = 0
+      %w[retry dead schedule].each do |set|
+        Sidekiq.redis do |conn|
+          conn.call("ZRANGE", set, "0", "-1").each do |raw|
+            job = JSON.parse(raw) rescue next
+            next unless job["rh_demo"] || job["class"].to_s.start_with?("RoundhouseUi::Demo::")
+
+            conn.call("ZREM", set, raw)
+            removed += 1
+          end
+        end
+      end
+      RoundhouseUi::Demo::ALL.each { |w| Sidekiq::Queue.new(w::QUEUE).clear }
+      puts "removed #{removed} demo entries from the retry/dead/scheduled sets"
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: roundhouse_ui
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.11.0
 platform: ruby
 authors:
 - R.J. Robinson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-31 00:00:00.000000000 Z
+date: 2026-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -38,11 +38,12 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.5'
-description: 'A mountable Rails engine that replaces the Sidekiq Web UI with a real-time
-  control plane: live queues, search, bulk actions, stuck-queue detection, snapshots,
-  and pluggable observability.'
+description: 'Mountable Rails engine for Sidekiq or Solid Queue: grouped errors, argument
+  search, filter-scoped bulk actions, enforced pause, snapshots, audit log. Mounts
+  alongside or instead of Sidekiq::Web. Not affiliated with or endorsed by Contributed
+  Systems LLC; Sidekiq, Sidekiq Pro and Sidekiq Enterprise are their trademarks.'
 email:
-- rj@trainual.com
+- robertj.robinson@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -64,14 +65,17 @@ files:
 - app/controllers/roundhouse_ui/jobs_controller.rb
 - app/controllers/roundhouse_ui/metrics_controller.rb
 - app/controllers/roundhouse_ui/queues_controller.rb
+- app/controllers/roundhouse_ui/recurring_controller.rb
 - app/controllers/roundhouse_ui/redis_controller.rb
 - app/controllers/roundhouse_ui/retries_controller.rb
 - app/controllers/roundhouse_ui/scheduled_controller.rb
+- app/controllers/roundhouse_ui/settings_controller.rb
 - app/controllers/roundhouse_ui/snapshots_controller.rb
 - app/controllers/roundhouse_ui/workers_controller.rb
 - 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
@@ -85,10 +89,18 @@ files:
 - app/views/roundhouse_ui/jobs/show.html.erb
 - app/views/roundhouse_ui/metrics/show.html.erb
 - app/views/roundhouse_ui/queues/index.html.erb
+- app/views/roundhouse_ui/queues/show.html.erb
+- app/views/roundhouse_ui/recurring/index.html.erb
 - app/views/roundhouse_ui/redis/show.html.erb
 - app/views/roundhouse_ui/retries/index.html.erb
 - app/views/roundhouse_ui/scheduled/index.html.erb
+- app/views/roundhouse_ui/settings/show.html.erb
+- app/views/roundhouse_ui/shared/_filter_error.html.erb
 - app/views/roundhouse_ui/shared/_pager.html.erb
+- app/views/roundhouse_ui/shared/_search_bar.html.erb
+- app/views/roundhouse_ui/shared/_search_help.html.erb
+- app/views/roundhouse_ui/shared/_tag_filter.html.erb
+- app/views/roundhouse_ui/shared/bulk_preview.html.erb
 - app/views/roundhouse_ui/snapshots/index.html.erb
 - app/views/roundhouse_ui/workers/index.html.erb
 - config/routes.rb
@@ -98,16 +110,27 @@ files:
 - lib/roundhouse_ui/backends/solid_queue.rb
 - lib/roundhouse_ui/cancel_middleware.rb
 - lib/roundhouse_ui/cancellation.rb
+- lib/roundhouse_ui/demo.rb
 - lib/roundhouse_ui/duration_collector.rb
 - lib/roundhouse_ui/engine.rb
 - lib/roundhouse_ui/error_groups.rb
 - lib/roundhouse_ui/fetch.rb
+- lib/roundhouse_ui/filter_query.rb
 - lib/roundhouse_ui/health.rb
+- lib/roundhouse_ui/history.rb
+- lib/roundhouse_ui/icons.rb
+- lib/roundhouse_ui/marks/datadog-lockup-white.svg
+- lib/roundhouse_ui/marks/datadog-lockup.svg
 - lib/roundhouse_ui/metrics.rb
 - lib/roundhouse_ui/observability.rb
 - lib/roundhouse_ui/pause.rb
+- lib/roundhouse_ui/queue_summary.rb
+- lib/roundhouse_ui/recurring.rb
 - lib/roundhouse_ui/redaction.rb
+- lib/roundhouse_ui/runbooks.rb
 - lib/roundhouse_ui/snapshots.rb
+- lib/roundhouse_ui/tags.rb
+- lib/roundhouse_ui/theme.rb
 - lib/roundhouse_ui/version.rb
 - lib/tasks/roundhouse_ui_tasks.rake
 homepage: https://github.com/rjrobinson/roundhouse_ui
@@ -116,6 +139,8 @@ licenses:
 metadata:
   source_code_uri: https://github.com/rjrobinson/roundhouse_ui
   changelog_uri: https://github.com/rjrobinson/roundhouse_ui/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/rjrobinson/roundhouse_ui/issues
+  documentation_uri: https://github.com/rjrobinson/roundhouse_ui#readme
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -135,5 +160,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Roundhouse — a modern, real-time web UI for Sidekiq.
+summary: Roundhouse — a real-time ops UI for Sidekiq and Solid Queue.
 test_files: []