roundhouse_ui 0.9.1 → 0.10.0

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.1"
+  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.1
+  version: 0.10.0
 platform: ruby
 authors:
 - R.J. Robinson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-31 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