wurk 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0995fd5827870e14584104a8998db58e9927339197460596567c05f2dacc7da0'
-  data.tar.gz: 8159d245826bf646a9c6025e4e06a49717f957aabe18dad5d2a5b58ed99818c0
+  metadata.gz: cbdba1bc48d5cc6029c22b78376e6b6a0b93e4f519f6c717fd3f2ce84b5900d2
+  data.tar.gz: 0d0c5e36c75c898fa05d1b448e4730391cbcf883d39402db49ac879d3168aa91
 SHA512:
-  metadata.gz: d45c20c9a8c29695c7ea2e04066dda58454fea0ce56453ed866cd111e38977fb1739ae47429a60b68380fac2f4d7fe85f232b420f92f95cba330c389ee435b5b
-  data.tar.gz: 94c5599bc28408e1e5eb30967d1b0fad4806d415a17e515774c057120d0833660f3c2860d9cf0cb2ea320ae3a27bd9ce683385ce5ace1c347d46530a96cd9a1a
+  metadata.gz: 29c1cb70a235bffed95cfa399328be393c4f653df388eff3f06a36e605f7f941ec21f1dc21b6fa832876f09635991c69087ff18dec9dc3a08cedb50f85945338
+  data.tar.gz: ca4aa23ed8658e6fc98cbe14501a1789cc38cc43a6a539c6a41fd3aebdcba97bb91fef58c84ae26f0d36cc42518b8279b348336efa93a3b4f0aaf37bf886c625

data/README.md

@@ -21,6 +21,8 @@
 
 Wurk is wire-compatible with Sidekiq — same Redis keys, same job JSON, same Ruby DSL. Swap one line in your `Gemfile` and your existing jobs, batches, limiters, cron entries, and live Redis data keep working untouched. The Pro and Enterprise feature sets ship in the same free gem, with no license check and no tiers.
 
+**On Sidekiq:** Sidekiq is the reason Ruby background processing works as well as it does. Mike Perham and Contributed Systems have maintained it for well over a decade and funded that work through Pro and Enterprise — a model that kept a critical piece of the ecosystem healthy, documented, and supported, and one the whole community has benefited from. Wurk implements Sidekiq's API because it is a genuinely good API, and exists to make a different bet about what maintenance costs now — see [Why Wurk exists](#why-wurk-exists).
+
 **On speed:** Wurk is not currently faster than stock Sidekiq — it runs at roughly 0.87×–1.02× depending on workload shape, with parity on CPU and I/O but still behind on framework overhead (noop) and boot time. Numbers, method, and the reproduction command are in [docs/benchmarks.md](docs/benchmarks.md); run them yourself with `rake bench:vs_sidekiq`.
 
 ## Install
@@ -42,7 +44,7 @@ gem "wurk"
 
 ## Feature matrix
 
-Everything below is in the one free gem. The "Sidekiq tier" column is only there to show what you'd otherwise pay for.
+Everything below is in the one free gem. The "Sidekiq tier" column maps each area onto Sidekiq's own lineup, so you can see at a glance what a migration covers.
 
 | Area | What you get | Sidekiq tier |
 |---|---|---|
@@ -53,7 +55,26 @@ Everything below is in the one free gem. The "Sidekiq tier" column is only there
 | **Encryption** | Transparent AES-256-GCM job-argument encryption with zero-downtime key rotation | Enterprise |
 | **Dashboard** | Mountable Rails engine, precompiled SolidJS SPA (no Node needed), live SSE, charts, host-app auth hook | OSS + Pro/Ent |
 
