wurk 0.0.1

data/lib/wurk/web/config.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Wurk
+  class Web
+    # Web UI configuration. Holds the authorization callback documented in
+    # docs/target/sidekiq-ent.md §9.2 — a Rack-level hook called with
+    # `(env, method, path)` per request. Truthy return proceeds; falsey
+    # short-circuits to 403.
+    #
+    # Wurk ships the Ent feature in the free gem. No license check; the
+    # block runs unconditionally when present.
+    #
+    # Example:
+    #
+    #   Wurk::Web.configure do |c|
+    #     c.authorization do |env, method, _path|
+    #       user = env['warden']&.user
+    #       method == 'GET' ? user&.support? || user&.admin? : user&.admin?
+    #     end
+    #   end
+    #
+    # When no block is registered, every request is authorized (matches
+    # Sidekiq's default — no auth until the user opts in).
+    class Config
+      # String forms that mean "off" — so `config.web.read_only = ENV[...]`
+      # doesn't flip on when the env var is "0"/"false"/empty.
+      FALSEY_STRINGS = ['', '0', 'false', 'no', 'off'].freeze
+
+      # Host-app Rack middleware stacked in front of the dashboard, newest
+      # last. Each entry is `[middleware, args, block]`. Returns a frozen copy
+      # so the memoized chain (`#rack_app`) can only be invalidated through
+      # `#use` — direct mutation can't silently desync it.
+      def middlewares
+        @middlewares.dup.freeze
+      end
+
+      def initialize
+        @authorization = nil
+        @read_only = env_read_only?
+        @middlewares = []
+        @rack_app = nil
+      end
+
+      # Registers a `(env, method, path) -> truthy/falsey` block. Re-calling
+      # overwrites; the spec exposes a single hook, not a chain.
+      def authorization(&block)
+        @authorization = block if block
+        @authorization
+      end
+
+      # Sidekiq-compatible (`Sidekiq::Web.use`). Registers a Rack middleware
+      # that wraps the dashboard, in front of the authorization hook, so a
+      # host app can gate the UI with Devise/Warden/Sorcery/Rack::Auth::Basic
+      # without writing its own middleware. `args` and an optional block pass
+      # straight through to the middleware's `new`. Call before the first
+      # request (i.e. from an initializer) — the chain is built once.
+      def use(middleware, *args, &block)
+        @middlewares << [middleware, args, block]
+        @rack_app = nil
+      end
+
+      # Builds (once) the host-middleware chain wrapping `inner` and memoizes
+      # it on this Config. `reset_config!` swaps in a fresh Config, so each
+      # test rebuilds cleanly; production builds exactly once at boot.
+      def rack_app(inner)
+        @rack_app ||= begin
+          stack = @middlewares
+          ::Rack::Builder.new do
+            stack.each { |middleware, args, block| use(middleware, *args, &block) }
+            run inner
+          end.to_app
+        end
+      end
+
+      # Read-only mode. When on, the Authorization middleware blocks every
+      # non-GET request (retry/kill/requeue/delete/pause/resume/clear) with
+      # 403, and the SPA hides destructive actions via the /api/meta flag.
+      # Defaults from WURK_WEB_READ_ONLY=1 so a viewer-only deploy (e.g. the
+      # public demo) needs no Ruby config.
+      def read_only=(value)
+        @read_only = value.is_a?(String) ? !FALSEY_STRINGS.include?(value.strip.downcase) : !!value
+      end
+
+      def read_only?
+        @read_only
+      end
+
+      def reset!
+        @authorization = nil
+        @read_only = env_read_only?
+        @middlewares = []
+        @rack_app = nil
+      end
+
+      # Returns true when no block is registered, otherwise the block's
+      # truthiness. The `path` argument is the engine-relative path so a
+      # consumer mounting under `/wurk` sees `/api/stats`, not the host's
+      # absolute path — that matches Sidekiq's contract.
+      def authorized?(env, method, path)
+        return true if @authorization.nil?
+
+        !!@authorization.call(env, method, path)
+      end
+
+      private
+
+      def env_read_only?
+        ENV['WURK_WEB_READ_ONLY'] == '1'
+      end
+    end
+
+    class << self
+      def config
+        @config ||= Config.new
+      end
+
+      def configure
+        yield config
+      end
+
+      # Class-level shorthand for `config.use` — mirrors `Sidekiq::Web.use`.
+      def use(...)
+        config.use(...)
+      end
+
+      # Test helper — exposed for parity with `Wurk::Limiter.reset_config!`.
+      # Production callers should not need to drop the auth block at runtime.
+      def reset_config!
+        @config = nil
+      end
+    end
+
+    # Rack middleware inserted into the engine. Resolves PATH_INFO + REQUEST_METHOD
+    # from `env` and delegates to `Wurk::Web.config`. The engine's mount path
+    # is stripped via `SCRIPT_NAME` so the callback sees engine-relative paths.
+    class Authorization
+      FORBIDDEN_BODY = 'Forbidden'
+      READ_ONLY_BODY = 'Read-only mode'
+      FORBIDDEN_HEADERS = { 'Content-Type' => 'text/plain' }.freeze
+      # Methods allowed while read-only. Anything else is a mutation and 403s.
+      SAFE_METHODS = %w[GET HEAD OPTIONS].freeze
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        method = env['REQUEST_METHOD']
+        path = env['PATH_INFO'].to_s
+        config = Wurk::Web.config
+        return forbidden(FORBIDDEN_BODY) unless config.authorized?(env, method, path)
+        return forbidden(READ_ONLY_BODY) if config.read_only? && !SAFE_METHODS.include?(method)
+
+        @app.call(env)
+      end
+
+      private
+
+      def forbidden(body)
+        [403, FORBIDDEN_HEADERS.dup, [body]]
+      end
+    end
+
+    # Engine Rack middleware that applies the host-registered `Wurk::Web.use`
+    # chain (Devise/Warden/Sorcery/Rack::Auth::Basic) in front of the
+    # dashboard. Inserted ahead of `Authorization` so host auth runs first and
+    # its `env` (e.g. `env['warden']`) is visible to the authorization hook.
+    # The chain is built lazily on first request — after host initializers
+    # have run — then memoized on the Config.
+    class MiddlewareStack
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        Wurk::Web.config.rack_app(@app).call(env)
+      end
+    end
+  end
+end

