wurk 0.0.1

data/app/controllers/wurk/api_controller.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require_relative 'api/serializers'
+require_relative 'api/pagination'
+require 'wurk/web'
+
+module Wurk
+  # JSON APIs consumed by the React SPA. Action methods stay thin; mapping to
+  # the wire shape lives in `Wurk::Api::Serializers`, and pagination lives in
+  # `Wurk::Api::Pagination`. SSE lives in #stream.
+  #
+  # Wire-compat: every payload field reads from the canonical Wurk inspector
+  # objects (Stats, Queue, RetrySet, ScheduledSet, DeadSet, ProcessSet,
+  # BatchSet, Cron::LoopSet) so dashboards stay aligned with the Redis schema
+  # in `docs/target/sidekiq-{free,pro,ent}.md`.
+  class ApiController < ApplicationController
+    include ActionController::Live
+
+    STREAM_TICK_SECONDS = 2.0
+    STREAM_MAX_DURATION = 600.0
+
+    HISTORY_WINDOW_UNITS = { 's' => 1, 'm' => 60, 'h' => 3600, 'd' => 86_400 }.freeze
+    DEFAULT_HISTORY_WINDOW = 24 * 3600
+
+    skip_forgery_protection only: %i[
+      stream reset_limiter pause_cron unpause_cron enqueue_cron
+    ]
+
+    # Boot-time flags the SPA reads once to shape the UI (e.g. hide destructive
+    # actions and show the read-only banner). Always a GET, so it stays
+    # reachable while read-only mode blocks mutations.
+    def meta
+      render json: { read_only: ::Wurk::Web.config.read_only? }
+    end
+
+    def stats
+      render json: ::Wurk::Api::Serializers.stats_payload(::Wurk::Stats.new)
+    end
+
+    def queues
+      render json: ::Wurk::Stats.new.queue_summaries.map { |q| ::Wurk::Api::Serializers.queue_summary(q) }
+    end
+
+    def queue
+      q = ::Wurk::Queue.new(params[:name].to_s)
+      page = ::Wurk::Api::Pagination.window(params)
+      jobs = ::Wurk::Api::Pagination.slice(q, page) { |rec| ::Wurk::Api::Serializers.job_record(rec) }
+      render json: {
+        name: q.name, size: q.size, latency: q.latency, paused: q.paused?,
+        page: page[:page], count: page[:count], jobs: jobs
+      }
+    end
+
+    def retries   = render_sorted_set(::Wurk::RetrySet.new)
+    def scheduled = render_sorted_set(::Wurk::ScheduledSet.new)
+    def dead      = render_sorted_set(::Wurk::DeadSet.new)
+
+    def processes
+      render json: ::Wurk::ProcessSet.new.map { |p| ::Wurk::Api::Serializers.process_row(p) }
+    end
+
+    def batches
+      set = ::Wurk::BatchSet.new
+      page = ::Wurk::Api::Pagination.window(params)
+      rows = ::Wurk::Api::Pagination.slice(set, page) { |status| status.data.transform_keys(&:to_sym) }
+      render json: { total: set.size, page: page[:page], count: page[:count], batches: rows }
+    end
+
+    def batch
+      status = ::Wurk::Batch::Status.new(params[:bid].to_s)
+      return render(json: { error: 'unknown batch' }, status: :not_found) unless status.exists?
+
+      render json: status.data.transform_keys(&:to_sym)
+    rescue ::ArgumentError
+      render json: { error: 'unknown batch' }, status: :not_found
+    end
+
+    def limiters
+      names = ::Wurk::Web::Enterprise::Limits.list(filter: params[:substr])
+      page = ::Wurk::Api::Pagination.window(params)
+      render json: { total: names.size, page: page[:page], count: page[:count], limiters: limiter_rows(names, page) }
+    end
+
+    def reset_limiter
+      ::Wurk::Web::Enterprise::Limits.reset(params[:name].to_s)
+      render json: { ok: true }
+    end
+
+    def cron
+      now = ::Time.now.to_i
+      render json: ::Wurk::Cron::LoopSet.new.map { |lp| ::Wurk::Api::Serializers.cron_row(lp, now) }
+    end
+
+    def pause_cron   = render_cron_action(::Wurk::Web::Enterprise::Periodic.pause(params[:lid].to_s))
+    def unpause_cron = render_cron_action(::Wurk::Web::Enterprise::Periodic.unpause(params[:lid].to_s))
+
+    def enqueue_cron
+      jid = ::Wurk::Web::Enterprise::Periodic.enqueue_now(params[:lid].to_s)
+      return render(json: { error: 'unknown loop' }, status: :not_found) if jid.nil?
+
+      render json: { ok: true, jid: jid }
+    end
+
+    def cron_history
+      render json: { lid: params[:lid].to_s, history: ::Wurk::Web::Enterprise::Periodic.history(params[:lid].to_s) }
+    end
+
+    def metrics
+      minutes = ::Wurk::Api::Pagination.clamp_int(params[:minutes], 1, ::Wurk::Metrics::Query::MAX_MINUTES, 60)
+      rows = ::Wurk::Web::Enterprise::Historical.top(minutes: minutes, class_filter: params[:substr])
+      render json: { minutes: minutes, top_jobs: rows.map { |(klass, totals)| ::Wurk::Api::Serializers.metric_row(klass, totals) } }
+    rescue ::Wurk::Metrics::Query::WindowTooWide => e
+      render json: { error: e.message }, status: :bad_request
+    end
+
+    def metrics_for_job
+      klass = params[:klass].to_s
+      minutes, hours = metrics_window(params)
+      rows = ::Wurk::Web::Enterprise::Historical.for_job(klass, minutes: minutes, hours: hours)
+      series = rows.map { |row| row.merge(at: row[:at].to_f) }
+      render json: { klass: klass, minutes: minutes, hours: hours, series: series }
+    rescue ::ArgumentError, ::Wurk::Metrics::Query::WindowTooWide => e
+      render json: { error: e.message }, status: :bad_request
+    end
+
+    # Cluster-total throughput/failures time-series for the dashboard charts.
+    # `:bucket` is 1m/5m/1h; `?window=24h` (s/m/h/d suffix) is clamped to the
+    # bucket's retention. Recharts-ready array under `series`.
+    def history
+      window = parse_window(params[:window])
+      series = ::Wurk::Web::Enterprise::Historical.history(params[:bucket].to_s, window: window)
+      render json: { bucket: params[:bucket].to_s, window: window, series: series.map { |row| ::Wurk::Api::Serializers.history_point(row) } }
+    rescue ::ArgumentError => e
+      render json: { error: e.message }, status: :bad_request
+    end
+
+    def search
+      substr = params[:substr].to_s
+      return render(json: { substr: substr, total: 0, hits: [] }) if substr.empty?
+
+      hits = ::Wurk::Web::Search.new(substr, kinds: parse_search_kinds(params), limit: parse_search_limit(params)).to_a
+      render json: { substr: substr, total: hits.size, hits: hits }
+    end
+
+    # SSE: one `event: stats` per tick with a fresh Stats snapshot. Caps at
+    # `STREAM_MAX_DURATION` so a stale browser tab can't tie a Rails worker
+    # forever — the client reconnects automatically when the stream closes.
+    #
+    # `?max_duration=` and `?tick=` are test/debug knobs; the SPA never sets
+    # them. `?max_duration=0` emits one tick and closes.
+    def stream
+      stream_headers!
+      clamp = ::Wurk::Api::Pagination.method(:clamp_float)
+      tick = clamp.call(params[:tick], 0.0, STREAM_TICK_SECONDS, STREAM_TICK_SECONDS)
+      max_dur = clamp.call(params[:max_duration], 0.0, STREAM_MAX_DURATION, STREAM_MAX_DURATION)
+      sse = ::ActionController::Live::SSE.new(response.stream, retry: (STREAM_TICK_SECONDS * 1000).to_i)
+      drive_stream(sse, tick, max_dur)
+    end
+
+    private
+
+    def render_sorted_set(set)
+      page = ::Wurk::Api::Pagination.window(params)
+      total = set.size
+      entries = ::Wurk::Api::Pagination.slice(set, page) { |entry| ::Wurk::Api::Serializers.sorted_entry(entry) }
+      render json: { total: total, page: page[:page], count: page[:count], entries: entries }
+    end
+
+    # substr is already applied by Limits.list (matches on name), so slice the
+    # filtered names directly — only the page's rows pay the per-limiter Redis
+    # reads in limiter_row (which folds in live status).
+    def limiter_rows(names, page)
+      (names.slice(page[:page] * page[:count], page[:count]) || []).map do |name|
+        ::Wurk::Api::Serializers.limiter_row(name, limiter_meta(name))
+      end
+    end
+
+    def limiter_meta(name)
+      raw = ::Wurk.redis { |c| c.call('HGETALL', "lmtr:#{name}") }
+      raw.is_a?(Array) ? raw.each_slice(2).to_h : raw
+    end
+
+    def stream_headers!
+      response.headers['Content-Type'] = 'text/event-stream'
+      response.headers['Cache-Control'] = 'no-cache'
+      response.headers['X-Accel-Buffering'] = 'no'
+    end
+
+    def drive_stream(sse, tick, max_dur)
+      deadline = monotime + max_dur
+      loop do
+        sse.write(stream_tick_payload, event: 'stats')
+        break if monotime >= deadline
+
+        sleep tick
+      end
+    rescue ::IOError, ::ActionController::Live::ClientDisconnected
+      # client closed; nothing to clean up.
+    ensure
+      sse.close
+    end
+
+    def monotime
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+
+    def stream_tick_payload
+      ::Wurk::Api::Serializers.stats_payload(::Wurk::Stats.new).merge(at: ::Time.now.to_f)
+    end
+
+    def render_cron_action(success)
+      return render(json: { error: 'unknown loop' }, status: :not_found) unless success
+
+      render json: { ok: true }
+    end
+
+    def parse_search_kinds(params)
+      params[:kinds].is_a?(::Array) ? params[:kinds] : params[:kinds].to_s.split(',')
+    end
+
+    def parse_search_limit(params)
+      ::Wurk::Api::Pagination.clamp_int(
+        params[:limit], 1, ::Wurk::Web::Search::MAX_LIMIT, ::Wurk::Web::Search::DEFAULT_LIMIT
+      )
+    end
+
+    # Resolves the per-class metrics window. `minutes:` wins when present;
+    # `hours:` is used otherwise; default falls back to 60 minutes so callers
+    # that pass neither still get a useful series.
+    # `?window=24h` → seconds. Accepts an s/m/h/d suffix (bare number = seconds).
+    # Falls back to 24h on a missing or unparseable value; the Query layer
+    # clamps the result to the bucket's retention.
+    def parse_window(raw)
+      match = raw.to_s.strip.downcase.match(/\A(\d+)([smhd]?)\z/)
+      return DEFAULT_HISTORY_WINDOW unless match
+
+      Integer(match[1]) * HISTORY_WINDOW_UNITS.fetch(match[2].empty? ? 's' : match[2])
+    end
+
+    def metrics_window(params)
+      pagination = ::Wurk::Api::Pagination
+      minutes = pagination.clamp_int(params[:minutes], 1, ::Wurk::Metrics::Query::MAX_MINUTES, 60) if params[:minutes]
+      hours   = pagination.clamp_int(params[:hours],   1, ::Wurk::Metrics::Query::MAX_HOURS,   24) if params[:hours]
+      minutes ||= 60 if hours.nil?
+      [minutes, hours]
+    end
+  end
+end

