roundhouse_ui 0.1.0

data/lib/roundhouse_ui/pause.rb

@@ -0,0 +1,59 @@
+require "set"
+require "sidekiq"
+
+module RoundhouseUi
+  # Roundhouse's own queue-pause registry — pure OSS, no Sidekiq Pro.
+  #
+  # 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.
+  module Pause
+    KEY        = "roundhouse:paused"
+    FETCH_FLAG = "roundhouse:fetch_alive" # liveness beacon set by the fetcher
+
+    module_function
+
+    def pause!(queue)
+      Sidekiq.redis { |conn| conn.call("SADD", KEY, queue.to_s) }
+    end
+
+    def unpause!(queue)
+      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
+    end
+
+    def paused_queues
+      Sidekiq.redis { |conn| conn.call("SMEMBERS", KEY) }.sort
+    end
+
+    def paused_set
+      Set.new(Sidekiq.redis { |conn| conn.call("SMEMBERS", KEY) })
+    end
+
+    # Given the redis queue keys BasicFetch would poll (e.g. "queue:default"),
+    # drop any whose queue is paused. Pure given the paused set, so it's unit
+    # testable without a running Sidekiq.
+    def reject_paused(queue_keys)
+      paused = paused_set
+      return queue_keys if paused.empty?
+
+      queue_keys.reject { |key| paused.include?(key.to_s.delete_prefix("queue:")) }
+    end
+
+    # The fetcher calls this periodically so the web UI can tell whether pausing
+    # is actually enforced (the worker and web run in separate processes). The
+    # short TTL means the flag disappears soon after all Roundhouse fetchers stop.
+    def mark_fetch_alive!(ttl = 30)
+      Sidekiq.redis { |conn| conn.call("SET", FETCH_FLAG, "1", "EX", ttl) }
+    end
+
+    # True when a RoundhouseUi::Fetch has reported in recently — i.e. pausing
+    # will take effect. When false, the UI warns instead of pretending.
+    def fetch_installed?
+      Sidekiq.redis { |conn| conn.call("EXISTS", FETCH_FLAG) } == 1
+    end
+  end
+end

data/lib/roundhouse_ui/redaction.rb

@@ -0,0 +1,33 @@
+module RoundhouseUi
+  # Masks sensitive values when displaying job arguments. Configure the key
+  # patterns to redact (matched case-insensitively as substrings):
+  #
+  #   RoundhouseUi.redact_args = %w[password token secret api_key authorization]
+  #
+  # Walks arrays/hashes so nested keyword args are covered. No-op by default.
+  module Redaction
+    MASK = "«redacted»".freeze
+
+    module_function
+
+    def apply(value, patterns = RoundhouseUi.redact_args)
+      return value if patterns.nil? || patterns.empty?
+
+      case value
+      when Hash
+        value.each_with_object({}) do |(k, v), out|
+          out[k] = sensitive?(k, patterns) ? MASK : apply(v, patterns)
+        end
+      when Array
+        value.map { |e| apply(e, patterns) }
+      else
+        value
+      end
+    end
+
+    def sensitive?(key, patterns)
+      key = key.to_s.downcase
+      patterns.any? { |p| key.include?(p.to_s.downcase) }
+    end
+  end
+end

data/lib/roundhouse_ui/snapshots.rb