-Plus Wurk extras: a worker topology DSL, a Kubernetes liveness/readiness listener, and opt-in AI dashboard panes (anomaly detection, NL queries, backlog forecasting).
+Plus the [Wurk extras](#wurk-extras) below: a worker topology DSL, a Kubernetes liveness/readiness listener, OpenTelemetry tracing, job status/progress/results, an HTTP producer+observe API, per-job timeouts/deadlines, debounce/throttle/collapse, global per-queue concurrency caps, and DAG flows.
+
+## Wurk extras
+
+Sidekiq has no equivalent for any of these — they aren't parity, they're new surface. Each is documented as **Wurk-only**: using it ties that code to Wurk, so migrating back to plain Sidekiq means removing or reimplementing it. Everything that touches the job path is **opt-in and free when unused** — no extra Redis round trip on the hot path until you turn it on. The dashboard's theme, locale and timezone are the exception: they're active whenever the dashboard is, and cost the job path nothing either way.
+
+| Extra | What it does | Give up if you migrate back to Sidekiq |
+|---|---|---|
+| **[Job status, progress & results](docs/job-status.md)** | Opt-in `sidekiq_options track: true` persists a `status:<jid>` row — state, coalesced progress writes, the return value (size-capped, withheld under encryption) | `Wurk::Status` reads/writes and the dashboard's per-job progress bar |
+| **[HTTP producer + observe API](docs/api-http.md)** | A bearer-token-scoped `/v1` JSON API — enqueue, bulk-enqueue, inspect queues/jobs/swarm — mountable standalone, nested in the engine, or via the `wurk api` CLI | The whole `/v1` surface; non-Ruby producers lose their enqueue/inspect path |
+| **[OpenTelemetry tracing](docs/telemetry.md)** | W3C `traceparent`/`tracestate` propagated client → server, one span per attempt, linked (not force-parented) across long delays | Distributed traces across your job graph |
+| **[Flows — DAG-on-batches](docs/flows.md)** | `Wurk::Flow` chains and fans batches out/in with dependency edges, piped results between nodes, cycle/depth/width limits | The DAG builder, `pipe:` result-passing, `Flow.abandon` |
+| **[Debounce, throttle-to-slot & collapse](docs/unique-jobs.md)** | `collapse: { policy: :debounce }` coalesces bursts into one job (last payload wins); `collapse: { policy: :throttle }` admits one job per fixed time slot | Burst coalescing — every enqueue in the window runs standalone again |
+| **[Per-job timeouts & deadlines](docs/retries.md)** | `timeout:` bounds one attempt, `deadline:` bounds the whole job from enqueue, enforced by a lightweight per-capsule watchdog thread (no thread-per-job) | Runaway/stuck jobs run unbounded except for `shutdown_timeout` |
+| **[Global per-queue concurrency caps](docs/rate-limiting.md)** | `config.global_concurrency = { critical: 20 }` caps in-flight jobs for a queue across the whole cluster, folded into the fetch pipeline | The cluster-wide cap; only per-key `Limiter`s remain |
+| **Worker topology DSL** | Declare which queues/classes a given fleet role runs, in code instead of ad hoc `-q` flags | The declarative topology; fall back to CLI queue flags |
+| **[Kubernetes probes](#kubernetes-probes)** | `config.health_check` opens a thin `/live`/`/ready` HTTP listener, self-electing across a swarm's children | The built-in probe listener; roll your own liveness check |
+| **Dashboard theme, locale & timezone** | Light/dark/system theme, per-visitor locale override, and a 400-zone timezone picker for every timestamp in the SPA | Nothing server-side — this is dashboard-only |
+
+AI dashboard panes — anomaly detection, natural-language queries, error triage, and capacity forecasting — are **planned, not shipped**: they're [roadmap M5](docs/idea/13-roadmap.md#m5--ai-dashboard), after the M4.5 extras above.
 
 ## Documentation
 
@@ -182,6 +203,21 @@ end
 
 Knobs: `health_check(port:, bind: "0.0.0.0", ready_window: 30)`. In swarm mode one child owns the port; the others poll every 5s and take it over if the owner dies, so probes survive a child restart.
 
+## Why Wurk exists
+
+Sidekiq's split into OSS, Pro, and Enterprise is how a decade of serious maintenance got funded, and it worked. Ruby got a background-job library that stayed maintained, documented, and answerable to its users for longer than most infrastructure gems survive at all — and the API in this README is the one that came out of it. Wurk is standing on that work.
+
+What Wurk bets on is that the economics underneath changed. Wurk is built and maintained **AI-first** — implementation, parity suite, docs, and benchmarks are written and kept current by AI agents working under human review. That is what makes it practical to:
+
+- ship the entire Pro + Enterprise surface with no tier, no flag gate, and no license check;
+- keep parity honest mechanically rather than by hand — Sidekiq's own tests run as an oracle suite, and third-party gems (sidekiq-cron, sidekiq-unique-jobs, sidekiq-scheduler, sidekiq-status, sidekiq-failures, sidekiq-throttled) run their upstream suites against Wurk on every push;
+- keep adding surface Sidekiq doesn't have — the [Wurk extras](#wurk-extras) above landed as one release;
+- sustain that over the long run, because the marginal cost of a fix, a doc update, or a version bump is no longer somebody's week.
+
+It also means Wurk holds itself to published numbers instead of adjectives: the benchmark suite runs against stock Sidekiq every release and the results ship [as measured](docs/benchmarks.md), including the unflattering ones.
+
+None of this makes Wurk the right call for everyone. Sidekiq Pro and Enterprise come with a commercial support contract, a decade of production track record, and a human on the other end of an email. If that is what your risk profile needs, buy it — it is worth the money, and it is the reason the API Wurk implements exists in the first place.
+
 ## Migrating from Sidekiq
 
 ```diff

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

@@ -66,7 +66,7 @@ module Wurk
       # `leader_identity` is the cluster's `dear-leader` value (ProcessSet#leader,
       # memoized to one Redis GET per request) — comparing here avoids the N+1
       # `Process#leader?` GET-per-row that a per-process lookup would cost.
-      def process_row(process, leader_identity: nil)
+      def process_row(process, leader_identity: nil) # rubocop:disable Metrics/AbcSize
         {
           identity: process.identity,
           hostname: process['hostname'],
@@ -139,6 +139,56 @@ module Wurk
         }
       end
 
+      # One row of the flow listing. Header fields only: {Wurk::Flow::Status}
+      # reads its node records lazily, and a page of 25 flows that each fetched
+      # a thousand of them would be 25,000 HMGETs to render a progress bar.
+      def flow_row(status)
+        {
+          fid: status.fid,
+          state: status.state,
+          total: status.total,
+          pending: status.pending,
+          succeeded: status.succeeded_count,
+          depth: status.depth,
+          width: status.width,
+          created_at: status.created_at,
+          finished_at: status.finished_at,
+          failed_at: status.failed_at,
+          abandoned_at: status.abandoned_at
+        }
+      end
+
+      # The graph. Nodes ride inside the same document rather than behind a
+      # second request: the SPA lays the DAG out from `depends_on`, and a
+      # header fetched separately from its edges can describe a different
+      # revision of the flow than the one being drawn.
+      def flow_detail(status)
+        flow_row(status).merge(
+          dead_nodes: status.dead_indexes,
+          nodes: status.nodes.map { |node| flow_node(node) }
+        )
+      end
+
+      # `error` carries a broken pipe's reason (slice 11 decision 2) — the one
+      # node state whose cause is not discoverable from the job itself, because
+      # no job ever ran.
+      def flow_node(node)
+        {
+          index: node.index,
+          name: node.name,
+          klass: node.klass,
+          queue: node.queue,
+          jid: node.jid,
+          bid: node.bid,
+          state: node.state,
+          depends_on: node.dependencies,
+          dependents: node.dependents,
+          remaining: node.remaining,
+          piped: node.piped?,
+          error: node.error
+        }
+      end
+
       def metric_row(klass, totals)
         { klass: klass, processed: totals[:p], failed: totals[:f], runtime_ms: totals[:ms] }
       end

data/app/controllers/wurk/api_controller.rb

@@ -13,7 +13,7 @@ module Wurk
   # 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
+  class ApiController < ApplicationController # rubocop:disable Metrics/ClassLength
     include ActionController::Live
     # The SPA is a token-less JSON client; SameOriginGuard supplies Sidekiq's
     # same-origin CSRF defense (spec §25.1) so every mutating endpoint is
@@ -182,6 +182,31 @@ module Wurk
       render json: { error: 'unknown batch' }, status: :not_found
     end
 
+    def flows
+      set = ::Wurk::FlowSet.new
+      page = ::Wurk::Api::Pagination.window(params)
+      rows = ::Wurk::Api::Pagination.slice(set, page) { |status| ::Wurk::Api::Serializers.flow_row(status) }
+      render json: { total: set.size, page: page[:page], count: page[:count], flows: rows }
+    end
+
+    def flow
+      status = flow_status
+      return render(json: { error: 'unknown flow' }, status: :not_found) unless status&.exists?
+
+      render json: ::Wurk::Api::Serializers.flow_detail(status)
+    end
+
+    # The kill switch (slice 11 decision 4). Read-only mode 403s it via the
+    # Authorization middleware, like every other non-GET here. `abandoned`
+    # comes back false for a flow that had already finished or been abandoned —
+    # neither is stuck, and neither is touched.
+    def abandon_flow
+      status = flow_status
+      return render(json: { error: 'unknown flow' }, status: :not_found) unless status&.exists?
+
+      render json: { ok: true, abandoned: ::Wurk::Flow.abandon(status.fid) }
+    end
+
     def limiters
       names = ::Wurk::Web::Enterprise::Limits.list(filter: params[:substr])
       page = ::Wurk::Api::Pagination.window(params)
@@ -256,7 +281,7 @@ module Wurk
     # `: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 chart-ready.
-    def queue_history
+    def queue_history # rubocop:disable Metrics/AbcSize
       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)
@@ -304,8 +329,6 @@ module Wurk
       end
     end
 
-    private
-
     # Engine-relative path probed as a representative mutation. Must be a real
     # mutating route (POST /api/retries — bulk retry/delete/kill) so that a
     # path-sensitive hook resolves it the same way the Authorization middleware
@@ -313,6 +336,9 @@ module Wurk
     # is the GET /api/meta path) would let such a hook allow the probe while
     # still 403ing real mutations, reviving the "button shows, then 403s" gap.
     MUTATION_PROBE_PATH = '/api/retries'
+    private_constant :MUTATION_PROBE_PATH
+
+    private
 
     # Per-request read-only signal for the SPA. When a registered authorization
     # hook would reject a *mutating* request for this user (e.g. a viewer role
@@ -327,6 +353,16 @@ module Wurk
       config.authorized?(request.env, 'POST', MUTATION_PROBE_PATH)
     end
 
+    # nil for an empty fid, which Flow::Status refuses rather than reading
+    # `flow:` — the key prefix itself, which is not a flow. Both callers turn
+    # that into the same 404 a fid nothing was created under gets, because from
+    # outside there is no difference worth telling apart.
+    def flow_status
+      ::Wurk::Flow::Status.new(params[:fid].to_s)
+    rescue ::ArgumentError
+      nil
+    end
+
     # 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).
@@ -342,7 +378,7 @@ module Wurk
     end
 
     # Bulk variant: `keys[]` + a single `cmd` applied to every resolved entry.
-    def bulk_entry_action(set, actions)
+    def bulk_entry_action(set, actions) # rubocop:disable Metrics/AbcSize
       method = actions[params[:cmd].to_s]
       return render(json: { error: 'unknown action' }, status: :bad_request) unless method
 
@@ -364,7 +400,7 @@ module Wurk
     # 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)
+    def signal_processes(method) # rubocop:disable Metrics/AbcSize
       identity = params[:identity].to_s
       if identity.empty? || identity == 'all'
         count = ::Wurk::ProcessSet.new.reject(&:embedded?).each { |p| p.public_send(method) }.size

data/app/controllers/wurk/dashboard_controller.rb

@@ -3,6 +3,7 @@
 require 'json'
 require 'net/http'
 require 'uri'
+require 'wurk/web'
 
 module Wurk
   # Serves the SPA shell. Everything else is JSON from ApiController.
@@ -25,36 +26,91 @@ module Wurk
     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
+    # The SPA mount point, matched without its closing `>` so the locale hint
+    # appends to whatever attributes the shell already carries.
+    ROOT_DIV = '<div id="wurk-root"'
+    # The theme hint's anchor. It is the one payload that has to land at the
+    # *top* of <head> rather than before </head> with the others: the shell's
+    # pre-paint script reads it, and that script runs before the stylesheet so
+    # a host default never flashes the other palette.
+    HEAD_OPEN = '<head>'
 
     def index
-      render layout: false, html: inject_mount_base(spa_html).html_safe
+      render layout: false, html: decorate_shell(spa_html).html_safe
     end
 
     private
 
+    def decorate_shell(html)
+      inject_theme_default(inject_locale_hint(inject_head(html)))
+    end
+
     def spa_html
       ENV['WURK_VITE_DEV'] == '1' ? fetch_vite_dev_shell : read_built_index
     end
 
+    # Block form deliberately: a string replacement would interpret `\0`/`\&`
+    # backreferences inside the host-configured JSON these scripts carry.
+    def inject_head(html)
+      html.sub('</head>') { "#{mount_base_script}#{host_translations_script}</head>" }
+    end
+
     # The SPA is mount-agnostic: it reads window.__WURK_BASE__ to build every API
     # URL and its client-router base, so the same precompiled bundle works whether
     # the host mounts the engine at /wurk, /sidekiq, or /admin/jobs. script_name
     # is the mount prefix ("/sidekiq"), or "" at the app root. Injected into every
     # served shell (built and Vite-dev) so a non-/wurk mount needs no rebuild.
-    def inject_mount_base(html)
-      html.sub('</head>', "#{mount_base_script}</head>")
-    end
-
     def mount_base_script
       base = request.script_name.to_s.chomp('/')
-      %(<script>window.__WURK_BASE__ = #{js_string(base)};</script>\n  )
+      %(<script>window.__WURK_BASE__ = #{json_literal(base)};</script>\n  )
+    end
+
+    # Host copy overrides (Wurk::Web.config.translations), read once at SPA boot
+    # by loadHostOverrides() in frontend/src/i18n/index.ts and deep-merged over
+    # the shipped bundle for the locale in use.
+    def host_translations_script
+      overrides = ::Wurk::Web.config.translations
+      return '' unless overrides.is_a?(::Hash) && !overrides.empty?
+
+      %(<script type="application/json" id="wurk-i18n">#{json_literal(overrides)}</script>\n  )
+    end
+
+    # First-paint language hint, third in the SPA's precedence chain (`?locale=`
+    # and a stored pick both outrank it), so it only decides the render for a
+    # visitor who has never chosen. The negotiator returns a tag from the host's
+    # offered list or nothing — request text never reaches the attribute — and
+    # no hint at all is the right answer for an unrecognized language: the SPA
+    # then falls through to navigator.languages.
+    def inject_locale_hint(html)
+      locale = negotiated_locale
+      return html unless locale
+
+      html.sub(ROOT_DIV) { %(#{ROOT_DIV} data-locale="#{::ERB::Util.html_escape(locale)}") }
+    end
+
+    # First-paint theme default (Wurk::Web.config.default_theme), last in the
+    # SPA's precedence chain behind a stored pick — so it only decides the
+    # palette for a visitor who has never chosen one. No config emits nothing
+    # and leaves the SPA on 'system', which follows the visitor's OS.
+    def inject_theme_default(html)
+      theme = ::Wurk::Web.config.default_theme
+      return html unless theme
+
+      script = %(<script>window.__WURK_THEME__ = #{json_literal(theme)};</script>)
+      html.sub(HEAD_OPEN) { "#{HEAD_OPEN}\n    #{script}" }
+    end
+
+    def negotiated_locale
+      config = ::Wurk::Web.config
+      header = request.get_header('HTTP_ACCEPT_LANGUAGE')
+      ::Wurk::Web::LocaleNegotiator.call(header, offered: config.offered_locales) || config.default_locale
     end
 
-    # JSON-quote the mount prefix as a literal inside <script>, escaping the
-    # sequences that could otherwise break out of the tag. The mount is
+    # JSON-encode a value as a literal inside <script>, escaping the sequences
+    # that could otherwise break out of the tag. Both payloads are
     # host-configured, not request input, but the injection stays safe regardless.
-    def js_string(str)
-      str.to_json.gsub(/[<>&]/) { |c| format('\u%04x', c.ord) }
+    def json_literal(value)
+      value.to_json.gsub(/[<>&]/) { |c| format('\u%04x', c.ord) }
     end
 
     def fetch_vite_dev_shell

data/config/routes.rb

@@ -9,7 +9,7 @@ Wurk::Engine.routes.draw do
     get  'stats',            to: 'api#stats'
     get  'queues',           to: 'api#queues'
     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/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.
@@ -28,7 +28,7 @@ Wurk::Engine.routes.draw do
     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{[^/]+} }
+    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
@@ -45,6 +45,14 @@ Wurk::Engine.routes.draw do
     # 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
+    # Flows (Wurk::Flow) read the way the batches below them do — a paged index
+    # plus one document per id — because a flow *is* the parent relation between
+    # batches. `abandon` is the kill switch (slice 11 decision 4): a non-GET, so
+    # read-only mode 403s it via the Authorization middleware, no guard needed
+    # here.
+    get  'flows',            to: 'api#flows'
+    get  'flows/:fid',       to: 'api#flow', as: :api_flow
+    post 'flows/:fid/abandon', to: 'api#abandon_flow', as: :api_abandon_flow
     get  'batches',          to: 'api#batches'
     get  'batches/:bid',     to: 'api#batch', as: :api_batch
     get  'limiters',         to: 'api#limiters'
@@ -57,13 +65,32 @@ Wurk::Engine.routes.draw do
     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  '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
 
+  # The machine-facing HTTP API (lib/wurk/api/) — mount mode 1 of three. An app
+  # that already mounts the engine gets it at `<mount>/api/v1` for free once a
+  # token exists; `Wurk::API.serves?` decides per request, so with none the
+  # constraint fails, Rails falls through, and there is no surface to find. It
+  # shares the /api prefix with the dashboard's own JSON API above; the
+  # constraint — not the declaration order — is what keeps those matching. It
+  # claims every version-shaped path rather than `/v1` alone, so an unknown
+  # version reaches the app and comes back as the same `unsupported_api_version`
+  # problem document the other two mounts answer with.
+  #
+  # Nested here it also inherits the engine's middleware — the host's
+  # `Wurk::Web.use` chain and the read-only gate — so a dashboard behind Devise
+  # keeps gating this path too. A machine client that cannot pass a browser
+  # login wants mode 2 instead: `mount Wurk::API => '/wurk-api'` in the host's
+  # own routes, declared BEFORE the engine when its path extends the engine's —
+  # Rails matches a mounted app by bare string prefix, so `mount Wurk::Engine =>
+  # '/wurk'` declared first swallows every `/wurk-api/...` request.
+  mount Wurk::API => Wurk::API::ENGINE_MOUNT, constraints: ->(request) { Wurk::API.serves?(request.path_info) }
+
   # 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>".

data/exe/wurk

@@ -2,7 +2,8 @@
 # frozen_string_literal: true
 
 # Standalone runner. Does NOT load the Rails engine.
-# Usage: `exe/wurk -C config/wurk.yml`
+# Usage: `exe/wurk -C config/wurk.yml`     — worker: one process, thread pool
+#        `exe/wurk api --port 7433`        — machine HTTP API, runs no jobs
 
 $stdout.sync = true
 $LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
@@ -12,7 +13,10 @@ require 'wurk'
 begin
   cli = Wurk::CLI.instance
   cli.parse
-  cli.run
+  case cli.command
+  when 'api' then cli.run_api
+  else            cli.run
+  end
 rescue StandardError => e
   raise e if $DEBUG
 

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "rails/generators"
+require 'rails/generators'
 
 module Wurk
   module Generators
@@ -8,10 +8,10 @@ module Wurk
     # 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__)
+      source_root File.expand_path('templates', __dir__)
 
       def copy_initializer
-        template "wurk.rb", "config/initializers/wurk.rb"
+        template 'wurk.rb', 'config/initializers/wurk.rb'
       end
 
       def insert_mount_line

data/lib/sidekiq/job_retry.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
+require 'wurk'

data/lib/sidekiq/manager.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
+require 'wurk'

data/lib/sidekiq/processor.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
+require 'wurk'