wurk 1.5.0 → 1.7.0

data/lib/wurk/api/validation.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'problem'
+
+module Wurk
+  module API
+    # Everything the API refuses at its boundary, before a Wurk object sees it.
+    #
+    # Client validates a job hash written by Ruby running in this process. This
+    # validates one typed by a stranger, and the two are different jobs.
+    # `JobUtil::TRANSIENT_ATTRIBUTES` (job_util.rb) is a *strip*-list: it names
+    # the two keys that must never reach the wire and passes everything else
+    # through, which is the right default for a producer that already runs your
+    # code and the wrong one for a producer that doesn't. So the allow-list
+    # JobUtil has no reason to own lives here, at the only door a stranger can
+    # knock on.
+    #
+    # Nothing in this file changes what a Ruby `perform_async` may push. The
+    # boundary is the HTTP request, not the payload format — wire-compat is
+    # untouched.
+    module Validation
+      # Carries the problem it should be rendered as, so a route rescues one
+      # class and renders whatever it was handed instead of mapping message
+      # text back onto a status code.
+      class Invalid < StandardError
+        attr_reader :type, :status, :extra
+
+        def initialize(detail, type: Problem::INVALID_REQUEST, status: 400, **extra)
+          super(detail)
+          @type = type
+          @status = status
+          @extra = extra
+        end
+      end
+
+      # A Ruby constant path and nothing else. `class` reaches the consumer as
+      # a constantize plus `new.perform`, so the string is a code selector, not
+      # data: any shape that is not a constant path is either an attack or a
+      # bug, and both are better answered here than by a NameError in a worker
+      # process two hosts away.
+      #
+      # Linear, not backtracking: `:` is outside the character class, so each
+      # `::` boundary is unambiguous.
+      CLASS_FORMAT = /\A[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*\z/
+
+      # Length is checked separately from shape so a megabyte of `A`s is
+      # refused on a fact about the string rather than matched, stored in a
+      # payload and echoed back in an error.
+      MAX_CLASS_LENGTH = 255
+
+      # A jid reaches Redis as a ZSCAN glob (JobSet#find_job wraps it in `*`),
+      # so an unbounded or metacharacter-carrying jid off the network is a scan
+      # this API runs on the client's behalf. Sidekiq's own jids are
+      # `SecureRandom.hex(12)`; admit any URL-safe token of a sane length and
+      # refuse the rest at the door.
+      JID_FORMAT = /\A[A-Za-z0-9_-]{1,255}\z/
+
+      # A queue name arrives as one path segment (percent-decoded by the
+      # router, so a name containing '/' is reachable) and reaches Redis as
+      # `queue:<name>`. The Sidekiq schema bounds it nowhere, so this door
+      # does: whitespace and control characters are out because a name
+      # carrying them is one no operator can type back into the dashboard or a
+      # CLI flag, and the length cap exists for the same reason a jid's does —
+      # it is echoed back on every listing.
+      QUEUE_NAME_FORMAT = /\A[^[:space:][:cntrl:]]{1,255}\z/
+
+      # A process identity is `<hostname>:<pid>:<nonce>` and is itself a Redis
+      # key — the heartbeat HASH, `<identity>:work` and `<identity>-signals`
+      # are all built by interpolating it. The same shape as a queue name for
+      # the same reason, spelled separately because the two doors are
+      # independent: bounding what may be addressed as a queue says nothing
+      # about what may be addressed as a process.
+      IDENTITY_FORMAT = /\A[^[:space:][:cntrl:]]{1,255}\z/
+
+      # Same word the router uses for "any scope": here it turns the class
+      # allow-list off.
+      ANY = :any
+
+      # The top-level keys a job hash may carry in over HTTP.
+      #
+      # Anything absent is refused rather than dropped: a silently ignored
+      # `deadlin:` typo is a job that runs unbounded and a producer that never
+      # finds out. The server-written fields are absent on purpose —
+      # `created_at`/`enqueued_at` would let a client backdate its own queue
+      # latency, `retry_count`/`failed_at` would let it lie to the retrier,
+      # `expiry`/`deadline_at` are stamps derived from `expires_in`/`deadline`,
+      # `bid` would attach a job to a batch whose `pending` counter was never
+      # incremented for it, and `pool`/`client_class` name Ruby objects a JSON
+      # body cannot hold at all.
+      #
+      # Mutable for the same reason `TRANSIENT_ATTRIBUTES` is: a gem that adds
+      # a job option (sidekiq-unique-jobs' `lock:`) has to be able to append
+      # one without reopening this file. Baked into the literal rather than
+      # appended at load, so the parallel test runner never observes a
+      # half-built list.
+      # rubocop:disable Style/MutableConstant
+      JOB_KEYS = %w[
+        class args queue at retry jid backtrace tags dead
+        retry_for retry_queue expires_in track timeout deadline
+        encrypt unique_for unique_until collapse log_level locale wrapped
+      ]
+      # rubocop:enable Style/MutableConstant
+
+      # `push_bulk`'s envelope keys, on top of the job keys it shares.
+      BULK_KEYS = %w[batch_size spread_interval].freeze
+
+      # Echoing a rejected key back is the only way a client finds its typo,
+      # but the keys came off the network — bound how many and how long, for
+      # the same reason the JSON parser's own message is never forwarded.
+      MAX_REPORTED_KEYS = 10
+      MAX_REPORTED_KEY_LENGTH = 40
+
+      module_function
+
+      # Reads at most `limit + 1` bytes, so an oversized body is refused on the
+      # strength of what a cap-sized read already proved rather than by
+      # buffering the whole thing to measure it.
+      def body!(request, limit)
+        raw = request.read_body(limit + 1)
+        return raw unless raw.bytesize > limit
+
+        raise Invalid.new(
+          "The request body may not exceed #{limit} bytes.",
+          type: Problem::PAYLOAD_TOO_LARGE, status: 413, max_bytes: limit
+        )
+      end
+
+      # The body is the job hash with no envelope around it, so this only
+      # insists it is a JSON object at all — everything downstream indexes it
+      # by key.
+      def object!(raw)
+        parsed = ::JSON.parse(raw)
+        raise Invalid, 'The request body must be a JSON object.' unless parsed.is_a?(::Hash)
+
+        parsed
+      rescue ::JSON::ParserError
+        # Deliberately not the parser's own message: it quotes the unparsed
+        # remainder of the document, so a large malformed body would come back
+        # as a large error.
+        raise Invalid, 'The request body is not valid JSON.'
+      end
+
+      # One job hash, for `POST /jobs`.
+      def job!(payload, principal:, config:)
+        known_keys!(payload, JOB_KEYS)
+        jid!(payload['jid']) if payload.key?('jid')
+        allowed!(class!(payload), principal, config) if payload.key?('class')
+        args_size!(payload['args'], config.api_max_args_bytes)
+        payload
+      end
+
+      # The `push_bulk` envelope, for `POST /jobs/bulk`: the same job keys plus
+      # the two that describe the batch, and an `args` that is one array per
+      # job rather than one array of arguments.
+      def bulk!(payload, principal:, config:)
+        known_keys!(payload, JOB_KEYS + BULK_KEYS)
+        jid!(payload['jid']) if payload.key?('jid')
+        allowed!(class!(payload), principal, config) if payload.key?('class')
+        bulk_args_size!(payload['args'], config.api_max_args_bytes)
+        payload
+      end
+
+      # @raise [Invalid] unless `jid` is a URL-safe token of a sane length.
+      # @return [String] the jid.
+      def jid!(jid) = url_safe!(jid, 'jid')
+
+      # A bid indexes `b-<bid>` and its satellite keys, and Batch::Status
+      # builds every one of them by interpolation — the same key-fragment
+      # exposure a jid has, so the same door.
+      # @return [String] the bid.
+      def bid!(bid) = url_safe!(bid, 'batch id')
+
+      # A fid interpolates into `flow:<fid>` and, one segment further, into
+      # every node record under it — the same key-fragment exposure a bid has,
+      # so the same door.
+      # @return [String] the fid.
+      def fid!(fid) = url_safe!(fid, 'flow id')
+
+      def url_safe!(value, label)
+        return value if value.is_a?(::String) && JID_FORMAT.match?(value)
+
+        raise Invalid, "A #{label} is a URL-safe token of up to 255 characters."
+      end
+
+      # @raise [Invalid] unless `name` fits {QUEUE_NAME_FORMAT}.
+      # @return [String] the queue name.
+      def queue_name!(name)
+        return name if name.is_a?(::String) && QUEUE_NAME_FORMAT.match?(name)
+
+        raise Invalid, 'A queue name is up to 255 characters with no whitespace or control characters.'
+      end
+
+      # @raise [Invalid] unless `identity` fits {IDENTITY_FORMAT}.
+      # @return [String] the process identity.
+      def identity!(identity)
+        return identity if identity.is_a?(::String) && IDENTITY_FORMAT.match?(identity)
+
+        raise Invalid, 'A process identity is up to 255 characters with no whitespace or control characters.'
+      end
+
+      # Validates the allow-list where it is declared, so a typo'd class name
+      # raises in the initializer that wrote it instead of 403ing a producer in
+      # production. Accepts Classes as well as names — a host listing the
+      # constant it already has in scope is spelling the same thing.
+      #
+      # @return [Array<String>, :any, nil] normalized allow-list.
+      def enqueueable_classes!(classes)
+        return nil if classes.nil?
+        return ANY if classes == ANY
+
+        list = Array(classes).map(&:to_s)
+        raise ArgumentError, 'api_enqueue_classes must name at least one class, :any, or nil' if list.empty?
+
+        unknown = list.reject { |name| class_name?(name) }
+        raise ArgumentError, "api_enqueue_classes entries must be Ruby class names: #{unknown.inspect}" if unknown.any?
+
+        list.freeze
+      end
+
+      def class_name?(value)
+        value.is_a?(::String) && value.length <= MAX_CLASS_LENGTH && CLASS_FORMAT.match?(value)
+      end
+
+      def known_keys!(payload, allowed)
+        unknown = payload.keys - allowed
+        return if unknown.empty?
+
+        reported = reportable(unknown)
+        raise Invalid.new("Unknown job keys: #{reported.join(', ')}.", unknown_keys: reported)
+      end
+
+      def reportable(keys)
+        keys.sort.first(MAX_REPORTED_KEYS).map { |key| key.to_s[0, MAX_REPORTED_KEY_LENGTH] }
+      end
+
+      def class!(payload)
+        job_class = payload['class']
+        return job_class if class_name?(job_class)
+
+        raise Invalid, %(Job 'class' must be a Ruby class name, e.g. "HardWorker" or "Billing::Charge".)
+      end
+
+      # The allow-list JobUtil has no reason to own:
+      #
+      #   nil   → only an `admin` token may enqueue, and it may enqueue anything
+      #   Array → exactly these names, for every token, `admin` included
+      #   :any  → the check is off
+      #
+      # Unset denies an enqueue-scoped producer everything, because `class`
+      # selects which of the host's jobs runs and a producer that can name any
+      # constant is choosing. `admin` is exempt only while no list exists: it
+      # already holds the destructive routes, so restricting which class it may
+      # enqueue would be theatre. Once a host writes a list, it means it.
+      def allowed!(job_class, principal, config)
+        return if enqueueable?(job_class, principal, config.api_enqueue_classes)
+
+        raise Invalid.new(
+          "#{job_class} may not be enqueued over HTTP; config.api_enqueue_classes names the classes that may.",
+          type: Problem::CLASS_NOT_ALLOWED, status: 403, job_class: job_class
+        )
+      end
+
+      def enqueueable?(job_class, principal, classes)
+        case classes
+        when nil then principal.permits?(:admin)
+        when ANY then true
+        else classes.include?(job_class)
+        end
+      end
+
+      # Only an Array is sizeable and only an Array is legal; Client names the
+      # other shapes, with the offending value in the message.
+      def args_size!(args, limit)
+        return unless args.is_a?(::Array)
+
+        size = ::JSON.generate(args).bytesize
+        return if size <= limit
+
+        raise Invalid.new(
+          "Job args may not exceed #{limit} bytes; these serialize to #{size}.",
+          type: Problem::PAYLOAD_TOO_LARGE, status: 413, max_bytes: limit
+        )
+      end
+
+      # The body cap bounds the request; this bounds each job the request turns
+      # into, which for a bulk push is the only one of the two that bounds what
+      # lands in Redis.
+      def bulk_args_size!(args, limit)
+        return unless args.is_a?(::Array)
+
+        args.each_with_index do |job_args, index|
+          next unless job_args.is_a?(::Array)
+
+          size = ::JSON.generate(job_args).bytesize
+          next if size <= limit
+
+          raise Invalid.new(
+            "Job #{index}'s args may not exceed #{limit} bytes; they serialize to #{size}.",
+            type: Problem::PAYLOAD_TOO_LARGE, status: 413, max_bytes: limit, job_index: index
+          )
+        end
+      end
+    end
+  end
+end

data/lib/wurk/api.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Wurk
+  # Namespace for two unrelated things that both answer to "the API": the Pro
+  # data-API Lua extensions (API::Fast, required by lib/wurk.rb at its
+  # load-order-sensitive point) and the machine-facing HTTP API (API::App).
+  module API
+    # The one prefix the machine plane answers under, and the version it pins.
+    # They live on the namespace rather than on App because the engine's mount
+    # constraint has to answer "is this path mine?" on every routing pass, and
+    # loading App to ask would undo the lazy load below.
+    API_VERSION = 'v1'
+    VERSION_PREFIX = "/#{API_VERSION}".freeze
+    NESTED_PREFIX = "#{VERSION_PREFIX}/".freeze
+    SUPPORTED_VERSIONS = [API_VERSION].freeze
+
+    # A path that names *some* version of this plane — `/v1`, `/v2/jobs`, not
+    # `/v1x` and not the dashboard's own `/stats`. Version-shaped rather than
+    # `v1`-only because the mount has to claim a version it does not serve in
+    # order for App to answer it `unsupported_api_version`, which is what the
+    # standalone and separately-mounted modes already do. Claiming only `/v1`
+    # would leave mode 1 alone in falling through to the host's router, and a
+    # client would learn "wrong version" from Rails' 404 in one deployment
+    # shape and from a problem document naming the supported versions in the
+    # other two.
+    VERSION_PATH = %r{\A/v\d+(?:/|\z)}
+
+    # Where mount mode 1 puts this plane inside the engine (config/routes.rb).
+    # Named here because two callers have to agree on it: the mount itself, and
+    # `Wurk::Web::Authorization`, which runs before routing and so sees the
+    # engine-relative path with this prefix still on it.
+    ENGINE_MOUNT = '/api'
+
+    # Rack env key the engine's Authorization middleware stamps when the
+    # dashboard is read-only. It is how mount mode 1 — and only mode 1 —
+    # inherits `WURK_WEB_READ_ONLY`: a separately mounted or standalone API is
+    # a different deployment and opts in on its own (`config.api_read_only`).
+    READ_ONLY_ENV = 'wurk.web.read_only'
+
+    class << self
+      # Class-level Rack entry, the same shape as Wurk::Web.call, so
+      # `mount Wurk::API => '/wurk-api'` and `run Wurk::API` both work.
+      #
+      # App and its dependencies (Rack::Request among them) load on the first
+      # request rather than at `require "wurk"`. The HTTP API is off unless a
+      # host mounts it, and eager-loading it cost every swarm child ~1.2 MB of
+      # pre-fork heap and measurably slower boot for a surface it never serves.
+      def call(env)
+        app.call(env)
+      end
+
+      # Whether the API should answer for `path` — the request path relative to
+      # wherever it was mounted. The engine's conditional mount (config/
+      # routes.rb) is a constraint over this, which settles two things a bare
+      # `mount` could not:
+      #
+      #   * Off means absent. With no token registered the constraint fails,
+      #     Rails falls through to the next route, and the surface does not
+      #     exist — not a 401 advertising one that does (07 plan, step 1).
+      #     Asked per request, not at draw time: routes load once at boot, and
+      #     a host is free to register its token after that (a Puma-cluster web
+      #     process never enters server mode, so its `configure_server` block
+      #     has not run by then).
+      #   * Nested in the engine, this plane shares the /api prefix with the
+      #     dashboard's own JSON API. Without the version check a mistyped
+      #     dashboard path would fall through to the machine plane and draw a
+      #     bearer challenge for a route that was never part of this contract.
+      #     A version-shaped path is never one of the dashboard's, so this
+      #     claims every version and lets App refuse the ones it cannot serve.
+      def serves?(path, config = ::Wurk.configuration)
+        return false unless config.api_enabled?
+
+        VERSION_PATH.match?(path)
+      end
+
+      # The same question asked one prefix out, for callers that run before the
+      # engine's mount has stripped it — `Wurk::Web::Authorization` is the only
+      # one. It has to tell a machine-plane path from a dashboard one (both live
+      # under /api) without loading App, which is why this is here and not there.
+      def engine_serves?(path, config = ::Wurk.configuration)
+        path.start_with?(ENGINE_MOUNT) && serves?(path.delete_prefix(ENGINE_MOUNT), config)
+      end
+
+      private
+
+      # App is stateless, so every mount — engine-nested, separately mounted,
+      # standalone — can share one instance.
+      def app
+        @app ||= begin
+          require_relative 'api/app'
+          App.new
+        end
+      end
+    end
+  end
+end

data/lib/wurk/batch/server_middleware.rb

@@ -30,7 +30,7 @@ module Wurk
     class ServerMiddleware
       include Wurk::Middleware::ServerMiddleware
 
-      def call(_worker, job, _queue)
+      def call(_worker, job, _queue, &)
         bid = job['bid']
         return yield unless bid
 
@@ -39,7 +39,7 @@ module Wurk
           return
         end
 
-        run_and_ack(bid, job['jid']) { yield }
+        run_and_ack(bid, job['jid'], &)
       end
 
       private

data/lib/wurk/batch.rb

@@ -36,7 +36,7 @@ module Wurk
   # Nested batches: a job opening its OWN batch (`batch.jobs { ... }`)
   # increments live counters on the existing batch. A callback opening its
   # PARENT batch links via parent_bid and adds child BID to b-<bid>-kids.
-  class Batch
+  class Batch # rubocop:disable Metrics/ClassLength
     DEFAULT_EXPIRY_SECONDS = 30 * 24 * 60 * 60
     POST_SUCCESS_EXPIRY_SECONDS = 24 * 60 * 60
     CALLBACK_NOTIFY_TTL = 30 * 24 * 60 * 60
@@ -117,9 +117,18 @@ module Wurk
     # can drive the trim on isolated limits without mutating the process-global
     # `Wurk.configuration`.
     def self.trim_index(pipe, key, max: nil, timeout: nil)
+      score, rank = trim_bounds(max: max, timeout: timeout)
+      pipe.call('ZREMRANGEBYSCORE', key, '-inf', score)
+      pipe.call('ZREMRANGEBYRANK', key, 0, rank)
+    end
+
+    # The same two bounds as arguments, for a writer that cannot append to a
+    # pipeline: `Wurk::Flow`'s creation script has to trim from inside its own
+    # atomic write, and one policy read out of here beats a second copy of the
+    # cutoff arithmetic that drifts the day this one changes.
+    def self.trim_bounds(max: nil, timeout: nil)
       cutoff = ::Process.clock_gettime(::Process::CLOCK_REALTIME) - (timeout || DEFAULT_EXPIRY_SECONDS)
-      pipe.call('ZREMRANGEBYSCORE', key, '-inf', "(#{cutoff}")
-      pipe.call('ZREMRANGEBYRANK', key, 0, -(max || INDEX_MAX))
+      ["(#{cutoff}", -(max || INDEX_MAX)]
     end
 
     def initialize(bid = nil)

data/lib/wurk/capsule.rb

@@ -4,6 +4,7 @@ require_relative 'redis_pool'
 require_relative 'pool_checkout'
 require_relative 'middleware/chain'
 require_relative 'fetcher/reliable'
+require_relative 'watchdog'
 
 module Wurk
   # One processing unit: a set of threads + queues sharing a fetcher and a
@@ -14,7 +15,7 @@ module Wurk
   class Capsule
     MODES = %i[strict weighted random].freeze
 
-    attr_reader :name, :queues, :mode, :weights, :config
+    attr_reader :name, :queues, :mode, :weights, :config, :watchdog
     attr_accessor :concurrency, :fetcher
 
     # Capsule-hosted components (Manager, Processor, Fetcher) hand their capsule
@@ -41,6 +42,7 @@ module Wurk
       @pools = {}
       @client_chain = nil
       @server_chain = nil
+      @watchdog = nil
     end
 
     def to_h
@@ -78,6 +80,11 @@ module Wurk
     def prepare!
       prepare_shared!
       @fetcher ||= build_fetcher
+      # Here rather than in the constructor so a client-only process — a web
+      # dyno building the same Configuration — allocates nothing, and so the
+      # scanner thread a bounded job spawns belongs to the child that runs it.
+      # The object itself holds no thread until something is bounded.
+      @watchdog ||= Watchdog.new(self)
       redis_pool
       fetch_redis_pool
       self

data/lib/wurk/cli.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-require 'yaml'
-require 'optparse'
-require 'erb'
-
+# yaml, optparse and erb are required inside the two methods that use them
+# (#parse_config and #option_parser) rather than here. Together they cost ~45ms
+# of the ~290ms `require "wurk"` spends, and only `exe/wurk` ever reaches them —
+# a Rails app that enqueues and processes jobs pays that on every boot for a
+# command-line parser it never runs. `require` is idempotent, so the lazy call
+# is a $LOADED_FEATURES hash lookup on every invocation after the first.
 require_relative 'version'
 require_relative 'configuration'
 require_relative 'component'
@@ -24,6 +26,27 @@ module Wurk
     # format and Lua scripts rely on commands introduced in Redis 7.
     MIN_REDIS_VERSION = '7.0.0'
 
+    # Subcommands. Bare `wurk` runs the worker — the historical shape, and the
+    # only one the swarm binaries accept — so a subcommand is never anything
+    # but the first argument, and every argument after it is that command's.
+    COMMANDS = %w[api].freeze
+
+    # `wurk api` defaults. 0.0.0.0 because the point of the machine API is for
+    # another service to reach it; it is bearer-gated, and answers 404 to
+    # everything until a token exists. `--bind 127.0.0.1` narrows it.
+    DEFAULT_API_BIND = '0.0.0.0'
+    DEFAULT_API_PORT = 7433
+
+    # Serving the API with nothing registered would bind a port and 404 every
+    # request — the surface is off until a token exists, so say so at boot
+    # rather than leaving an operator to diagnose it over HTTP.
+    NO_API_TOKEN_MESSAGE = <<~MSG
+      No API token is registered, so every request would answer 404.
+      Register one where the app loaded by -r configures wurk:
+
+          Wurk.configuration.api_token(ENV.fetch('WURK_API_TOKEN'), scopes: %i[enqueue read])
+    MSG
+
     # Thread-backtrace dumper used by both TTIN and INFO. Same body — INFO is
     # the modern name, TTIN is kept for parity with older Sidekiq users.
     BACKTRACE_DUMPER = lambda do |cli|
@@ -68,8 +91,20 @@ module Wurk
       ['-C', '--config PATH',          :config_file, 'path to YAML config file']
     ].freeze
 