@@ -0,0 +1,90 @@
+require "json"
+require "sidekiq/api"
+
+module RoundhouseUi
+  # Back up a queue's jobs before you purge it, and restore them later — the
+  # safety net that makes clearing a stuck queue non-destructive.
+  #
+  # Storage is pluggable via RoundhouseUi.snapshot_store. The default RedisStore
+  # keeps blobs in Redis (simple, dependency-free); for large/stuck queues you'll
+  # want a file or S3 store so the backup doesn't sit in the same Redis you're
+  # trying to relieve. Any object responding to write/read/delete/ids works.
+  module Snapshots
+    module_function
+
+    def store
+      RoundhouseUi.snapshot_store
+    end
+
+    # Copy every job currently on `queue_name` into a snapshot. Non-destructive —
+    # the queue is left untouched (purge separately if you want to clear it).
+    def take(queue_name)
+      payloads = []
+      Sidekiq::Queue.new(queue_name).each { |job| payloads << job.value }
+
+      id = "#{queue_name}-#{Time.now.to_i}-#{rand(10_000)}"
+      store.write(id, JSON.dump(
+        "queue" => queue_name, "created_at" => Time.now.to_f, "count" => payloads.size, "jobs" => payloads
+      ))
+      metadata(id)
+    end
+
+    def all
+      store.ids.filter_map { |id| metadata(id) }.sort_by { |m| -m[:created_at].to_f }
+    end
+
+    def metadata(id)
+      raw = store.read(id)
+      return nil unless raw
+
+      data = JSON.parse(raw)
+      { id: id, queue: data["queue"], count: data["count"] || data["jobs"].size, created_at: data["created_at"] }
+    end
+
+    # Re-enqueue a snapshot's jobs onto their original queue. Returns the count.
+    def restore(id)
+      raw = store.read(id)
+      return 0 unless raw
+
+      data = JSON.parse(raw)
+      key = "queue:#{data["queue"]}"
+      data["jobs"].each { |payload| Sidekiq.redis { |conn| conn.call("RPUSH", key, payload) } }
+      data["jobs"].size
+    end
+
+    def delete(id)
+      store.delete(id)
+    end
+
+    # Default store: blobs + an index set, all in Redis.
+    class RedisStore
+      INDEX = "roundhouse:snapshots"
+
+      def write(id, blob)
+        Sidekiq.redis do |conn|
+          conn.call("SET", key(id), blob)
+          conn.call("SADD", INDEX, id)
+        end
+      end
+
+      def read(id)
+        Sidekiq.redis { |conn| conn.call("GET", key(id)) }
+      end
+
+      def delete(id)
+        Sidekiq.redis do |conn|
+          conn.call("DEL", key(id))
+          conn.call("SREM", INDEX, id)
+        end
+      end
+
+      def ids
+        Sidekiq.redis { |conn| conn.call("SMEMBERS", INDEX) }
+      end
+
+      private
+
+      def key(id) = "roundhouse:snapshot:#{id}"
+    end
+  end
+end

data/lib/roundhouse_ui/version.rb

@@ -0,0 +1,3 @@
+module RoundhouseUi
+  VERSION = "0.1.0"
+end

data/lib/roundhouse_ui.rb

@@ -0,0 +1,73 @@
+require "roundhouse_ui/version"
+require "roundhouse_ui/engine"
+require "sidekiq/api"
+require "roundhouse_ui/pause"
+require "roundhouse_ui/fetch"
+require "roundhouse_ui/snapshots"
+require "roundhouse_ui/observability"
+require "roundhouse_ui/audit"
+require "roundhouse_ui/redaction"
+require "roundhouse_ui/cancellation"
+require "roundhouse_ui/cancel_middleware"
+require "roundhouse_ui/metrics"
+
+# Brand name is "Roundhouse"; the gem and Ruby namespace are RoundhouseUi
+# (matching the published gem name `roundhouse_ui`).
+module RoundhouseUi
+  class << self
+    # When true, destructive actions (purge, retry, delete, …) are disabled.
+    # Mount Roundhouse read-only where operators should only observe.
+    attr_accessor :read_only
+
+    # Pluggable snapshot storage. Defaults to Redis; assign any object that
+    # responds to write(id, blob) / read(id) / delete(id) / ids.
+    attr_writer :snapshot_store
+
+    def snapshot_store
+      @snapshot_store ||= Snapshots::RedisStore.new
+    end
+
+    # Pluggable APM deep-links. Defaults to no links; assign a DatadogAdapter
+    # (or your own) to deep-link jobs out to your observability tool.
+    attr_writer :observability
+
+    def observability
+      @observability ||= Observability::NullAdapter.new
+    end
+
+    # How the audit log names the person taking an action. Auth is the host's
+    # job, so give Roundhouse a callable that pulls the actor from the request:
+    #
+    #   RoundhouseUi.actor_resolver = ->(controller) { controller.current_user&.email }
+    #
+    # Defaults to "anonymous".
+    attr_accessor :actor_resolver
+
+    # Opt-in: enqueue brand-new jobs and edit/re-enqueue existing ones from the
+    # UI. Off by default — it's a sharp tool (bad edits create unrunnable jobs).
+    attr_accessor :allow_job_editing
+
+    # Argument keys (substring, case-insensitive) to mask when displaying jobs.
+    # e.g. RoundhouseUi.redact_args = %w[password token secret]. Default: none.
+    attr_accessor :redact_args
+
+    # Configure in an initializer:
+    #
+    #   RoundhouseUi.configure do |c|
+    #     c.read_only = !Rails.env.development?
+    #   end
+    def configure
+      yield self
+    end
+
+    # Cooperative cancellation check for long-running jobs:
+    #   raise SomeStop if RoundhouseUi.cancelled?(jid)
+    def cancelled?(jid)
+      Cancellation.cancelled?(jid)
+    end
+  end
+
+  self.read_only = false
+  self.allow_job_editing = false
+  self.redact_args = []
+end