data/app/controllers/wurk/application_controller.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Wurk
+  class ApplicationController < ::ActionController::Base
+    protect_from_forgery with: :exception
+  end
+end

data/app/controllers/wurk/dashboard_controller.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module Wurk
+  # Serves the SPA shell. Everything else is JSON from ApiController.
+  #
+  # Production: returns the precompiled index.html shipped in
+  # vendor/assets/dashboard. The release pipeline (`frontend:build` →
+  # `gem build`) writes both that file and the wurk-manifest.json validated
+  # at engine boot.
+  #
+  # Development: when WURK_VITE_DEV=1 is set, fetches the shell from the
+  # Vite dev server (default :5173) so contributors get HMR without
+  # rebuilding the bundle on every change.
+  class DashboardController < ApplicationController
+    VITE_DEV_URL = 'http://localhost:5173/'
+    INDEX_REL_PATH = ['vendor', 'assets', 'dashboard', 'index.html'].freeze
+
+    def index
+      render layout: false, html: spa_html.html_safe
+    end
+
+    private
+
+    def spa_html
+      ENV['WURK_VITE_DEV'] == '1' ? fetch_vite_dev_shell : read_built_index
+    end
+
+    def fetch_vite_dev_shell
+      uri = ::URI.parse(VITE_DEV_URL)
+      ::Net::HTTP.get(uri)
+    rescue ::StandardError => e
+      raise "Wurk dashboard: cannot reach Vite dev server at #{VITE_DEV_URL} " \
+            "(#{e.class}: #{e.message}). Run `bin/rake frontend:dev` from the gem root."
+    end
+
+    def read_built_index
+      path = ::Wurk::Engine.root.join(*INDEX_REL_PATH)
+      unless path.exist?
+        raise "Wurk dashboard: precompiled SPA index.html missing at #{path}. " \
+              'Run `bin/rake frontend:build`.'
+      end
+      path.read
+    end
+  end
+end