data/lib/wurk/web/enterprise.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative '../limiter'
+require_relative '../cron'
+require_relative '../client'
+require_relative '../metrics/query'
+
+module Wurk
+  class Web
+    # Web UI Ent-feature surface (spec: docs/target/sidekiq-ent.md §9.1).
+    # Each tab — Limits, Periodic, Historical — gets a small helper module
+    # that the API controller delegates to. The data fabric lives here so
+    # the controller stays a thin JSON shim and so library users wanting
+    # the same operations programmatically (cron management scripts,
+    # operator REPL, etc.) have a single entry point.
+    #
+    # Wurk ships these free; no license gate, no env flag.
+    module Enterprise
+      # Limits tab — list every registered limiter, filter by name, expose
+      # reset + delete. List/metrics already render via `Wurk::Limiter::Base`;
+      # this wrapper adds the name filter documented in §1.2.0+.
+      module Limits
+        module_function
+
+        # @return [Array<String>] limiter names, optionally filtered to those
+        #   whose name contains the case-insensitive substring `filter`.
+        def list(filter: nil)
+          names = Wurk.redis { |c| c.call('SMEMBERS', Wurk::Limiter::LIST_KEY) }.sort
+          return names if filter.nil? || filter.to_s.empty?
+
+          needle = filter.to_s.downcase
+          names.select { |n| n.downcase.include?(needle) }
+        end
+
+        def metadata(name)
+          raw = Wurk.redis { |c| c.call('HGETALL', "lmtr:#{name}") }
+          raw.is_a?(Array) ? raw.each_slice(2).to_h : raw
+        end
+
+        # Stats-key reset: drops every `lmtr-stats:` / state key for the
+        # named limiter while keeping its metadata + LIST membership so the
+        # row remains in the UI. Mirrors the §1.5 `#reset` surface — the
+        # name is wire-compat, so the trailing-? rule doesn't apply here.
+        def reset(name) # rubocop:disable Naming/PredicateMethod
+          Wurk.redis do |c|
+            %W[lmtr-cs:#{name} lmtr-b:#{name} lmtr-w:#{name} lmtr-l:#{name}
+               lmtr-p:#{name} lmtr-stats:#{name}].each { |k| c.call('DEL', k) }
+          end
+          true
+        end
+      end
+
+      # Periodic tab — list/pause/unpause/enqueue-now/history. The list view
+      # reuses `Wurk::Cron::LoopSet`; mutating actions write directly to the
+      # `loops:{lid}` HASH so they're idempotent and crash-safe.
+      module Periodic
+        module_function
+
+        def list
+          Wurk::Cron::LoopSet.new
+        end
+
+        def fetch(lid)
+          Wurk::Cron::LoopSet.new.fetch(lid)
+        end
+
+        def pause(lid)
+          set_paused(lid, '1')
+        end
+
+        def unpause(lid)
+          set_paused(lid, '0')
+        end
+
+        # Spec §2.4 "enqueue-now": pushes a one-off run with the loop's
+        # configured klass/queue/args/retry. Returns the new jid, or nil
+        # when the loop doesn't exist.
+        def enqueue_now(lid)
+          loop_obj = fetch(lid)
+          return nil unless loop_obj
+
+          Wurk::Client.new.push(
+            'class' => loop_obj.klass,
+            'args' => loop_obj.args,
+            'queue' => loop_obj.queue,
+            'retry' => loop_obj.retry_value
+          )
+        end
+
+        # Spec §8.0.1+: per-loop history list at `loop-history:{lid}`. Each
+        # entry is a `[fired_at, jid]` tuple (LPUSH'd by the poller).
+        def history(lid)
+          loop_obj = fetch(lid)
+          return [] unless loop_obj
+
+          loop_obj.history
+        end
+
+        def set_paused(lid, value) # rubocop:disable Naming/PredicateMethod
+          loop_obj = fetch(lid)
+          return false unless loop_obj
+
+          Wurk.redis { |c| c.call('HSET', "#{Wurk::Cron::LOOP_PREFIX}#{lid}", 'paused', value) }
+          true
+        end
+      end
+
+      # Historical tab — per-class and per-queue gauges over a recent window.
+      # The minute / hour HASH layout comes from `Wurk::Metrics::History`;
+      # `Query.for_job` / `Query.top_jobs` already does the fan-out. The
+      # wrapper here is a stable entry point so the controller doesn't reach
+      # into the `Query` module directly (and so we have one place to layer
+      # additional aggregations on later — global gauges across all classes).
+      module Historical
+        module_function
+
+        # Per-class time series. Pass exactly one of `minutes:` / `hours:`.
+        # Returns `[{at: Time, p:, f:, ms:}, …]` ordered oldest→newest.
+        def for_job(klass, minutes: nil, hours: nil, now: ::Time.now)
+          Wurk::Metrics::Query.for_job(klass, minutes: minutes, hours: hours, now: now)
+        end
+
+        # Global top-N rollup. Wraps `Query.top_jobs` and keeps the wire
+        # shape of `[[class_name, {p:, f:, ms:}], ...]`.
+        def top(minutes: 60, class_filter: nil)
+          Wurk::Metrics::Query.top_jobs(minutes: minutes, class_filter: class_filter)
+        end
+
+        # Cluster-total time-series for the dashboard charts. `bucket` is
+        # '1m'/'5m'/'1h'; `window` is in seconds (clamped to the bucket's
+        # retention). Returns `[{at:, p:, f:, ms:}, …]` oldest→newest.
+        def history(bucket, window:, now: ::Time.now)
+          Wurk::Metrics::Query.history(bucket, window, now: now)
+        end
+      end
+    end
+  end
+end

data/lib/wurk/web/search.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative '../queue'
+require_relative '../retry_set'
+require_relative '../scheduled_set'
+require_relative '../dead_set'
+
+module Wurk
+  class Web
+    # Pro feature parity: substring search across queues / retries /
+    # scheduled / dead. Spec: docs/target/sidekiq-pro.md §10.1 ("Search box
+    # on Retry/Scheduled/Dead pages, substring across job payload via ZSCAN").
+    # Wurk ships it free, extended to also cover the queue LIST.
+    #
+    # ZSET stores use `ZSCAN MATCH *needle*` (the substring is literal,
+    # wrapped in glob stars — Redis matches the raw JSON payload). The queue
+    # LIST falls back to a paged LRANGE filter since LIST has no SCAN.
+    #
+    # Result shape mirrors `Wurk::Api::Serializers#sorted_entry` so the SPA
+    # renders search hits with the same component as a sorted-set row.
+    class Search
+      DEFAULT_LIMIT = 100
+      MAX_LIMIT = 500
+      KINDS = %w[queues retry scheduled dead].freeze
+      QUEUE_PAGE = 50
+      ZSCAN_PAGE = 200
+
+      attr_reader :substring, :kinds, :limit
+
+      def initialize(substring, kinds: KINDS, limit: DEFAULT_LIMIT)
+        @substring = substring.to_s
+        @kinds = (Array(kinds).map(&:to_s) & KINDS)
+        @kinds = KINDS.dup if @kinds.empty?
+        @limit = limit.to_i.clamp(1, MAX_LIMIT)
+      end
+
+      # Streams matching hits across every selected store. Stops at `limit`.
+      # Yields Hashes shaped like sorted_entry payloads with an extra
+      # `:kind` discriminator + `:name` (queue name or set name).
+      def each(&)
+        return enum_for(:each) unless block_given?
+        return if @substring.empty?
+
+        emitted = 0
+        each_hit do |row|
+          yield row
+          emitted += 1
+          break if emitted >= @limit
+        end
+      end
+
+      def to_a
+        each.to_a
+      end
+
+      private
+
+      def each_hit(&block)
+        @kinds.each do |kind|
+          case kind
+          when 'queues' then search_queues(&block)
+          else search_sorted_set(kind, &block)
+          end
+        end
+      end
+
+      def search_queues
+        Queue.all.each do |queue|
+          paged_lrange(queue.name) do |payload|
+            next unless payload.include?(@substring)
+
+            record = JobRecord.new(payload, queue.name)
+            yield queue_row(queue.name, record)
+          end
+        end
+      end
+
+      def paged_lrange(queue_name, &block)
+        key = Keys.queue(queue_name)
+        page = 0
+        loop do
+          start = page * QUEUE_PAGE
+          stop = start + QUEUE_PAGE - 1
+          slice = Wurk.redis { |c| c.call('LRANGE', key, start, stop) }
+          slice.each(&block)
+          break if slice.size < QUEUE_PAGE
+
+          page += 1
+        end
+      end
+
+      def search_sorted_set(kind, &)
+        set = sorted_set_for(kind)
+        set.scan(@substring, ZSCAN_PAGE) do |value, score|
+          yield sorted_row(kind, set.name, SortedEntry.new(set, score, value))
+        end
+      end
+
+      def sorted_set_for(kind)
+        case kind
+        when 'retry'     then RetrySet.new
+        when 'scheduled' then ScheduledSet.new
+        when 'dead'      then DeadSet.new
+        end
+      end
+
+      def queue_row(name, record)
+        {
+          kind: 'queue',
+          name: name,
+          jid: record.jid,
+          klass: record.display_class,
+          args: record.display_args,
+          queue: record.queue,
+          enqueued_at: record.enqueued_at&.to_f,
+          created_at: record.created_at&.to_f
+        }
+      end
+
+      def sorted_row(kind, name, entry)
+        {
+          kind: kind,
+          name: name,
+          jid: entry.jid,
+          klass: entry.display_class,
+          args: entry.display_args,
+          queue: entry.queue,
+          enqueued_at: entry.enqueued_at&.to_f,
+          created_at: entry.created_at&.to_f,
+          score: entry.score,
+          at: entry.at.to_f,
+          error_class: entry['error_class'],
+          error_message: entry['error_message'],
+          retry_count: entry['retry_count']
+        }
+      end
+    end
+  end
+end

data/lib/wurk/web.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'web/config'
+require_relative 'web/search'
+require_relative 'web/enterprise'
+
+module Wurk
+  # Web UI namespace. Holds three sibling concerns:
+  #
+  #   * `Wurk::Web::Config` + `Wurk::Web::Authorization` — the Rack-level
+  #     authorization hook (sidekiq-ent §9.2), 403 on falsey.
+  #   * `Wurk::Web::Search` — Pro substring search across queues/retries/
+  #     scheduled/dead (ZSCAN + glob; sidekiq-pro §10.1).
+  #   * `Wurk::Web::Enterprise` — Limits / Periodic / Historical helpers
+  #     (sidekiq-ent §9.1) used by the JSON APIs.
+  #
+  # Wurk ships every Pro/Ent web feature free. Loading this file is enough
+  # to make `Wurk::Web.configure` available — no separate require needed.
+  #
+  # The class body is intentionally empty — every concern lives in a sibling
+  # file already required above. Rubocop's Lint/EmptyClass is disabled
+  # because this is a namespace anchor, not a missing-implementation bug.
+  class Web # rubocop:disable Lint/EmptyClass
+  end
+end

data/lib/wurk/work_set.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Wurk
+  # Live snapshot of currently-executing jobs across the cluster. Reads
+  # `<identity>:work` HASH per registered process; each field is a thread
+  # id → JSON payload. The data lags reality by up to one heartbeat (10s)
+  # since heartbeats `UNLINK` and rewrite the hash atomically.
+  #
+  # Wire-compat is sacred — every Redis call matches Sidekiq OSS exactly.
+  # Spec: docs/target/sidekiq-free.md §19.7.
+  class WorkSet
+    include Enumerable
+
+    # Optional `processes_key:` allows tests to operate on a namespaced
+    # SET; production callers always use `Keys::PROCESSES` (wire-compat).
+    def initialize(processes_key: Keys::PROCESSES)
+      @processes_key = processes_key
+    end
+
+    # Pipelined `<identity>:work` HGETALL per known process. Yields
+    # (process_id, thread_id, Work). Result sorted by `run_at` so the
+    # oldest in-flight job appears first — dashboards rely on this order.
+    def each
+      return enum_for(:each) unless block_given?
+
+      collect_rows.sort_by { |(_, _, work)| work.run_at }.each { |row| yield(*row) }
+    end
+
+    # Sum of `busy` HASH field across every known identity. Lagged by one
+    # heartbeat. Pipelined HGET — unbounded by process count but each
+    # call is O(1) on the Redis side.
+    def size
+      Wurk.redis do |conn|
+        procs = conn.call('SMEMBERS', @processes_key)
+        next 0 if procs.empty?
+
+        conn.pipelined do |pipe|
+          procs.each { |key| pipe.call('HGET', key, 'busy') }
+        end.sum(&:to_i)
+      end
+    end
+
+    # O(n) scan for a JID across all in-flight jobs. Returns nil when no
+    # match. Slow — not for app logic. Aliased as `find_work_by_jid` for
+    # Sidekiq wire-compat.
+    def find_work(jid)
+      each do |_process_id, _thread_id, work|
+        return work if work.job.jid == jid
+      end
+      nil
+    end
+    alias find_work_by_jid find_work
+
+    private
+
+    def collect_rows
+      procs, all_works = fetch_work_hashes
+      procs.zip(all_works).flat_map do |key, workers|
+        rows_for(key, workers)
+      end
+    end
+
+    def fetch_work_hashes
+      Wurk.redis do |conn|
+        ids = conn.call('SMEMBERS', @processes_key).sort
+        next [[], []] if ids.empty?
+
+        works = conn.pipelined do |pipe|
+          ids.each { |id| pipe.call('HGETALL', "#{id}:work") }
+        end
+        [ids, works]
+      end
+    end
+
+    def rows_for(key, workers)
+      workers.filter_map do |tid, json|
+        next nil if json.nil? || json.empty?
+
+        [key, tid, Work.new(key, tid, Wurk.load_json(json))]
+      end
+    end
+  end
+
+  # One in-flight job. The `payload` field is the raw JSON the processor
+  # is currently executing; `job` lazily wraps it in a JobRecord so
+  # downstream code can read class/args/jid without re-parsing.
+  #
+  # Spec: docs/target/sidekiq-free.md §19.7.
+  class Work
+    attr_reader :process_id, :thread_id
+
+    def initialize(pid, tid, hsh)
+      @process_id = pid
+      @thread_id = tid
+      @hsh = hsh
+    end
+
+    def queue   = @hsh['queue']
+    def payload = @hsh['payload']
+
+    # Float epoch seconds → Time. Heartbeat writes `run_at` as Float, so
+    # we don't have to handle the dual ms/secs format JobRecord does.
+    def run_at
+      ::Time.at(@hsh['run_at'])
+    end
+
+    def job
+      @job ||= JobRecord.new(payload)
+    end
+  end
+
+  # Deprecated alias. Sidekiq <8 used `Workers` for what is now `WorkSet`;
+  # third-party gems may still reference it. Resolved at load time so
+  # the alias survives a constant lookup by either name.
+  Workers = WorkSet
+end

data/lib/wurk/worker/setter.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative '../job_util'
+
+module Wurk
+  module Worker
+    # Aliased as `Sidekiq::Job::Setter`. Per-call option carrier returned
+    # by `Worker.set(opts)`. Holds string-keyed overrides and exposes the
+    # same `perform_*` surface as the worker class itself.
+    #
+    # `set(sync: true)` makes `perform_async` invoke `perform_inline` —
+    # required for testing-mode parity.
+    #
+    # Spec: docs/target/sidekiq-free.md §6.3 (Sidekiq::Job::Setter).
+    class Setter
+      include Wurk::JobUtil
+
+      def initialize(klass, opts)
+        @klass = klass
+        @opts = normalize_opts(opts)
+      end
+
+      def set(options)
+        @opts.merge!(normalize_opts(options))
+        self
+      end
+
+      def perform_async(*args)
+        return perform_inline(*args) if @opts['sync']
+
+        @klass.client_push(@opts.merge('class' => @klass, 'args' => args))
+      end
+
+      def perform_inline(*)
+        @klass.new.perform(*)
+      end
+      alias perform_sync perform_inline
+
+      def perform_in(interval, *args)
+        ts = absolute_at(interval)
+        item = @opts.merge('class' => @klass, 'args' => args)
+        item['at'] = ts if ts && ts > now_seconds
+        @klass.client_push(item)
+      end
+      alias perform_at perform_in
+
+      def perform_bulk(args, **opts)
+        merged = @opts.merge(opts.transform_keys(&:to_s)).merge(
+          'class' => @klass,
+          'args' => args
+        )
+        @klass.build_client.push_bulk(merged)
+      end
+
+      private
+
+      def absolute_at(interval)
+        unless interval.is_a?(Numeric) || interval.is_a?(Time)
+          raise ArgumentError, "interval must be Numeric or Time, got #{interval.class}"
+        end
+
+        seconds = interval.to_f
+        seconds < Wurk::Worker::SCHEDULED_THRESHOLD ? now_seconds + seconds : seconds
+      end
+
+      def now_seconds
+        ::Process.clock_gettime(::Process::CLOCK_REALTIME)
+      end
+
+      # Lifts wait/wait_until → at; stringifies keys. Matches Sidekiq's
+      # Setter initializer normalization exactly.
+      def normalize_opts(opts)
+        result = {}
+        opts.each do |k, v|
+          key = k.to_s
+          case key
+          when 'wait', 'wait_until' then result['at'] = wait_to_seconds(v)
+          else result[key] = v
+          end
+        end
+        result
+      end
+
+      def wait_to_seconds(value)
+        case value
+        when Time then value.to_f
+        when Numeric then ::Process.clock_gettime(::Process::CLOCK_REALTIME) + value.to_f
+        else raise ArgumentError, "wait/wait_until must be Numeric or Time, got #{value.class}"
+        end
+      end
+    end
+  end
+end