wurk 0.0.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4c0b4f7856306b0cec991a88fa89a2ba86f152598adb27b8b1e34607128c12a
-  data.tar.gz: 4ece7a94d1ddba50dbcb6af3b6e17c6346c7ef90642d5839d1b87cf4a12eb7e7
+  metadata.gz: 774727bf58b55972fbc4ace533c90803233ad6e4a42d6e8b8cec0f464972bae3
+  data.tar.gz: e06ddec0e9138bb50be07a50184d46b500affe8f9212d5aaa290be75b35a73da
 SHA512:
-  metadata.gz: ae6268ba18a442b30c692a3017cb6bd5a8b14fa136d5f6ae9edcf3cf5d96df1ac36bc1f5449a78f8d5f237ef70d69720c7b6b3c7a0d8730bdf8ce9ac979c9d0c
-  data.tar.gz: 2269d08c147405889c154e7ed995c346b972c19f0fcb40b42263bf498469b1bc33e297ab1e28f569d7162e3d6b208c3804134d74fbcc4c127e41ebe335b5ef14
+  metadata.gz: e0f7924f14f94fc5f4143be95389f461c988d2772cb05d4502a77d9959431420d4392a5dc7d9d390038fa372da0b492b4f0d095bb566d6abc0fc4a6bf3fa5605
+  data.tar.gz: 8cc09f2445d8e75f40cdc06ac84597748de5e2a7cbfd99ec9ad062e88ca5df03f7be7e117c221533c796304a6b90e6e47555f26d307a04a44b550b570449ceeb

data/README.md

@@ -10,6 +10,7 @@
 
 <div align="center">
 