data/config/locales/en.yml

@@ -0,0 +1,15 @@
+en:
+  wurk:
+    dashboard:
+      title: "Wurk"
+    nav:
+      overview: "Overview"
+      queues: "Queues"
+      retries: "Retries"
+      scheduled: "Scheduled"
+      dead: "Dead"
+      processes: "Processes"
+      batches: "Batches"
+      limiters: "Limiters"
+      cron: "Cron"
+      metrics: "Metrics"

data/config/routes.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+Wurk::Engine.routes.draw do
+  root to: 'dashboard#index'
+
+  # JSON APIs consumed by the SPA. Nested under whatever mount the host chose.
+  scope :api, defaults: { format: :json } do
+    get  'meta',             to: 'api#meta'
+    get  'stats',            to: 'api#stats'
+    get  'queues',           to: 'api#queues'
+    get  'queues/:name',     to: 'api#queue', as: :api_queue
+    get  'retries',          to: 'api#retries'
+    get  'scheduled',        to: 'api#scheduled'
+    get  'dead',             to: 'api#dead'
+    get  'processes',        to: 'api#processes'
+    get  'batches',          to: 'api#batches'
+    get  'batches/:bid',     to: 'api#batch', as: :api_batch
+    get  'limiters',         to: 'api#limiters'
+    post 'limiters/:name/reset', to: 'api#reset_limiter', as: :api_reset_limiter
+    get  'cron',             to: 'api#cron'
+    post 'cron/:lid/pause',  to: 'api#pause_cron', as: :api_pause_cron
+    post 'cron/:lid/unpause', to: 'api#unpause_cron', as: :api_unpause_cron
+    post 'cron/:lid/enqueue', to: 'api#enqueue_cron', as: :api_enqueue_cron
+    get  'cron/:lid/history', to: 'api#cron_history', as: :api_cron_history
+    get  'metrics',          to: 'api#metrics'
+    get  'metrics/:klass',   to: 'api#metrics_for_job', as: :api_metrics_for_job, constraints: { klass: %r{[^/]+} }
+    get  'history/:bucket',  to: 'api#history', as: :api_history
+    get  'search',           to: 'api#search'
+    get  'stream',           to: 'api#stream' # SSE
+  end
+
+  # SPA catch-all — let React Router handle the rest.
+  get '*path', to: 'dashboard#index', constraints: ->(req) { req.format == :html }
+end