+    # Same table shape, offered only when `api` is the subcommand: none of it
+    # means anything to a worker process, and `wurk --help` stays the worker's.
+    API_OPTION_FLAGS = [
+      ['-b', '--bind ADDRESS', :api_bind,   "Address to bind (default #{DEFAULT_API_BIND})"],
+      ['-p', '--port PORT',    :api_port,   "Port to listen on (default #{DEFAULT_API_PORT})", :to_i],
+      ['-s', '--server NAME',  :api_server, 'Rack handler to serve with (default: the first installed)']
+    ].freeze
+
     attr_accessor :launcher, :environment, :config
 
+    # The subcommand `parse` pulled off argv, or nil for the worker runner.
+    # The binary picks the mode from it — `exe/wurk` runs the API for `api`.
+    attr_reader :command
+
     def self.instance
       @instance ||= new
     end
@@ -84,12 +119,14 @@ module Wurk
       @launcher = nil
       @environment = nil
       @parser = nil
+      @command = nil
     end
 
     # `parse` is split from `run` so tests can drive option parsing without
     # touching Redis or booting the host app.
     def parse(args = ARGV.dup)
       @config ||= Wurk.default_configuration
+      @command = extract_command!(args)
       setup_options(args)
       initialize_logger
       validate!
@@ -137,6 +174,8 @@ module Wurk
     # `SIDEKIQ_PRELOAD_APP` whole-app eager-load) and boots `Process.warmup`
     # before the fork so children share warmed pages (copy-on-write). Spec §7.
     def run_swarm(boot_app: true, warmup: true)
