roundhouse_ui 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 913330ea311e66bcb5eb717852a73c0c4eb51a281acbd5899fac33f623b609a2
-  data.tar.gz: 8fdaff5a284e27d7df7a63ade47294f9d5f156a14e9133f7a40a24ca194ad828
+  metadata.gz: 6ee71201b4424c59d9450b7eea1fec5b7447e9e40ee419a4ebc03c39bf8189d6
+  data.tar.gz: 8a33d51ba920fd11b64ae9a28160ce40e87ff0b8c315a04136b64c7aa8427bb7
 SHA512:
-  metadata.gz: ae78d8ec53e92eaac58308a7701abfc11f71ad2d89f1ffe05b40611df458a6121a97f831d16770dfb0f9d37a3bdffe50905498bba41e7c86c7b74fe4bbc211d3
-  data.tar.gz: 446a6fa76c6f2cf70f2b3ec5e83d5eb06dbe6e6a393bebfab7414f3bd1e87d8fa96c6bf9ae180c284e2ae50e63ee1e1f3516a827591ab58d686fccdd8ebaf195
+  metadata.gz: 7494f64a2e7cea227f13ac6037e390775f068726f81e3962ecf0bf62a87d6dffaa7c613bef9c0d2b47bf4bdc5d410e6a2073e35c3a67723485af99fd30b43691
+  data.tar.gz: 2ff606ac7ca4797069b7cbb875313fd7988a962845f4c738765a8816a48280f5c889167a31d43452342389c3d122d798b15b782ac2219ba0cfb99d4125431bc0

data/README.md

@@ -107,32 +107,52 @@ RoundhouseUi.configure do |c|
   # No-op unless the sidekiq-failures gem is loaded. Default: off.
   c.show_sidekiq_failures = true
 
-  # Set false to hide queue pause/resume controls and the "not enforced" warning,
-  # e.g. when you run reliable fetch (super_fetch) instead of RoundhouseUi::Fetch.
-  # Default: true.
+  # Set false to hide queue pause/resume controls entirely. Rarely needed — on
+  # Sidekiq Pro and Solid Queue pause is enforced natively, and on OSS Sidekiq
+  # installing RoundhouseUi::Fetch enforces it. Default: true.
   # c.pause_enabled = false
 
   # Seconds between dashboard stat polls (default 5). Raise it if polling shows
   # up in your traces — each poll re-runs the host's auth/routing on the mount.
   # c.poll_interval = 10
 
-  # Show the "slowest job classes" table on the Metrics page. Requires the
-  # DurationCollector middleware (see below). Default: false.
+  # Show the "slowest job classes" table on the Metrics page. The flag alone shows
+  # nothing — it also needs the DurationCollector middleware (see below).
+  # Default: false.
   # c.collect_durations = true
 end
 ```
 
-Every option is independent and has a safe default — set only what you need.
-`read_only`, `allow_job_editing`, and `show_sidekiq_failures` default to `false`;
-`redact_args` to `[]`; `observability` to a no-op adapter; `snapshot_store` to Redis.
+Every option is independent and has a safe default — **set only what you need**. Nothing
+here is required to mount Roundhouse.
+
+### When to turn each one on
+
+| Option | Default | Turn it on when | Leave it alone when |
+|---|---|---|---|
+| `read_only` | `false` | **Production, almost always.** Blocks purge/retry/delete/edit *server-side*, not just in the UI — so it holds even if someone hand-crafts a request. The usual shape is `!Rails.env.development?`. | You need operators to actually fix things from the UI, and you trust everyone behind the mount. |
+| `redact_args` | `[]` | **Any app whose job args carry secrets or PII** — args render in full on the job page. Matches keys case-insensitively as substrings, and walks nested hashes/arrays. | Args are all IDs and enum values. |
+| `actor_resolver` | `"anonymous"` | You want the audit log to name *who* did something. One line: `->(c) { c.current_user&.email }`. | Single-operator app, or you already audit at another layer. |
+| `allow_job_editing` | `false` | Development and debugging. **Sharp tool** — a bad edit creates an unrunnable job, and it lets the UI enqueue arbitrary classes. | Production, unless you specifically want that power and have `read_only` off anyway. |
+| `observability` | no-op | You run an APM and want per-job deep links out to it. Ships a Datadog adapter; duck-type `job_url`/`queue_url`/`error_url` for anything else. | No APM, or you'd rather not add links that only some people can open. |
+| `snapshot_store` | Redis | Your snapshots are large or need to outlive Redis (S3/disk). Duck-type `write`/`read`/`delete`/`ids`. | Redis is fine — which it usually is for occasional queue snapshots. |
+| `show_sidekiq_failures` | `false` | You use the `sidekiq-failures` gem **and** run jobs with `retry: false` — those never enter Sidekiq's retry/dead sets, so this is the only way to see them. | You don't have the gem (it's a no-op then anyway). |
+| `poll_interval` | `5` | **Raise it** if dashboard polling shows up in your traces — every poll re-runs your app's auth and routing on the mount, so a busy console adds real load. Lower it only for a livelier demo. | Default is fine for most apps. |
+| `collect_durations` | `false` | You want "slowest job classes" on Metrics, which Sidekiq doesn't track. **Also requires installing the `DurationCollector` middleware** — the flag alone shows nothing. Costs one pipelined Redis round-trip per job. | You already get per-job timing from your APM. |
+| `pause_enabled` | `true` | Leave it on. | **Rarely set this to `false`.** Pause is enforced natively on Sidekiq Pro and Solid Queue, and on OSS Sidekiq by installing `RoundhouseUi::Fetch` — so turning it off usually just hides a working feature. Only useful if you want the controls gone entirely. |
+
+Two that pair with a middleware rather than working alone: `collect_durations`
+(`DurationCollector`) and job cancellation (`CancelMiddleware`) — see
+[Cancelling jobs](#cancelling-jobs) and [Slowest job classes](#slowest-job-classes).
 
 ## Pausing queues
 
-> On **Solid Queue**, pause is **native** — it's enforced by the backend, so there's
-> nothing to install and no warning. The rest of this section is Sidekiq-only.
+> Pause is **native** — enforced with nothing to install and no warning — on both
+> **Solid Queue** and **Sidekiq Pro/Enterprise** (see below). The fetch strategy
+> below is only needed on **OSS Sidekiq**.
 
-On Sidekiq, pause/resume is pure OSS. To make a pause actually stop a queue from being
-worked, install Roundhouse's fetch strategy in your Sidekiq **server** config:
+On OSS Sidekiq, pause/resume is pure OSS. To make a pause actually stop a queue from
+being worked, install Roundhouse's fetch strategy in your Sidekiq **server** config:
 
 ```ruby
 # config/initializers/sidekiq.rb