data/exe/wurk

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Standalone runner. Does NOT load the Rails engine.
+# Usage: `exe/wurk -C config/wurk.yml`
+
+$stdout.sync = true
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'wurk'
+
+begin
+  cli = Wurk::CLI.instance
+  cli.parse
+  cli.run
+rescue StandardError => e
+  raise e if $DEBUG
+
+  warn "wurk: #{e.message}"
+  warn e.backtrace.join("\n")
+  exit 1
+end

data/lib/active_job/queue_adapters/wurk_adapter.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# ActiveJob adapter. Rails resolves `:wurk` to this class via the
+# QueueAdapters lookup convention (`const_get("WurkAdapter")`). The file is
+# loaded eagerly by lib/wurk/engine.rb so the constant is defined before any
+# host app sets `config.active_job.queue_adapter = :wurk`.
+#
+# Spec: docs/target/sidekiq-free.md §28 (ActiveJob integration).
+
+begin
+  gem 'activejob', '>= 7.0'
+  require 'active_job'
+  require_relative '../../wurk/active_job/wrapper'
+
+  ActiveSupport.on_load(:active_job) do
+    # Lets native AJs configure Wurk options directly — `sidekiq_options retry: 3`
+    # etc. Skip when already included (e.g. Sidekiq loaded alongside in a mixed
+    # codebase mid-migration).
+    include Wurk::Job::Options unless respond_to?(:sidekiq_options)
+  end
+
+  module ActiveJob
+    module QueueAdapters
+      # Older Rails ships a built-in placeholder; remove before defining.
+      remove_const(:WurkAdapter) if const_defined?(:WurkAdapter, false)
+
+      parent = const_defined?(:AbstractAdapter) ? AbstractAdapter : Object
+      class WurkAdapter < parent
+        # Class var (not class ivar) so subclasses share the same stop flag —
+        # matches Sidekiq exactly, which third-party gems read directly.
+        @@stopping = false # rubocop:disable Style/ClassVars
+
+        callback = -> { @@stopping = true } # rubocop:disable Style/ClassVars
+
+        Wurk.configure_client { |config| config.on(:quiet, &callback) }
+        Wurk.configure_server { |config| config.on(:quiet, &callback) }
+
+        # Defer enqueue until the surrounding DB transaction commits so we
+        # never push a job whose row hasn't landed. Matches Sidekiq.
+        def enqueue_after_transaction_commit?
+          true
+        end
+
+        def enqueue(job)
+          wrapper = Sidekiq::ActiveJob::Wrapper.set(
+            wrapped: job.class,
+            queue: job.queue_name
+          )
+          job.provider_job_id = wrapper.perform_async(job.serialize)
+        end
+
+        def enqueue_at(job, timestamp)
+          job.provider_job_id = Sidekiq::ActiveJob::Wrapper.set(
+            wrapped: job.class,
+            queue: job.queue_name
+          ).perform_at(timestamp, job.serialize)
+        end
+
+        def enqueue_all(jobs)
+          jobs.group_by(&:class).sum { |job_class, group| push_grouped_by_queue(job_class, group) }
+        end
+
+        def stopping? = @@stopping
+
+        # Backwards-compat alias. Sidekiq exposes this name for jobs enqueued
+        # by very old Rails versions that wrote the older constant in payloads.
+        JobWrapper = Sidekiq::ActiveJob::Wrapper
+
+        private
+
+        def push_grouped_by_queue(job_class, group)
+          group.group_by(&:queue_name).sum do |queue, same_queue|
+            immediate, scheduled = same_queue.partition { |j| j.scheduled_at.nil? }
+            count = 0
+            count += bulk_push(job_class, queue, immediate, scheduled: false) if immediate.any?
+            count += bulk_push(job_class, queue, scheduled, scheduled: true) if scheduled.any?
+            count
+          end
+        end
+
+        def bulk_push(job_class, queue, jobs, scheduled:)
+          items = {
+            'class' => Sidekiq::ActiveJob::Wrapper,
+            'wrapped' => job_class,
+            'queue' => queue,
+            'args' => jobs.map { |j| [j.serialize] }
+          }
+          items['at'] = jobs.map { |j| j.scheduled_at&.to_f } if scheduled
+          Sidekiq::Client.push_bulk(items).compact.size
+        end
+      end
+    end
+  end
+rescue Gem::LoadError
+  # ActiveJob not present — adapter unavailable, which matches Sidekiq behavior.
+end