+      raise ArgumentError, "the swarm runner takes no subcommand; run `wurk #{@command}` instead" if @command
+
       # Server mode before the app loads — see #run. The flag rides through the
       # fork into every child (the config object is copied), so configure_server
       # blocks registered in the parent take effect in the workers.
@@ -163,6 +202,32 @@ module Wurk
       end
     end
 
+    # `wurk api` — serve the machine-facing HTTP API and nothing else: no
+    # fetcher, no heartbeat, no job ever runs here. This is mount mode 3, the
+    # standalone one: the same Rack app the engine nests and a host can mount
+    # itself, served without Rails.
+    #
+    # Server mode is entered for the reason #run does it — a host that
+    # registers its token inside a `configure_server` block would otherwise
+    # boot an API with no credential and 404 every request. Nothing starts as a
+    # side effect: no lifecycle event fires and no Launcher is ever built.
+    #
+    # `handler:` is a test seam; production resolves one from the installed
+    # gems.
+    def run_api(boot_app: true, handler: nil)
+      enter_server_mode
+      boot_application if boot_app
+      validate_redis!
+      # Load the app here, not on the first request: a broken load should fail
+      # the boot an operator is watching, not the first client to call.
+      require_relative 'api/app'
+      raise ArgumentError, NO_API_TOKEN_MESSAGE unless @config.api_enabled?
+
+      handler ||= api_handler(@config[:api_server])
+      logger.info { "Wurk API listening on http://#{api_bind}:#{api_port}#{Wurk::API::VERSION_PREFIX}" }
+      handler.run(Wurk::API, Host: api_bind, Port: api_port)
+    end
+
     def handle_signal(sig)
       logger.debug { "Got #{sig} signal" }
       handler = SIGNAL_HANDLERS[sig]
@@ -188,6 +253,29 @@ module Wurk
       ::Process.warmup
     end
 
+    def api_bind = @config[:api_bind] || DEFAULT_API_BIND
+    def api_port = @config[:api_port] || DEFAULT_API_PORT
+
+    # Rack 3 moved the server handlers out to the `rackup` gem; rack 2 still
+    # ships them itself. Neither is a wurk dependency — the web server is the
+    # host's choice here exactly as it is for the app this sits next to — so
+    # resolve one at run time and name the fix when there is none.
+    def api_handler(name)
+      registry = handler_registry
+      name ? registry.get(name) : registry.default
+    rescue ::LoadError, ::NameError, ::ArgumentError => e
+      raise ArgumentError, "wurk api could not start a web server (#{e.message}). Add one to your Gemfile " \
+                           '— puma, falcon, or rackup + webrick — or name an installed one with --server.'
+    end
+
+    def handler_registry
+      require 'rackup/handler'
+      ::Rackup::Handler
+    rescue ::LoadError
+      require 'rack/handler'
+      ::Rack::Handler
+    end
+
     def launch(self_read)
       @launcher = Wurk::Launcher.new(@config)
       begin
@@ -270,6 +358,14 @@ module Wurk
 
     # --- options + config-file --------------------------------------------
 
+    # Pulled off before OptionParser sees argv, so the banner and the flag
+    # table can depend on which command was named. A bare word OptionParser
+    # doesn't recognize would otherwise survive `parse!` and be silently
+    # ignored, which is how `wurk api` would look like it worked.
+    def extract_command!(args)
+      COMMANDS.include?(args.first) ? args.shift : nil
+    end
+
     def setup_options(args)
       opts = parse_options(args)
       set_environment(opts[:environment])
@@ -316,6 +412,9 @@ module Wurk
     def parse_config(path)
       raise ArgumentError, "No such file #{path}" unless ::File.exist?(path)
 
+      require 'erb'
+      require 'yaml'
+
       erb = ::ERB.new(::File.read(path), trim_mode: '-')
       erb.filename = ::File.expand_path(path)
       opts = ::YAML.safe_load(erb.result, permitted_classes: [Symbol], aliases: true) || {}
@@ -350,15 +449,18 @@ module Wurk
     end
 
     def option_parser(opts)
+      require 'optparse'
+
       ::OptionParser.new do |o|
-        o.banner = 'wurk [options]'
-        define_value_flags(o, opts)
+        o.banner = @command ? "wurk #{@command} [options]" : 'wurk [options]'
+        define_value_flags(o, opts, OPTION_FLAGS)
+        define_value_flags(o, opts, API_OPTION_FLAGS) if @command == 'api'
         define_meta_flags(o, opts)
       end
     end
 
-    def define_value_flags(parser, opts)
-      OPTION_FLAGS.each do |short, long, key, desc, transform|
+    def define_value_flags(parser, opts, flags)
+      flags.each do |short, long, key, desc, transform|
         parser.on(short, long, desc) { |arg| assign_flag(opts, key, arg, transform) }
       end
     end