@@ -146,11 +166,26 @@ all of Sidekiq's weighting/ordering. Until it's installed, the Queues page recor
 but **warns that they aren't enforced** (worker and web are separate processes, so
 Roundhouse detects whether a fetcher has reported in).
 
-> ⚠️ **Sidekiq Pro/Enterprise users:** super_fetch / reliable fetch sets its own
-> `fetch_class`, and Sidekiq allows only one. Installing `RoundhouseUi::Fetch` would
-> **replace reliable fetch and lose its crash-recovery guarantees** — don't. On those
-> tiers, leave the fetch strategy out and set `RoundhouseUi.pause_enabled = false` to
-> hide the pause controls and the (otherwise permanent) "not enforced" warning.
+### Sidekiq Pro / Enterprise — nothing to install
+
+Pro ships its own enforced pause, and Roundhouse uses it automatically. Pro reopens
+`Sidekiq::Queue` with `pause!`/`unpause!` and *prepends* pause support onto
+`Sidekiq::BasicFetch` (`super_fetch` honors it too), so **any Pro worker enforces
+pauses** whether or not a fetch strategy is configured.
+
+When Roundhouse detects Pro it delegates pause/resume to `Sidekiq::Queue#pause!`,
+reads paused state from Pro's registry, advertises `native_pause`, and drops the
+"not enforced" warning. So on Pro:
+
+- **Don't** install `RoundhouseUi::Fetch` — it isn't needed, and on `super_fetch`
+  installs it would displace reliable fetch and lose its crash-recovery guarantees.
+- **Don't** set `pause_enabled = false` — pause genuinely works; disabling it only
+  hides a feature you already have.
+
+Roundhouse always goes through `Sidekiq::Queue#pause!` rather than writing Pro's
+Redis key directly: Pro's fetchers read that set once at startup and afterwards
+only update on the `pro:config` pubsub message `pause!` publishes, so a raw write
+would leave running workers pulling the queue until they restarted.
 
 ## Surfacing sidekiq-failures
 
@@ -184,6 +219,15 @@ The **Busy** page's Cancel button flags a job's JID. A queued/scheduled/retrying
 is then skipped when it would next run; a *currently running* job stops only if it
 checks in — e.g. a long loop can `break if RoundhouseUi.cancelled?(jid)`.
 
+**Timing and cost.** The middleware is close to free when nothing is cancelled: rather
+than checking each job's JID against Redis, it asks "is *anything* cancelled?" from a
+process-local gate refreshed at most every 2s, and only does the exact per-job lookup
+while cancellations are pending. The tradeoff is that a cancellation takes **up to ~2s
+to reach a worker process** — the UI and your workers are separate processes, so expect
+a brief lag after clicking Cancel. Jobs already in flight are unaffected either way
+(cancellation is cooperative), and `RoundhouseUi.cancelled?(jid)` — what a long-running
+job polls — is never gated, so it always reads current state.
+
 ## Slowest job classes
 
 Sidekiq doesn't track per-class durations, so Roundhouse can record them itself.