data/lib/generators/wurk/install/install_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Wurk
+  module Generators
+    # `bin/rails g wurk:install`
+    # Writes a config initializer and adds a commented-out mount line to routes.
+    # The host app picks the mount path; the generator suggests /wurk.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        template "wurk.rb", "config/initializers/wurk.rb"
+      end
+
+      def insert_mount_line
+        route(%(# mount Wurk::Engine => "/wurk"  # uncomment to expose the Wurk dashboard))
+      end
+    end
+  end
+end

data/lib/generators/wurk/install/templates/wurk.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Wurk configuration. Generated by `bin/rails g wurk:install`.
+# See docs/target/sidekiq-free.md for the full surface area.
+
+Wurk.configure_server do |config|
+  # config.redis = { url: ENV.fetch("REDIS_URL", "redis://localhost:6379/0") }
+  # config.workers = 2
+  # config.concurrency = 10
+  # config.queues = %w[critical default low]
+  # config.shutdown_timeout = 25
+end
+
+Wurk.configure_client do |config|
+  # config.redis = { url: ENV.fetch("REDIS_URL", "redis://localhost:6379/0") }
+end

data/lib/wurk/active_job/wrapper.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative '../job'
+
+# Defined under the `Sidekiq::ActiveJob` namespace (not `Wurk::ActiveJob`) so
+# the canonical `class` string written to Redis stays `"Sidekiq::ActiveJob::Wrapper"`
+# — the exact wire shape Sidekiq emits. Mixed Sidekiq/Wurk worker pools can
+# read the same payloads either way. Wire-compat is sacred.
+#
+# `Wurk::ActiveJob::Wrapper` and `ActiveJob::QueueAdapters::SidekiqAdapter::JobWrapper`
+# both resolve here so legacy enqueued payloads load on the gem swap.
+#
+# Spec: docs/target/sidekiq-free.md §28.
+module Sidekiq
+  module ActiveJob
+    class Wrapper
+      include Wurk::Job
+
+      def perform(job_data)
+        ::ActiveJob::Base.execute(job_data.merge('provider_job_id' => jid))
+      end
+    end
+  end
+end
+
+# Wurk-namespaced alias kept tight against the Sidekiq definition above; the
+# extra module is a pure constant rebind, not a second class definition.
+module Wurk # rubocop:disable Style/OneClassPerFile
+  module ActiveJob
+    Wrapper = ::Sidekiq::ActiveJob::Wrapper
+  end
+end

data/lib/wurk/api/fast.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative '../lua'
+require_relative '../job_record'
+
+module Wurk
+  module API
+    # Pro parity (§11): Lua-backed O(1)-round-trip replacements for the
+    # ruby-side LRANGE / ZSCAN loops in Queue and SortedSet. Mixed into the
+    # existing data API classes so the surface is `Sidekiq::Queue#delete_job(jid)`,
+    # `Sidekiq::DeadSet#scan(pattern) { |JobRecord| … }` etc. — wire-compat
+    # with Pro consumer code that drops in on a one-line require swap.
+    #
+    # We don't reimplement `Queue#size` (already LLEN, unchanged per spec).
+    module Fast
+      # Extension to Wurk::Queue. Pure server-side delete by jid / class — no
+      # network round-trips per match. Returns the count of payloads removed.
+      module QueueExt
+        # @return [Integer] payloads removed (0 when jid absent; >0 only in
+        #   the corner case of duplicate-jid corruption).
+        def delete_job(jid)
+          raise ArgumentError, 'jid required' if jid.nil? || jid.to_s.empty?
+
+          Wurk.redis do |conn|
+            Wurk::Lua::Loader.eval_cached(
+              conn,
+              :fast_delete_job,
+              keys: [Keys.queue(name)],
+              argv: [jid.to_s]
+            )
+          end.to_i
+        end
+
+        # @param klass [Class, String, Symbol]
+        # @return [Integer] payloads removed.
+        def delete_by_class(klass)
+          klass_name = klass.is_a?(Class) ? klass.name : klass.to_s
+          raise ArgumentError, 'class name required' if klass_name.empty?
+
+          Wurk.redis do |conn|
+            Wurk::Lua::Loader.eval_cached(
+              conn,
+              :fast_delete_by_class,
+              keys: [Keys.queue(name)],
+              argv: [klass_name]
+            )
+          end.to_i
+        end
+      end
+
+      # Extension to Wurk::SortedSet / JobSet. The base `scan(match, count)`
+      # already yields `(value, score)` pairs via ZSCAN — Pro promotes the
+      # surface to yield `JobRecord` directly so callers can `entry.delete`
+      # / `entry.retry` without re-parsing JSON.
+      #
+      # The new behavior is enabled by *block arity*: a 1-arg block (or
+      # block.lambda? + a 1-param signature) receives `JobRecord`; legacy
+      # 2-arg blocks (`|value, score|`) keep the raw shape. This preserves
+      # the existing two-arg contract used by JobSet#find_job internally.
+      module SortedSetExt
+        def scan(match, count = 100, &block)
+          return enum_for(:scan, match, count) unless block
+
+          if block.arity == 1
+            super do |value, score|
+              block.call(Wurk::SortedEntry.new(self, score, value))
+            end
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end
+
+Wurk::Queue.include(Wurk::API::Fast::QueueExt)
+Wurk::SortedSet.prepend(Wurk::API::Fast::SortedSetExt)

data/lib/wurk/batch/buffer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Wurk
+  class Batch
+    # Accumulates batched payloads inside an autoflush `Batch#jobs` block so
+    # the whole block flushes in one pipeline (`autoflush == true`) or every
+    # N jobs (`autoflush == Integer`). Client#raw_push fills it; Batch#jobs
+    # drains the remainder at block exit.
+    Buffer = Struct.new(:payloads, :threshold) do
+      def add(items)
+        payloads.concat(items)
+        self
+      end
+
+      def ready?
+        !threshold.nil? && payloads.length >= threshold
+      end
+
+      def drain
+        out = payloads.dup
+        payloads.clear
+        out
+      end
+    end
+  end
+end