data/lib/tasks/roundhouse_ui_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :roundhouse_ui do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: roundhouse_ui
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- R.J. Robinson
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: sidekiq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+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.'
+email:
+- rj@trainual.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/javascripts/roundhouse_ui/turbo.min.js
+- app/assets/stylesheets/roundhouse_ui/application.css
+- app/controllers/concerns/roundhouse_ui/job_set_browsing.rb
+- app/controllers/roundhouse_ui/application_controller.rb
+- app/controllers/roundhouse_ui/assets_controller.rb
+- app/controllers/roundhouse_ui/audit_controller.rb
+- app/controllers/roundhouse_ui/busy_controller.rb
+- app/controllers/roundhouse_ui/capsules_controller.rb
+- app/controllers/roundhouse_ui/dashboard_controller.rb
+- app/controllers/roundhouse_ui/dead_controller.rb
+- app/controllers/roundhouse_ui/errors_controller.rb
+- 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/redis_controller.rb
+- app/controllers/roundhouse_ui/retries_controller.rb
+- app/controllers/roundhouse_ui/scheduled_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/views/layouts/roundhouse_ui/application.html.erb
+- app/views/roundhouse_ui/audit/index.html.erb
+- app/views/roundhouse_ui/busy/index.html.erb
+- app/views/roundhouse_ui/capsules/index.html.erb
+- app/views/roundhouse_ui/dashboard/show.html.erb
+- app/views/roundhouse_ui/dead/index.html.erb
+- app/views/roundhouse_ui/errors/index.html.erb
+- app/views/roundhouse_ui/jobs/_form.html.erb
+- app/views/roundhouse_ui/jobs/edit.html.erb
+- app/views/roundhouse_ui/jobs/new.html.erb
+- 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/redis/show.html.erb
+- 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/snapshots/index.html.erb
+- app/views/roundhouse_ui/workers/index.html.erb
+- config/routes.rb
+- lib/roundhouse_ui.rb
+- lib/roundhouse_ui/audit.rb
+- lib/roundhouse_ui/cancel_middleware.rb
+- lib/roundhouse_ui/cancellation.rb
+- lib/roundhouse_ui/engine.rb
+- lib/roundhouse_ui/fetch.rb
+- lib/roundhouse_ui/metrics.rb
+- lib/roundhouse_ui/observability.rb
+- lib/roundhouse_ui/pause.rb
+- lib/roundhouse_ui/redaction.rb
+- lib/roundhouse_ui/snapshots.rb
+- lib/roundhouse_ui/version.rb
+- lib/tasks/roundhouse_ui_tasks.rake
+homepage: https://github.com/rjrobinson/roundhouse_ui
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/rjrobinson/roundhouse_ui
+  changelog_uri: https://github.com/rjrobinson/roundhouse_ui/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Roundhouse — a modern, real-time web UI for Sidekiq.
+test_files: []