+[![Live Demo](https://img.shields.io/badge/live%20demo-wurk.demo.developerz.ai-22c55e?logo=googlechrome&logoColor=white)](https://wurk.demo.developerz.ai/wurk)
 [![Gem Version](https://img.shields.io/gem/v/wurk.svg)](https://rubygems.org/gems/wurk)
 [![CI](https://github.com/developerz-ai/wurk/actions/workflows/test.yml/badge.svg)](https://github.com/developerz-ai/wurk/actions/workflows/test.yml)
 [![Coverage gate](https://img.shields.io/badge/coverage%20gate-line%20%E2%89%A590%25-brightgreen.svg)](https://github.com/developerz-ai/wurk/actions/workflows/test.yml)
@@ -54,6 +55,7 @@ Plus Wurk extras: a worker topology DSL, a Kubernetes liveness/readiness listene
 
 ## Documentation
 
+- **[Website](https://developerz-ai.github.io/wurk/)** · **[Wiki / full docs](https://github.com/developerz-ai/wurk/wiki)** — the pitch, install, and the complete guide.
 - **[Getting started & architecture](https://github.com/developerz-ai/wurk/blob/main/docs/idea/01-overview.md)** — how the swarm, manager, fetcher, and processor fit together.
 - **[Migrating from Sidekiq](#migrating-from-sidekiq)** — the one-line swap and what to expect.
 - **API reference (parity specs):** [Sidekiq OSS](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-free.md) · [Pro](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-pro.md) · [Enterprise](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-ent.md) — the authoritative surface Wurk matches exactly.
@@ -139,6 +141,8 @@ Knobs: `health_check(port:, bind: "0.0.0.0", ready_window: 30)`. In swarm mode o
 
 `bundle install && restart`. Wurk reads and writes the same Redis schema, so a rolling deploy can run Sidekiq and Wurk against the same Redis during the cutover. Third-party gems (sidekiq-cron, sidekiq-unique-jobs, sidekiq-scheduler, sidekiq-status, sidekiq-failures, sidekiq-throttled, …) are exercised by running their own upstream suites against Wurk in the [`ecosystem` CI job](https://github.com/developerz-ai/wurk/blob/main/.github/workflows/ecosystem.yml) (see [`test/ecosystem/`](https://github.com/developerz-ai/wurk/tree/main/test/ecosystem)).
 
+Full walkthrough — config side-by-side, the Redis key/`sidekiq_options` mapping, known incompatibilities, and a one-page cutover checklist: **[docs/migrate-from-sidekiq.md](https://github.com/developerz-ai/wurk/blob/main/docs/migrate-from-sidekiq.md)**.
+
 ## Contributing
 
 Issues and pull requests are welcome — see **[CONTRIBUTING.md](https://github.com/developerz-ai/wurk/blob/main/CONTRIBUTING.md)** for the dev setup, test layers, and conventions, and **[SECURITY.md](https://github.com/developerz-ai/wurk/blob/main/SECURITY.md)** to report a vulnerability.

data/app/controllers/wurk/api/serializers.rb

@@ -34,8 +34,13 @@ module Wurk
         { name: summary.name, size: summary.size, latency: summary.latency, paused: summary.paused? }
       end
 
+      # Host-registered custom job-info rows (spec §25.2) ride along as
+      # `custom_rows` for the SPA's job-detail modal (see Config#job_info_pairs,
+      # which gates on registration so the common no-extension case is free).
+      # Divergence: wurk evaluates these during job-list serialization — the SPA
+      # renders job detail client-side — not in a dedicated server detail view.
       def job_record(record)
-        {
+        base = {
           jid: record.jid,
           klass: record.display_class,
           args: record.display_args,
@@ -43,6 +48,8 @@ module Wurk
           enqueued_at: record.enqueued_at&.to_f,
           created_at: record.created_at&.to_f
         }
+        rows = ::Wurk::Web.config.job_info_pairs(record)
+        rows.empty? ? base : base.merge(custom_rows: rows)
       end
 
       def sorted_entry(entry)
@@ -51,7 +58,8 @@ module Wurk
           at: entry.at.to_f,
           error_class: entry['error_class'],
           error_message: entry['error_message'],
-          retry_count: entry['retry_count']
+          retry_count: entry['retry_count'],
+          error_backtrace: entry.error_backtrace
         )
       end
 
@@ -67,6 +75,10 @@ module Wurk
           quiet: process.stopping?,
           rss: process['rss'],
           rtt_us: process['rtt_us'],
+          started_at: process['started_at'],
+          cpu_model: process['cpu_model'],
+          cores: process['cores'],
+          memory_total_kb: process['memory_total_kb'],
           labels: process.labels,
           queues: process.queues,
           version: process.version,
@@ -74,6 +86,20 @@ module Wurk
         }
       end
 
+      # One in-flight job (WorkSet row) for the Busy page's process detail.
+      def work_row(process_id, thread_id, work)
+        record = work.job
+        {
+          process_id: process_id,
+          thread_id: thread_id,
+          queue: work.queue,
+          klass: record.display_class,
+          args: record.display_args,
+          jid: record.jid,
+          run_at: work.run_at.to_f
+        }
+      end
+
       def limiter_row(name, meta)
         {
           name: name,
@@ -119,6 +145,13 @@ module Wurk
         { at: row[:at], processed: row[:p], failed: row[:f], runtime_ms: row[:ms] }
       end
 
+      # One queue's size/latency gauge series (Wurk::Metrics::Query.queue_history).
+      # `points` are oldest→newest; `at` is epoch seconds at the bucket start,
+      # `size` is queue depth, `latency` is head-of-line wait in seconds.
+      def queue_history_series(row)
+        { name: row[:name], points: row[:points].map { |p| { at: p[:at], size: p[:size], latency: p[:latency] } } }
+      end
+
       def parse_options(raw)
         return {} if raw.nil? || raw.to_s.empty?
 
@@ -126,6 +159,19 @@ module Wurk
       rescue ::JSON::ParserError
         {}
       end
+
+      # One profile row for the Profiles pane. `key` drives the view/data links.
+      def profile_record(rec)
+        {
+          key: rec.key,
+          jid: rec.jid,
+          token: rec.token,
+          type: rec.type,
+          size: rec.size,
+          elapsed: rec.elapsed,
+          started_at: rec.started_at&.to_i
+        }
+      end
     end
   end
 end

data/app/controllers/wurk/api_controller.rb

@@ -24,13 +24,30 @@ module Wurk
 
     skip_forgery_protection only: %i[
       stream reset_limiter pause_cron unpause_cron enqueue_cron
+      clear_queue delete_queue_job pause_queue unpause_queue
+      retries_bulk retries_all retry_job
+      scheduled_bulk scheduled_all scheduled_job
+      dead_bulk dead_all dead_job
+      quiet_process stop_process
     ]
 
+    # Per-set action whitelists. Maps the SPA's action name to the
+    # SortedEntry/JobSet method. Anything not listed 400s — keeps the bulk/
+    # single dispatchers from reaching arbitrary methods off a request param.
+    RETRY_ACTIONS     = { 'retry' => :retry, 'delete' => :delete, 'kill' => :kill }.freeze
+    SCHEDULED_ACTIONS = { 'delete' => :delete, 'add_to_queue' => :add_to_queue }.freeze
+    DEAD_ACTIONS      = { 'retry' => :retry, 'delete' => :delete }.freeze
+
     # 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? }
+      config = ::Wurk::Web.config
+      render json: {
+        read_only: config.read_only?,
+        read_only_message: config.read_only_message,
+        custom_tabs: config.custom_tabs
+      }
     end
 
     def stats
@@ -51,14 +68,97 @@ module Wurk
       }
     end
 
+    # Empties one queue (UNLINK list + drop from the `queues` set).
+    def clear_queue
+      ::Wurk::Queue.new(params[:name].to_s).clear
+      render json: { ok: true }
+    end
+
+    # Removes a single job from a queue by jid. LREM matches exact bytes, so we
+    # locate the record (Queue#find_job) and let it delete its own value.
+    def delete_queue_job
+      record = ::Wurk::Queue.new(params[:name].to_s).find_job(params[:jid].to_s)
+      return render(json: { error: 'unknown job' }, status: :not_found) unless record
+
+      render json: { ok: true, deleted: record.delete }
+    end
+
+    # Pause/unpause a queue (Pro §6, §10.1). Idempotent; returns the resulting
+    # state so the SPA can update its toggle without a refetch round-trip.
+    def pause_queue
+      ::Wurk::Queue.new(params[:name].to_s).pause!
+      render json: { ok: true, paused: true }
+    end
+
+    def unpause_queue
+      ::Wurk::Queue.new(params[:name].to_s).unpause!
+      render json: { ok: true, paused: false }
+    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)
 
+    # --- Retry set mutations -------------------------------------------------
+    def retry_job    = single_entry_action(::Wurk::RetrySet.new, RETRY_ACTIONS, params[:cmd])
+    def retries_bulk = bulk_entry_action(::Wurk::RetrySet.new, RETRY_ACTIONS)
+
+    def retries_all
+      set = ::Wurk::RetrySet.new
+      count = case params[:cmd].to_s
+              when 'retry'  then set.retry_all
+              when 'kill'   then set.kill_all
+              when 'delete' then clear_set(set)
+              else return render(json: { error: 'unknown action' }, status: :bad_request)
+              end
+      render json: { ok: true, count: count }
+    end
+
+    # --- Scheduled set mutations ---------------------------------------------
+    def scheduled_job  = single_entry_action(::Wurk::ScheduledSet.new, SCHEDULED_ACTIONS, params[:cmd])
+    def scheduled_bulk = bulk_entry_action(::Wurk::ScheduledSet.new, SCHEDULED_ACTIONS)
+
+    def scheduled_all
+      set = ::Wurk::ScheduledSet.new
+      count = case params[:cmd].to_s
+              when 'delete'       then clear_set(set)
+              when 'add_to_queue' then drain_set(set, :add_to_queue)
+              else return render(json: { error: 'unknown action' }, status: :bad_request)
+              end
+      render json: { ok: true, count: count }
+    end
+
+    # --- Dead set mutations --------------------------------------------------
+    def dead_job  = single_entry_action(::Wurk::DeadSet.new, DEAD_ACTIONS, params[:cmd])
+    def dead_bulk = bulk_entry_action(::Wurk::DeadSet.new, DEAD_ACTIONS)
+
+    def dead_all
+      set = ::Wurk::DeadSet.new
+      count = case params[:cmd].to_s
+              when 'retry'  then set.retry_all
+              when 'delete' then clear_set(set)
+              else return render(json: { error: 'unknown action' }, status: :bad_request)
+              end
+      render json: { ok: true, count: count }
+    end
+
     def processes
       render json: ::Wurk::ProcessSet.new.map { |p| ::Wurk::Api::Serializers.process_row(p) }
     end
 
+    # Currently-executing jobs across the cluster (WorkSet), oldest first.
+    # The Busy page's process-detail modal filters client-side by process_id.
+    def workers
+      render json: ::Wurk::WorkSet.new.map { |pid, tid, work| ::Wurk::Api::Serializers.work_row(pid, tid, work) }
+    end
+
+    # Busy-page controls: SIGTSTP (quiet — drop fetch, drain in-flight) and
+    # SIGTERM (stop — graceful shutdown). Both are async; the target notices on
+    # its next heartbeat (≤10s). `identity` absent or "all" signals every live
+    # process.
+    def quiet_process = signal_processes(:quiet!)
+    def stop_process  = signal_processes(:stop!)
+
     def batches
       set = ::Wurk::BatchSet.new
       page = ::Wurk::Api::Pagination.window(params)
@@ -134,6 +234,34 @@ module Wurk
       render json: { error: e.message }, status: :bad_request
     end
 
+    # Ent §5.3 Historical snapshots from the capped `history:metrics` stream.
+    # `?limit=N` (default 1000) most-recent points, oldest→newest, each
+    # `{at:, processed:, failures:, …}`. Fields are read generically so a
+    # migrated Sidekiq Ent stream renders as-is.
+    def history_snapshots
+      limit = ::Wurk::Api::Pagination.clamp_int(
+        params[:limit], 1, ::Wurk::History::STREAM_CAP, ::Wurk::History::STREAM_DEFAULT_LIMIT
+      )
+      render json: { snapshots: ::Wurk::Web::Enterprise::Historical.snapshots(limit: limit) }
+    end
+
+    # Per-queue size/latency gauge time-series for the Metrics/Historical tab.
+    # `:bucket` is 1m/5m/1h; `?window=24h` (s/m/h/d) is clamped to the bucket's
+    # retention; optional `?queue=<name>` narrows to one queue. Each queue's
+    # `points` are Recharts-ready.
+    def queue_history
+      window = parse_window(params[:window])
+      queues = params[:queue].present? ? [params[:queue].to_s] : nil
+      series = ::Wurk::Web::Enterprise::Historical.queue_history(params[:bucket].to_s, window: window, queues: queues)
+      render json: {
+        bucket: params[:bucket].to_s,
+        window: window,
+        queues: series.map { |row| ::Wurk::Api::Serializers.queue_history_series(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?
@@ -142,6 +270,13 @@ module Wurk
       render json: { substr: substr, total: hits.size, hits: hits }
     end
 
+    # Profiles list (v8.0+). The SPA links each row to /profiles/:key (view)
+    # and /profiles/:key/data (raw blob). Newest first.
+    def profiles
+      records = ::Wurk::ProfileSet.new.map { |rec| ::Wurk::Api::Serializers.profile_record(rec) }
+      render json: records.sort_by { |r| -(r[:started_at] || 0) }
+    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.
@@ -159,6 +294,86 @@ module Wurk
 
     private
 
+    # Resolves a single entry by "<score>|<jid>" key and applies a whitelisted
+    # action. 400 on an unknown action, 404 when the key matches nothing (e.g.
+    # the entry was already retried/deleted from another tab).
+    def single_entry_action(set, actions, cmd)
+      method = actions[cmd.to_s]
+      return render(json: { error: 'unknown action' }, status: :bad_request) unless method
+
+      entries = entries_for(set, [params[:key]])
+      return render(json: { error: 'unknown job' }, status: :not_found) if entries.empty?
+
+      entries.each { |entry| entry.public_send(method) }
+      render json: { ok: true, count: entries.size }
+    end
+
+    # Bulk variant: `keys[]` + a single `cmd` applied to every resolved entry.
+    def bulk_entry_action(set, actions)
+      method = actions[params[:cmd].to_s]
+      return render(json: { error: 'unknown action' }, status: :bad_request) unless method
+
+      count = 0
+      keys = Array(params[:keys]).map(&:to_s).uniq
+      entries_for(set, keys).each do |entry|
+        entry.public_send(method)
+        count += 1
+      end
+      render json: { ok: true, count: count }
+    end
+
+    # Sends `method` (:quiet! / :stop!) to one process by identity, or to every
+    # live process when identity is blank/"all". Embedded processes are skipped
+    # (they raise on quiet!/stop! — there's no separate process to signal). 404s
+    # when a named identity isn't in the live set.
+    def signal_processes(method)
+      identity = params[:identity].to_s
+      if identity.empty? || identity == 'all'
+        count = ::Wurk::ProcessSet.new.reject(&:embedded?).each { |p| p.public_send(method) }.size
+        return render(json: { ok: true, count: count })
+      end
+
+      process = ::Wurk::ProcessSet[identity]
+      return render(json: { error: 'unknown process' }, status: :not_found) unless process
+
+      process.public_send(method) unless process.embedded?
+      render json: { ok: true, count: process.embedded? ? 0 : 1 }
+    end
+
+    # Maps "<score>|<jid>" keys to live SortedEntry objects via score-bracketed
+    # fetch (exact float match, narrowed by jid) — avoids depending on float→
+    # string round-tripping between JS and Ruby. Skips malformed/empty keys.
+    def entries_for(set, keys)
+      keys.flat_map do |key|
+        score, jid = key.to_s.split('|', 2)
+        next [] if jid.nil? || jid.empty?
+
+        set.fetch(score.to_f, jid)
+      end
+    end
+
+    # UNLINKs the whole set, returning the count removed (read before clearing
+    # so the response reports what was deleted).
+    def clear_set(set)
+      total = set.size
+      set.clear
+      total
+    end
+
+    # Drains a set by applying `method` to every entry until empty. Used for
+    # scheduled "add to queue all", where each call removes the entry and would
+    # otherwise shift the paged iterator's indices mid-scan.
+    def drain_set(set, method)
+      count = 0
+      until set.size.zero?
+        set.each do |entry|
+          entry.public_send(method)
+          count += 1
+        end
+      end
+      count
+    end
+
     def render_sorted_set(set)
       page = ::Wurk::Api::Pagination.window(params)
       total = set.size

data/app/controllers/wurk/dashboard_controller.rb

@@ -15,7 +15,14 @@ module Wurk
   # 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/'
+    # Vite serves the dev shell under its `base` (vite.config.ts), which is the
+    # same path the engine mounts assets at — so derive these from
+    # AssetMount::PREFIX to keep the Ruby side in lockstep. Fetching the server
+    # root instead returns Vite's "did you mean /wurk-assets/" hint page, not the
+    # shell (issue #181).
+    VITE_DEV_HOST = 'http://localhost:5173'
+    VITE_ASSET_BASE = "#{::Wurk::Engine::AssetMount::PREFIX}/".freeze # "/wurk-assets/"
+    VITE_DEV_URL = "#{VITE_DEV_HOST}#{VITE_ASSET_BASE}".freeze
     INDEX_REL_PATH = ['vendor', 'assets', 'dashboard', 'index.html'].freeze
 
     def index
@@ -30,12 +37,23 @@ module Wurk
 
     def fetch_vite_dev_shell
       uri = ::URI.parse(VITE_DEV_URL)
-      ::Net::HTTP.get(uri)
+      rewrite_dev_asset_urls(::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
 
+    # The shell's entry URLs (`src="/wurk-assets/@vite/client"`,
+    # `src="/wurk-assets/src/main.tsx"`) are base-absolute, but the page is
+    # served from the host origin (e.g. :3000), where that path only maps to the
+    # built bundle. Point them back at the Vite dev server so the browser loads
+    # the modules + HMR client straight from Vite (CORS-enabled in dev). Vite's
+    # `server.origin` covers runtime-generated asset URLs but not these entry
+    # tags, so rewrite them here.
+    def rewrite_dev_asset_urls(html)
+      html.gsub(/(["'])#{::Regexp.escape(VITE_ASSET_BASE)}/, "\\1#{VITE_DEV_URL}")
+    end
+
     def read_built_index
       path = ::Wurk::Engine.root.join(*INDEX_REL_PATH)
       unless path.exist?

data/app/controllers/wurk/extensions_controller.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'wurk/web/extension'
+
+module Wurk
+  # Serves third-party Web extensions (#187): `ext/:name/*subpath` runs the
+  # registered extension's matched route and returns its rendered HTML for the
+  # SPA's Extension page to embed; `ext-assets/:name/*file` serves files from
+  # the extension's `asset_paths`.
+  #
+  # Inherits DashboardController so an /ext/* URL that is actually the SPA's
+  # client-side route (no extension registered under that name — e.g. a browser
+  # refresh on /wurk/ext/<tab>/) falls through to the SPA shell instead of 404.
+  class ExtensionsController < DashboardController
+    # Extension forms carry no Rails CSRF token. Parity with Sidekiq's own
+    # CSRF model instead (spec §25.1): unsafe methods must be same-origin per
+    # Sec-Fetch-Site; cross-site requests are denied. GETs are unaffected.
+    skip_forgery_protection
+    before_action :verify_same_origin!, unless: -> { request.get? || request.head? }
+
+    def show
+      result = Web::Extension::Renderer.call(
+        name: params[:name], method: request.request_method,
+        subpath: "/#{params[:subpath]}", env: request.env, mount: request.script_name
+      )
+      return index unless result # not an extension → SPA client route; let React handle it
+
+      respond_with(result)
+    end
+
+    def asset
+      file, cache_for = Web::Extension::Renderer.asset_file(params[:name], params[:file])
+      return head :not_found unless file
+
+      response.headers['Cache-Control'] = "public, max-age=#{cache_for}"
+      send_file file, disposition: 'inline'
+    end
+
+    private
+
+    def respond_with((status, headers, body))
+      return redirect_to(headers['Location'], allow_other_host: false) if status == 302
+
+      # Extension output is host-registered server code, same trust model as
+      # Sidekiq::Web rendering its extensions — not user input.
+      render html: body.html_safe, layout: false, status: status
+    end
+
+    # Spec §25.1: unsafe methods require `Sec-Fetch-Site: same-origin` — a
+    # missing header is denied too, like stock Sidekiq (a non-browser client
+    # must spoof the header deliberately; a cookie-carrying browser can't).
+    def verify_same_origin!
+      head :forbidden unless request.headers['Sec-Fetch-Site'] == 'same-origin'
+    end
+  end
+end

data/app/controllers/wurk/profiles_controller.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module Wurk
+  # Profiles pane non-JSON endpoints (spec §25.4):
+  #
+  #   GET /profiles/:key/data  → the stored gzipped gecko JSON, streamed with a
+  #                              gzip Content-Encoding (Firefox profiler pulls
+  #                              this when given a `from-url` source).
+  #   GET /profiles/:key       → upload the profile to the Firefox profiler
+  #                              store and 302 to its public view URL.
+  #
+  # `:key` is "<token>-<jid>". The JSON list lives at /api/profiles.
+  class ProfilesController < ApplicationController
+    # CSRF protection is for state-changing form posts; these are GET reads.
+    skip_forgery_protection
+
+    def data
+      blob = profile_blob(params[:key])
+      return head(:not_found) unless blob
+
+      response.headers['Content-Encoding'] = 'gzip'
+      send_data blob, type: 'application/json', disposition: 'inline'
+    end
+
+    def show
+      blob = profile_blob(params[:key])
+      return head(:not_found) unless blob
+
+      hash = upload_to_profiler(blob)
+      return head(:bad_gateway) unless hash
+
+      redirect_to(format(::Wurk::Web.config.profile_view_url, hash), allow_other_host: true)
+    end
+
+    private
+
+    def profile_blob(key)
+      Wurk.redis { |conn| conn.call('HGET', key, 'data') }
+    end
+
+    # POSTs the gzipped profile to the Firefox profiler's compressed-store.
+    # Returns the public hash (used to build the view URL) or nil on failure.
+    def upload_to_profiler(gzipped)
+      uri = URI.parse(::Wurk::Web.config.profile_store_url)
+      res = post_gzip(uri, gzipped)
+      res.is_a?(Net::HTTPSuccess) ? res.body.to_s.strip : nil
+    rescue StandardError => e
+      Wurk.configuration.handle_exception(e, context: 'Wurk::ProfilesController#upload')
+      nil
+    end
+
+    def post_gzip(uri, body)
+      req = Net::HTTP::Post.new(uri)
+      req['Content-Encoding'] = 'gzip'
+      req['Content-Type'] = 'application/json'
+      req.body = body
+      # Explicit timeouts so a slow/unreachable profiler can't tie up the Rails
+      # request thread for Ruby's ~60s defaults.
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https',
+                                          open_timeout: 5, read_timeout: 15) do |http|
+        http.request(req)
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -8,11 +8,43 @@ Wurk::Engine.routes.draw 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  'queues/:name',     to: 'api#queue', as: :api_queue, constraints: { name: %r{[^/]+} }
+    post 'queues/:name/clear',  to: 'api#clear_queue',     as: :api_clear_queue,     constraints: { name: %r{[^/]+} }
+    post 'queues/:name/delete', to: 'api#delete_queue_job', as: :api_delete_queue_job, constraints: { name: %r{[^/]+} }
+    # Per-queue Pause/Unpause (Pro §6, §10.1): toggles membership of the `paused`
+    # SET that fetchers consult. Read-only mode 403s these via Authorization.
+    post 'queues/:name/pause',   to: 'api#pause_queue',   as: :api_pause_queue,   constraints: { name: %r{[^/]+} }
+    post 'queues/:name/unpause', to: 'api#unpause_queue', as: :api_unpause_queue, constraints: { name: %r{[^/]+} }
+
+    # Job-set mutations (retry/delete/kill/requeue/clear). The SPA posts to
+    # these; the Authorization middleware 403s every non-GET in read-only mode,
+    # so they need no extra guard. `:key` is "<score>|<jid>" (Wurk::SortedEntry#id);
+    # `all/:cmd` operates over the whole set; the bare collection POST is a bulk
+    # action over `keys[]`. Spec: docs/target/sidekiq-free.md §25.4.
+    # `all/:cmd` is intentionally unconstrained: the controller validates `:cmd`
+    # against the per-set whitelist and returns a JSON 400 for an unknown action,
+    # matching the single/bulk contract. A route-level constraint would turn that
+    # into a 404 route miss instead.
     get  'retries',          to: 'api#retries'
+    post 'retries',          to: 'api#retries_bulk',   as: :api_retries_bulk
+    post 'retries/all/:cmd', to: 'api#retries_all',    as: :api_retries_all
+    post 'retries/:key',     to: 'api#retry_job',      as: :api_retry_job,   constraints: { key: %r{[^/]+} }
     get  'scheduled',        to: 'api#scheduled'
+    post 'scheduled',          to: 'api#scheduled_bulk', as: :api_scheduled_bulk
+    post 'scheduled/all/:cmd', to: 'api#scheduled_all',  as: :api_scheduled_all
+    post 'scheduled/:key',     to: 'api#scheduled_job',  as: :api_scheduled_job, constraints: { key: %r{[^/]+} }
     get  'dead',             to: 'api#dead'
+    post 'dead',             to: 'api#dead_bulk',      as: :api_dead_bulk
+    post 'dead/all/:cmd',    to: 'api#dead_all',       as: :api_dead_all
+    post 'dead/:key',        to: 'api#dead_job',       as: :api_dead_job, constraints: { key: %r{[^/]+} }
     get  'processes',        to: 'api#processes'
+    get  'workers',          to: 'api#workers'
+    # Busy-page process control (quiet/stop). `identity` rides in the body (it
+    # contains ':' and '.', awkward as a path segment); absent or "all" signals
+    # every live process. Read-only mode 403s these via the Authorization
+    # middleware. Spec: docs/target/sidekiq-free.md §25.4 (POST /busy).
+    post 'busy/quiet', to: 'api#quiet_process', as: :api_quiet_process
+    post 'busy/stop',  to: 'api#stop_process',  as: :api_stop_process
     get  'batches',          to: 'api#batches'
     get  'batches/:bid',     to: 'api#batch', as: :api_batch
     get  'limiters',         to: 'api#limiters'
@@ -24,11 +56,32 @@ Wurk::Engine.routes.draw do
     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/snapshots', to: 'api#history_snapshots', as: :api_history_snapshots
     get  'history/:bucket',  to: 'api#history', as: :api_history
+    get  'queue-history/:bucket', to: 'api#queue_history', as: :api_queue_history
     get  'search',           to: 'api#search'
+    get  'profiles',         to: 'api#profiles'
     get  'stream',           to: 'api#stream' # SSE
   end
 
+  # Profiles (v8.0+) — not under /api: `:key/data` streams the gzipped gecko
+  # blob with a gzip Content-Encoding, and `:key` POST-uploads the profile to
+  # the Firefox profiler then 302s to its public view. `:key` is "<token>-<jid>".
+  # The `/data` route is declared first so it wins over the bare `:key` match.
+  # Spec: docs/target/sidekiq-free.md §25.4.
+  get 'profiles/:key/data', to: 'profiles#data', as: :profile_data, constraints: { key: %r{[^/]+} }
+  get 'profiles/:key',      to: 'profiles#show', as: :profile,      constraints: { key: %r{[^/]+} }
+
+  # Third-party Web extensions (#187): server-rendered route + assets. The SPA's
+  # Extension page fetches `ext/:name/<subpath>` and embeds the returned HTML;
+  # `format: false` keeps dots in subpaths/filenames out of Rails' format logic.
+  # An /ext URL with no matching registered extension falls through to the SPA
+  # shell inside the controller (it's the SPA's own /ext/:tab client route).
+  match 'ext/:name(/*subpath)', to: 'extensions#show', via: %i[get post put patch delete], as: :extension,
+                                format: false, defaults: { subpath: '' }, constraints: { name: %r{[^/]+} }
+  get 'ext-assets/:name/*file', to: 'extensions#asset', as: :extension_asset,
+                                format: false, constraints: { name: %r{[^/]+} }
+
   # SPA catch-all — let React Router handle the rest.
   get '*path', to: 'dashboard#index', constraints: ->(req) { req.format == :html }
 end

data/exe/sidekiqswarm

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Drop-in alias for `wurkswarm`. Sidekiq Enterprise apps invoke `sidekiqswarm`
+# in their Procfile / systemd unit; this keeps that exact command working after
+# a one-line gem swap. Same behavior — forks the worker swarm from a preloaded
+# parent. Spec: docs/target/sidekiq-ent.md §7.
+load File.expand_path('wurkswarm', __dir__)