@@ -197,8 +241,8 @@ Sidekiq.configure_server do |config|
 end
 ```
 
-It's two cheap Redis writes per job (a counter + a summed-ms float) into a single
-hash, and a job failure never propagates from the collector.
+It's two cheap Redis writes per job (a counter + a summed-ms float) into a single hash,
+pipelined into **one round-trip**, and a job failure never propagates from the collector.
 
 ## Bulk actions on a filter
 

data/lib/roundhouse_ui/backends/sidekiq.rb

@@ -14,10 +14,17 @@ module RoundhouseUi
       def name = "Sidekiq"
 
       # Capabilities let the UI hide what a backend can't do. Sidekiq supports
-      # all the sets/views; pause is NOT native (needs the fetcher), so it does
-      # not advertise :native_pause — the "not enforced" warning still applies.
+      # all the sets/views. On OSS Sidekiq pause is NOT native (it needs our
+      # fetcher), so :native_pause is withheld and the "not enforced" warning
+      # applies — but Sidekiq Pro ships its own enforced pause, so there it is
+      # advertised and the warning drops away.
       CAPABILITIES = %i[retries dead scheduled busy workers redis capsules].freeze
-      def supports?(capability) = CAPABILITIES.include?(capability)
+
+      def supports?(capability)
+        return RoundhouseUi::Pause.native? if capability == :native_pause
+
+        CAPABILITIES.include?(capability)
+      end
 
       def stats        = ::Sidekiq::Stats.new
       def queues       = ::Sidekiq::Queue.all

data/lib/roundhouse_ui/cancel_middleware.rb

@@ -7,9 +7,15 @@ module RoundhouseUi
   #   Sidekiq.configure_server do |config|
   #     config.server_middleware { |chain| chain.add RoundhouseUi::CancelMiddleware }
   #   end
+  #
+  # Hot-path cost: near zero. Cancellation.pending? answers "anything cancelled
+  # at all?" from a process-local gate (one EXISTS per CHECK_EVERY seconds, not
+  # per job); the exact per-job SISMEMBER only runs while cancellations are
+  # actually pending. State lives on the Cancellation module because Sidekiq
+  # builds a fresh middleware instance per job — ivars here wouldn't survive.
   class CancelMiddleware
     def call(_worker, job, _queue)
-      if RoundhouseUi::Cancellation.cancelled?(job["jid"])
+      if RoundhouseUi::Cancellation.pending? && RoundhouseUi::Cancellation.cancelled?(job["jid"])
         RoundhouseUi::Cancellation.clear!(job["jid"])
         return # acknowledge without running
       end

data/lib/roundhouse_ui/cancellation.rb

@@ -12,6 +12,9 @@ module RoundhouseUi
   module Cancellation
     KEY = "roundhouse:cancelled"
     TTL = 86_400 # seconds
+    CHECK_EVERY = 2.0 # seconds — max staleness of the "nothing is cancelled" gate
+
+    @gate = Mutex.new # guards @pending / @checked_at (see .pending?)
 
     module_function
 
@@ -20,6 +23,12 @@ module RoundhouseUi
         conn.call("SADD", KEY, jid.to_s)
         conn.call("EXPIRE", KEY, TTL)
       end
+      # Bust the local gate: the cancelling process sees its own cancel
+      # immediately; other processes converge within CHECK_EVERY.
+      @gate.synchronize do
+        @pending = true
+        @checked_at = monotonic_now
+      end
     end
 
     def cancelled?(jid)
@@ -33,5 +42,39 @@ module RoundhouseUi
     def cancelled_jids
       Sidekiq.redis { |conn| conn.call("SMEMBERS", KEY) }
     end
+
+    # The middleware's hot-path gate: "is anything cancelled at all?" — almost
+    # always no, so answering it with one EXISTS per process per CHECK_EVERY
+    # (instead of a SISMEMBER per job) takes the common case to zero Redis
+    # round-trips. While cancellations are pending, the middleware still does
+    # the exact per-job SISMEMBER. A cancel issued by *another* process is
+    # invisible here for up to CHECK_EVERY — acceptable because cancellation
+    # is cooperative and racy by design (a job may already be running when the
+    # flag lands), and cancel! busts the local gate so the cancelling process
+    # itself is always exact.
+    def pending?
+      now = monotonic_now
+      @gate.synchronize do
+        if @checked_at.nil? || now - @checked_at >= CHECK_EVERY
+          @pending = any?
+          @checked_at = now
+        end
+        @pending
+      end
+    end
+
+    def any?
+      Sidekiq.redis { |conn| conn.call("EXISTS", KEY) } == 1
+    end
+
+    # Forget the cached gate state (tests; or after flushing Redis by hand).
+    def reset_gate!
+      @gate.synchronize do
+        @pending = nil
+        @checked_at = nil
+      end
+    end
+
+    def monotonic_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end
 end

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/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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: roundhouse_ui
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - R.J. Robinson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-24 00:00:00.000000000 Z
+date: 2026-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails