wurk 1.4.0 → 1.6.0

data/lib/wurk/api/jobs.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative 'idempotency'
+require_relative 'problem'
+require_relative 'response'
+require_relative 'validation'
+
+module Wurk
+  module API
+    # The produce plane: enqueue one job, enqueue many, ask what became of one,
+    # take a not-yet-run job back out.
+    #
+    # The request body *is* the Sidekiq job hash — `{"class", "args", "queue",
+    # "at", "retry"}` — and every write below hands it to {Wurk::Client}, the
+    # same object `perform_async` reaches. Nothing here builds, renames, or
+    # re-keys a payload. That is the drop-in guarantee written as code: an
+    # HTTP-enqueued job is the same bytes in the same Redis structures as a
+    # Ruby-enqueued one, so stock Sidekiq runs it. A payload assembled here
+    # would pass its own tests forever and be wrong the first time Client
+    # changed.
+    #
+    # Client is instantiated per request rather than memoized, and without a
+    # config, for the same reason: it must resolve the process's own middleware
+    # chain and pool at call time — exactly what a Ruby producer in this process
+    # gets — and the canonical inspectors this plane shares Redis with
+    # (ScheduledSet, RetrySet) read `Wurk.redis` unconditionally.
+    #
+    # What a stranger may send is {Validation}'s job, and whether a retry of it
+    # counts twice is {Idempotency}'s. This module owns only the three routes
+    # and the order those two run in.
+    module Jobs
+      module_function
+
+      def draw(router)
+        router.post('/jobs', scope: :enqueue) { |request| create(request) }
+        router.post('/jobs/bulk', scope: :enqueue) { |request| create_bulk(request) }
+        # :read. A producer that wants to poll what it pushed is granted
+        # `%i[enqueue read]` — the same pair the configuration docs show —
+        # rather than having every enqueue token able to read a jid it did not
+        # produce, which is what folding this into :enqueue would mean.
+        router.get('/jobs/:jid', scope: :read) { |request| show(request) }
+        # :admin, not :enqueue. A jid is not bound to the token that produced
+        # it, so an enqueue-scoped producer holding this route could walk the
+        # retry set one jid at a time. Widening a scope later is additive to
+        # every client; narrowing one breaks them.
+        router.delete('/jobs/:jid', scope: :admin) { |request| destroy(request) }
+      end
+
+      # 201 with the jid, or 200 with a null one when client middleware halted
+      # the push — a `collapse:`/`unique_for:` drop is the producer's own policy
+      # doing its job, not a failure to report as one.
+      def create(request)
+        produce(request) do |payload, config|
+          Validation.job!(payload, principal: request.principal, config: config)
+          jid = ::Wurk::Client.new.push(payload)
+          Response.json(jid ? 201 : 200, jid: jid)
+        end
+      end
+
+      # The `push_bulk` shape verbatim: one `class`, an array of arg arrays, and
+      # optionally `at`/`spread_interval`/`batch_size`. Nil entries in `jids`
+      # mark the jobs middleware halted, positionally.
+      def create_bulk(request)
+        produce(request) do |payload, config|
+          Validation.bulk!(payload, principal: request.principal, config: config)
+          jids = ::Wurk::Client.new.push_bulk(payload)
+          Response.json(jids.any? { |jid| !jid.nil? } ? 201 : 200, jids: jids)
+        end
+      end
+
+      # The shape both produce routes share.
+      #
+      # The body cap runs first, because it is the only check that can be made
+      # without holding the request. The `Idempotency-Key` claim wraps
+      # everything after it — parsing, validation and the push alike. That
+      # looks like it burns a client's key on a malformed body and does not:
+      # the claim releases on any answer that isn't a success, so the
+      # correction can be sent under the same key. What it buys is that the key
+      # is claimed *before* the push, the only ordering in which two concurrent
+      # retries of a dropped connection can't both enqueue.
+      def produce(request)
+        config = request.config
+        raw = Validation.body!(request, config.api_max_body_bytes)
+        Idempotency.around(request, raw, config) { rejectable(request) { yield(Validation.object!(raw), config) } }
+      rescue Validation::Invalid => e
+        # Only the two checks above the claim reach here — the body cap, and
+        # the shape of the Idempotency-Key itself. Everything below is answered
+        # inside the claim, where the status it decides on is visible.
+        problem(request, e)
+      end
+
+      # Renders a refusal *inside* the claim, so what the claim weighs is a
+      # response with a status on it rather than an exception it could only
+      # release on. Client owns what a valid job hash is past the boundary; the
+      # route surfaces its verdict instead of duplicating it.
+      def rejectable(request)
+        yield
+      rescue Validation::Invalid => e
+        problem(request, e)
+      rescue ::ArgumentError => e
+        invalid_request(request, e.message)
+      end
+
+      # The record {Wurk::Status} keeps for one jid: state, progress, result,
+      # error. Sidekiq keeps nothing at all about a job once it succeeds, so
+      # this route can only answer for a class that opted in with
+      # `track: true`; an untracked jid, an unknown one and a row whose TTL has
+      # lapsed are all the same answer, because Redis holds nothing that tells
+      # them apart.
+      def show(request)
+        jid = Validation.jid!(request.path_params[:jid].to_s)
+        record = ::Wurk::Status.get(jid)
+        return status_not_found(request, jid) unless record
+
+        Response.json(200, record.to_h)
+      rescue Validation::Invalid => e
+        problem(request, e)
+      end
+
+      # Removes a job that has not run yet from `schedule` or `retry`. Not a
+      # cancel: a job already handed to a processor keeps running, and one that
+      # has already died stays in `dead`, where deleting it is an operator
+      # action against a different set.
+      def destroy(request)
+        jid = Validation.jid!(request.path_params[:jid].to_s)
+        set = cancellable_sets.find { |candidate| remove(candidate, jid) }
+        return job_not_found(request, jid) unless set
+
+        Response.json(200, jid: jid, set: set.name)
+      rescue Validation::Invalid => e
+        problem(request, e)
+      end
+
+      # `schedule` first: a job merely waiting for its time is the one a
+      # producer usually means to call off, and a jid in both sets at once
+      # would mean something else is already broken.
+      def cancellable_sets = [::Wurk::ScheduledSet.new, ::Wurk::RetrySet.new]
+
+      # Find-then-delete through the canonical inspectors rather than a second
+      # deletion path over the same ZSETs — the dashboard and every third-party
+      # tool use these objects, and two ways to remove a member is a place for
+      # them to disagree. A job promoted out of the set between the two steps
+      # removes nothing and reads as "already gone", the honest answer to a
+      # cancel that lost the race.
+      def remove(set, jid)
+        entry = set.find_job(jid)
+        entry ? entry.delete : false
+      end
+
+      # Validation decided which problem this is; rendering it is all that is
+      # left, so a new rejection never needs a new arm here.
+      def problem(request, error) = Problem.from(error, instance: request.path)
+
+      def invalid_request(request, detail)
+        Problem.render(Problem::INVALID_REQUEST, status: 400, detail: detail, instance: request.path)
+      end
+
+      def job_not_found(request, jid)
+        Problem.render(
+          Problem::JOB_NOT_FOUND,
+          status: 404,
+          detail: "No scheduled or retrying job has jid #{jid}.",
+          instance: request.path,
+          jid: jid
+        )
+      end
+
+      def status_not_found(request, jid)
+        Problem.render(
+          Problem::JOB_NOT_FOUND,
+          status: 404,
+          detail: "No status is recorded for jid #{jid}; the job is unknown, its class does not set " \
+                  'track: true, or its record has expired.',
+          instance: request.path,
+          jid: jid
+        )
+      end
+    end
+  end
+end

data/lib/wurk/api/page.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'rack'
+require_relative 'validation'
+
+module Wurk
+  module API
+    # Offset paging for the observe plane's listings.
+    #
+    # Deliberately not the dashboard's Wurk::Api::Pagination. That module is
+    # autoloaded out of app/ by the engine, and the API has to page in
+    # standalone mode where Rails is never loaded (CLAUDE.md); requiring an
+    # autoloadable file by hand is exactly what Zeitwerk forbids. The contracts
+    # differ too — the dashboard's may change whenever the SPA does, everything
+    # under /v1 may not — so one shared module would tie a frozen contract to a
+    # mutable one.
+    module Page
+      DEFAULT_COUNT = 25
+      MAX_COUNT = 200
+
+      # Offset paging reaches page N by walking N*count members through Ruby,
+      # and their Redis round trips with them, so an unclamped `page` lets one
+      # request drag an entire million-row set through this process. A
+      # thousand pages is past any real client's depth and still bounds the
+      # worst case.
+      MAX_PAGE = 1_000
+
+      Window = Data.define(:page, :count) do
+        def offset = page * count
+      end
+
+      module_function
+
+      # @raise [Validation::Invalid] when a paging parameter is present but is
+      #   not an integer. Out of range is clamped instead of refused — a client
+      #   asking for more rows than the API will give is not a client bug — and
+      #   every listing echoes the effective values back, so the clamp is
+      #   visible rather than silent.
+      def window!(request) = window(query!(request))
+
+      # The parsed-query half, for a route that reads a parameter of its own
+      # (`?filter=`) beside the paging ones: it parses once and hands the same
+      # Hash to both, rather than re-parsing the query string per parameter.
+      def window(query)
+        Window.new(
+          page: integer!(query['page'], 'page', 0).clamp(0, MAX_PAGE),
+          count: integer!(query['count'], 'count', DEFAULT_COUNT).clamp(1, MAX_COUNT)
+        )
+      end
+
+      # Rack::Request#params merges the POST body in, which the paged routes
+      # must never read. parse_query is also flat: `?page[]=1` arrives as the
+      # key it literally is instead of nesting into a Hash that reaches
+      # Integer().
+      #
+      # Rack's own refusals (InvalidParameterError on bad %-encoding,
+      # QueryLimitError on an oversized one) are ArgumentError and RangeError
+      # respectively; caught here so a malformed query string is the 400 it is
+      # rather than the 500 App's catch-all would make of it.
+      def query!(request)
+        ::Rack::Utils.parse_query(request.query_string)
+      rescue ::ArgumentError, ::TypeError, ::RangeError
+        raise Validation::Invalid, 'The query string could not be parsed.'
+      end
+
+      # A repeated parameter (`?page=1&page=2`) parses to an Array, which is
+      # the TypeError arm — an ambiguous request, answered rather than guessed.
+      def integer!(raw, name, default)
+        return default if raw.nil? || raw == ''
+
+        Integer(raw, 10)
+      rescue ::ArgumentError, ::TypeError
+        raise Validation::Invalid, "The '#{name}' parameter must be an integer."
+      end
+
+      # Walks `enumerable`, skips `window.offset` members, and hands at most
+      # `window.count` of them to the block, which returns the row to emit.
+      #
+      # Skipped members are never yielded, so nothing before the offset is
+      # serialized: on a queue page that is a JobRecord whose JSON is never
+      # parsed, which is most of the cost of a deep page.
+      def slice(enumerable, window)
+        rows = []
+        skipped = 0
+        enumerable.each do |member|
+          if skipped < window.offset
+            skipped += 1
+            next
+          end
+
+          rows << yield(member)
+          break if rows.size >= window.count
+        end
+        rows
+      end
+    end
+  end
+end

data/lib/wurk/api/problem.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Wurk
+  module API
+    # Error bodies for the HTTP API, shaped like RFC 9457 problem documents.
+    #
+    # One deliberate divergence from the RFC: `type` is a bare stable slug
+    # ('not_found'), not a URI. A URI would either hardcode a docs host that can
+    # move or emit a mount-relative path the client can't dereference, and the
+    # slug is the part a client actually branches on. `/v1` makes these slugs a
+    # contract: adding one is fine, renaming one is a breaking change.
+    module Problem
+      CONTENT_TYPE = 'application/problem+json'
+
+      NOT_FOUND = 'not_found'
+      METHOD_NOT_ALLOWED = 'method_not_allowed'
+      UNSUPPORTED_API_VERSION = 'unsupported_api_version'
+      INTERNAL_ERROR = 'internal_error'
+      UNAUTHORIZED = 'unauthorized'
+      INVALID_REQUEST = 'invalid_request'
+      # Distinct from `not_found`, which means the API has no such route. A
+      # client that asked to cancel a job needs to tell "you addressed nothing"
+      # apart from "that job already ran".
+      JOB_NOT_FOUND = 'job_not_found'
+      # The same distinction one addressable resource over: a well-formed bid
+      # the `batches` set has never held, as opposed to a mistyped path.
+      BATCH_NOT_FOUND = 'batch_not_found'
+      # And one relation further out: a well-formed fid the `flows` set has
+      # never held. Distinct from `batch_not_found` because a flow's nodes are
+      # batches — a client told "batch not found" for a fid would go looking
+      # for the wrong thing.
+      FLOW_NOT_FOUND = 'flow_not_found'
+      # A well-formed identity that no live heartbeat answers to — the process
+      # exited, or its beat lapsed and Redis reaped the row.
+      PROCESS_NOT_FOUND = 'process_not_found'
+      # The process is live and the caller may signal it, but this one cannot
+      # be signalled at all: an embedded process shares its host application's
+      # PID, so a TSTP or TERM aimed at it would hit the web server around it.
+      PROCESS_NOT_SIGNALABLE = 'process_not_signalable'
+      # Named for RFC 6750 §3.1 so the slug and the `error=` the 403 carries in
+      # WWW-Authenticate are the same word.
+      INSUFFICIENT_SCOPE = 'insufficient_scope'
+      # Separate from `invalid_request` because the client's fix is different:
+      # nothing about the request's shape is wrong, it is only too big, and the
+      # `max_bytes` extension member says by how much.
+      PAYLOAD_TOO_LARGE = 'payload_too_large'
+      # An authorization verdict, like `insufficient_scope` — the credential is
+      # valid and the body is well-formed, but this class is not one the HTTP
+      # API may enqueue.
+      CLASS_NOT_ALLOWED = 'class_not_allowed'
+      # The two ways an `Idempotency-Key` collides. Reused means the same key
+      # arrived with different bytes, which is a client bug it must fix by
+      # rotating the key; in-progress means the first request holding it has
+      # not answered yet, which it fixes by waiting.
+      IDEMPOTENCY_KEY_REUSED = 'idempotency_key_reused'
+      REQUEST_IN_PROGRESS = 'request_in_progress'
+      # Not `insufficient_scope`: the credential is granted everything it needs
+      # and would work against another deployment unchanged. Nothing the client
+      # can send fixes this one, which is why it gets its own slug — a producer
+      # that retried a 403 forever on a frozen deployment is the failure this
+      # avoids.
+      READ_ONLY = 'read_only'
+      # The one refusal that comes with a time attached. `retry_after` repeats
+      # the header as a number so a client that already parses this body does
+      # not have to reach back into the headers for it.
+      RATE_LIMITED = 'rate_limited'
+
+      # Every slug needs a human title; `fetch` below turns a missing one into a
+      # loud failure in the test suite rather than a half-formed error body.
+      TITLES = {
+        NOT_FOUND => 'Not Found',
+        METHOD_NOT_ALLOWED => 'Method Not Allowed',
+        UNSUPPORTED_API_VERSION => 'Unsupported API Version',
+        INTERNAL_ERROR => 'Internal Server Error',
+        UNAUTHORIZED => 'Unauthorized',
+        INSUFFICIENT_SCOPE => 'Insufficient Scope',
+        INVALID_REQUEST => 'Invalid Request',
+        JOB_NOT_FOUND => 'Job Not Found',
+        BATCH_NOT_FOUND => 'Batch Not Found',
+        FLOW_NOT_FOUND => 'Flow Not Found',
+        PROCESS_NOT_FOUND => 'Process Not Found',
+        PROCESS_NOT_SIGNALABLE => 'Process Not Signalable',
+        PAYLOAD_TOO_LARGE => 'Payload Too Large',
+        CLASS_NOT_ALLOWED => 'Class Not Allowed',
+        IDEMPOTENCY_KEY_REUSED => 'Idempotency Key Reused',
+        REQUEST_IN_PROGRESS => 'Request In Progress',
+        READ_ONLY => 'Read-Only Mode',
+        RATE_LIMITED => 'Too Many Requests'
+      }.freeze
+
+      module_function
+
+      # `extra` keywords become extension members (RFC 9457 §3.2), e.g.
+      # `supported_versions:`. Returns a Rack response triple.
+      def render(type, status:, detail:, instance:, headers: nil, **extra)
+        body = {
+          type: type, title: TITLES.fetch(type), status: status, detail: detail, instance: instance
+        }
+        body.merge!(extra)
+        [status, response_headers(headers), [::JSON.generate(body)]]
+      end
+
+      # Renders a refusal that already knows which problem it is — the shape
+      # Validation::Invalid carries. The mapping from a rejection to a status
+      # code stays with the check that made it, so a new rejection never needs
+      # a new arm in the route that surfaces it.
+      def from(error, instance:)
+        render(error.type, status: error.status, detail: error.message, instance: instance, **error.extra)
+      end
+
+      # nosniff so a browser pointed at an error can never be talked into
+      # rendering the reflected request path as anything but data.
+      def response_headers(extra)
+        headers = { 'content-type' => CONTENT_TYPE, 'x-content-type-options' => 'nosniff' }
+        extra ? headers.merge(extra) : headers
+      end
+    end
+  end
+end

data/lib/wurk/api/queues.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative 'page'
+require_relative 'problem'
+require_relative 'response'
+require_relative 'serializers'
+require_relative 'validation'
+
+module Wurk
+  module API
+    # The observe plane: how deep the queues are, what is waiting to retry,
+    # what died, and the counters over the lot.
+    #
+    # Every route reads through a canonical inspector — {Wurk::Stats},
+    # {Wurk::Queue}, {Wurk::RetrySet}, {Wurk::ScheduledSet}, {Wurk::DeadSet},
+    # {Wurk::Batch::Status} — the same objects the dashboard reads. Not to save
+    # code: a second reader over the same Redis keys is a second place for the
+    # size-descending queue order, the latency math, the `paused` set and the
+    # ActiveJob unwrapping to drift, and a dashboard and an API that disagree
+    # about how deep a queue is are worse than either on its own.
+    #
+    # Pause and unpause are the only writes, and they go through
+    # {Wurk::Queue#pause!} / {Wurk::Queue#unpause!}, which expire this
+    # process's fetcher cache of the `paused` set. A bare SADD here would leave
+    # the swarm fetching from a queue the API had just reported paused.
+    module Queues
+      module_function
+
+      # Verb, pattern, the scope a caller must hold, handler. A table rather
+      # than nine `router.get` calls because the scope column is the part that
+      # has to be read at a glance: the two writes take :admin, not :read.
+      # Pausing `default` stops the fleet from working without enqueueing or
+      # deleting anything, so it belongs with the destructive routes rather
+      # than with the listings it sits beside.
+      TABLE = [
+        [:get, '/stats', :read, :stats],
+        [:get, '/queues', :read, :index],
+        [:get, '/queues/:name', :read, :show],
+        [:get, '/retries', :read, :retries],
+        [:get, '/scheduled', :read, :scheduled],
+        [:get, '/dead', :read, :dead],
+        [:get, '/batches/:bid', :read, :batch],
+        [:post, '/queues/:name/pause', :admin, :pause],
+        [:post, '/queues/:name/unpause', :admin, :unpause]
+      ].freeze
+
+      # The refusal rendering wraps every handler here rather than sitting in
+      # each one: they all validate something that came off the network, and a
+      # rescue repeated per route is one a new route gets written without.
+      def draw(router)
+        TABLE.each do |verb, pattern, scope, handler|
+          router.public_send(verb, pattern, scope: scope) do |request|
+            public_send(handler, request)
+          rescue Validation::Invalid => e
+            Problem.from(e, instance: request.path)
+          end
+        end
+      end
+
+      def stats(_request)
+        Response.json(200, Serializers.stats(::Wurk::Stats.new))
+      end
+
+      # Stats#queue_summaries rather than Queue.all: one pipeline instead of an
+      # LLEN round trip per queue, and it comes back in the size-descending
+      # order every other Wurk surface lists queues in.
+      def index(_request)
+        Response.json(200, queues: ::Wurk::Stats.new.queue_summaries.map { |q| Serializers.queue_summary(q) })
+      end
+
+      # No 404 for a name nothing was ever enqueued under. A queue is not an
+      # entity in the Sidekiq schema — it is a LIST that exists only while it
+      # has members — so "never used" and "drained" are the same state in
+      # Redis, and `size: 0` is the honest reading of both. Pausing one before
+      # its first job is a legitimate pre-deploy move for the same reason.
+      def show(request)
+        window = Page.window!(request)
+        queue = ::Wurk::Queue.new(Validation.queue_name!(request.path_params[:name]))
+        jobs = Page.slice(queue, window) { |record| Serializers.job_record(record) }
+        Response.json(200, Serializers.queue_gauges(queue).merge(page: window.page, count: window.count, jobs: jobs))
+      end
+
+      def retries(request) = sorted_set(request, ::Wurk::RetrySet.new)
+      def scheduled(request) = sorted_set(request, ::Wurk::ScheduledSet.new)
+      def dead(request) = sorted_set(request, ::Wurk::DeadSet.new)
+
+      def pause(request) = toggle(request, paused: true)
+      def unpause(request) = toggle(request, paused: false)
+
+      # Idempotent both ways (SADD/SREM), and the resulting state comes back so
+      # a client does not need a second request to confirm the toggle.
+      def toggle(request, paused:)
+        queue = ::Wurk::Queue.new(Validation.queue_name!(request.path_params[:name]))
+        paused ? queue.pause! : queue.unpause!
+        Response.json(200, name: queue.name, paused: paused)
+      end
+
+      # `total` is read before the page is walked, so it describes the set the
+      # page was taken from rather than the one left after a poller drained it.
+      def sorted_set(request, set)
+        window = Page.window!(request)
+        total = set.size
+        jobs = Page.slice(set, window) { |entry| Serializers.sorted_entry(entry) }
+        Response.json(200, name: set.name, total: total, page: window.page, count: window.count, jobs: jobs)
+      end
+
+      def batch(request)
+        bid = Validation.bid!(request.path_params[:bid])
+        status = ::Wurk::Batch::Status.new(bid)
+        return batch_not_found(request, bid) unless status.exists?
+
+        Response.json(200, status.data)
+      end
+
+      def batch_not_found(request, bid)
+        Problem.render(
+          Problem::BATCH_NOT_FOUND,
+          status: 404,
+          detail: "No batch has bid #{bid}; it was never created, or it has expired.",
+          instance: request.path,
+          bid: bid
+        )
+      end
+    end
+  end
+end

data/lib/wurk/api/read_only.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative '../api'
+require_relative 'problem'
+
+module Wurk
+  module API
+    # Whether this deployment answers anything but reads.
+    #
+    # The dashboard has had a read-only mode since the beginning
+    # (`Wurk::Web.config.read_only`, `WURK_WEB_READ_ONLY=1`): a viewer-only
+    # deploy — the public demo is one — where every non-safe verb 403s. The
+    # machine plane keeps exactly that rule, verb for verb, so "read-only"
+    # means one thing across Wurk instead of two. That freezes `admin`'s
+    # destructive routes and `enqueue` alike: a deployment an operator may not
+    # retry a job on is not one a stranger should be able to start a thousand
+    # on, and the alternative is a word whose meaning depends on which plane
+    # you are standing in.
+    #
+    # Only the *mount* differs, and it has to — see `Configuration#api_read_only`
+    # for the three states. Nested in the engine, this API is part of the
+    # dashboard's deployment and inherits its flag through the Rack env
+    # (`Wurk::Web::Authorization` stamps {Wurk::API::READ_ONLY_ENV}). Mounted on
+    # its own path or run standalone it is a different deployment, has no engine
+    # in front of it to stamp anything, and says so itself or not at all.
+    module ReadOnly
+      # RFC 9110 §9.2.1 — the verbs with no side effects the client asked for.
+      # The same three the dashboard's Authorization middleware allows; the API
+      # registers no OPTIONS route, but a read-only deploy refusing a preflight
+      # would be a lie about why.
+      SAFE_METHODS = %w[GET HEAD OPTIONS].freeze
+
+      module_function
+
+      # An explicit setting wins both ways — `false` is how a host keeps its
+      # producer live under a read-only dashboard, so it has to outrank what the
+      # engine stamped, not merely be OR'd into it.
+      #
+      # @return [Boolean] whether writes are frozen for this request's mount.
+      def enabled?(request)
+        explicit = request.config.api_read_only
+        return explicit unless explicit.nil?
+
+        inherited?(request) || request.config.api_read_only?
+      end
+
+      # @return [Array, nil] a 403 problem triple, or nil to let the request on.
+      def refuse(request)
+        return nil if SAFE_METHODS.include?(request.request_method)
+        return nil unless enabled?(request)
+
+        Problem.render(
+          Problem::READ_ONLY,
+          status: 403,
+          detail: 'This Wurk deployment is read-only; it answers GET and HEAD only.',
+          instance: request.path
+        )
+      end
+
+      # Checked before routing, so a write to a path that does not exist is
+      # refused for the reason that applies to every write here rather than
+      # 404ing and leaving a client to discover the freeze one route later.
+      def inherited?(request)
+        !!request.get_header(::Wurk::API::READ_ONLY_ENV)
+      end
+    end
+  end
+end

data/lib/wurk/api/request.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'rack'
+
+module Wurk
+  module API
+    # Rack::Request plus the three things every API handler needs: the segment
+    # captures the router bound ('/jobs/:jid' → `path_params[:jid]`), the
+    # authenticated principal, and mount-agnostic URL building.
+    class Request < ::Rack::Request
+      # Set by App once Auth has accepted the credential, so a handler can ask
+      # what the caller was granted without re-reading the header. Never nil by
+      # the time a handler runs — an unauthenticated request never reaches one.
+      attr_accessor :principal
+
+      # The configuration this app is answering from, stamped by App before
+      # anything reads it. Injectable there for tests, so a handler that wants
+      # a boundary cap or a token's grants must ask the request rather than
+      # reaching for the process-wide singleton behind the app's back.
+      attr_accessor :config
+
+      attr_writer :path_params
+
+      def path_params
+        @path_params ||= {}
+      end
+
+      # Root-relative on purpose. The API answers under three different
+      # prefixes (engine-nested, separately mounted, standalone) and usually
+      # sits behind a proxy, so SCRIPT_NAME is the only prefix it can trust —
+      # rebuilding an absolute URL out of Host/X-Forwarded-* would hand clients
+      # links to an origin they never asked for.
+      def url_for(path)
+        "#{script_name.to_s.chomp('/')}#{path}"
+      end
+
+      # At most `limit` bytes off the request body, so a caller can refuse an
+      # oversized one without ever holding it. Rack 3.1 made `rack.input`
+      # optional and a stream already at EOF answers nil, so both come back as
+      # an empty string: a bodyless request is a request, not a crash.
+      def read_body(limit)
+        body&.read(limit).to_s
+      end
+    end
+  end
+end

data/lib/wurk/api/response.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Wurk
+  module API
+    # Success bodies for the HTTP API; Problem is the error half. One owner per
+    # content type the API emits, so a route table never spells out a header for
+    # itself and the two halves can't drift on the ones they share.
+    module Response
+      CONTENT_TYPE = 'application/json'
+
+      # nosniff for Problem's reason: a body that echoes what the client sent
+      # must never be talked into rendering as anything but data.
+      HEADERS = { 'content-type' => CONTENT_TYPE, 'x-content-type-options' => 'nosniff' }.freeze
+
+      module_function
+
+      # Dups the headers because a Rack middleware downstream is entitled to
+      # add to them, and the frozen literal is shared by every response.
+      #
+      # @return [Array(Integer, Hash, Array<String>)] Rack response triple.
+      def json(status, payload)
+        [status, HEADERS.dup, [::JSON.generate(payload)]]
+      end
+    end
+  end
+end