wurk 1.5.0 → 1.7.0

data/lib/wurk/api/app.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'rack'
+require_relative '../api'
+require_relative '../version'
+require_relative 'auth'
+require_relative 'flows'
+require_relative 'jobs'
+require_relative 'problem'
+require_relative 'queues'
+require_relative 'read_only'
+require_relative 'request'
+require_relative 'response'
+require_relative 'router'
+require_relative 'swarm'
+require_relative 'throttle'
+
+module Wurk
+  module API
+    # The machine-facing HTTP API. Plain Rack under lib/, with no reference to
+    # Rails or the engine, so one implementation serves all three mounts:
+    # engine-nested (`<mount>/api/v1`), separately mounted
+    # (`mount Wurk::API => '/wurk-api'`), and standalone (`run Wurk::API`).
+    #
+    # Nothing here hardcodes '/wurk'. Every URL the API emits is built from
+    # SCRIPT_NAME (Request#url_for) — the same mount-agnostic rule the SPA shell
+    # follows in dashboard_controller.rb.
+    class App
+      # `config` is read on every request rather than captured, so a token
+      # registered after the first request still takes effect. Injectable
+      # because a test must be able to hand this app its own token table
+      # instead of mutating the process-wide one.
+      def initialize(config: nil)
+        @config = config
+        @router = Router.new
+        draw(@router)
+      end
+
+      def call(env)
+        request = Request.new(env)
+        # Stamped once, before anything reads it, so every handler sees the
+        # same config the auth gate did — including a test's injected one.
+        request.config = config
+        response = handle(request)
+        # HEAD is routed as GET, so the handler built a body it must not send.
+        request.head? ? [response[0], response[1], []] : response
+      end
+
+      private
+
+      def config
+        @config || ::Wurk.configuration
+      end
+
+      # One table per plane, each owning its own routes and handlers. Queues,
+      # Flows and Swarm join Jobs here.
+      def draw(router)
+        router.get('/', scope: Auth::ANY) { |request| root(request) }
+        Jobs.draw(router)
+        Queues.draw(router)
+        Flows.draw(router)
+        Swarm.draw(router)
+      end
+
+      # Authentication runs before the version gate and before routing, so an
+      # unauthenticated prober can't enumerate which paths or versions exist
+      # from the difference between a 404 and a 405.
+      #
+      # Then two refusals that are true of the whole deployment rather than of
+      # any one route, in cost order. Read-only is a fact this process already
+      # holds, so it answers without touching Redis. The throttle needs a
+      # credential to charge, which is why it cannot run before authentication —
+      # and it charges every authenticated request, routed or not: a client
+      # walking paths that don't exist is exactly the traffic a ceiling is for.
+      def handle(request)
+        config = request.config
+        return not_found(request) unless Auth.configured?(config)
+
+        principal = Auth.authenticate(request, config)
+        return Auth.unauthorized(request) unless principal
+
+        request.principal = principal
+        refusal = ReadOnly.refuse(request) || Throttle.refuse(request)
+        refusal || route(request)
+      rescue StandardError => e
+        internal_error(request, e)
+      end
+
+      def route(request)
+        path = request.path_info.to_s
+        return unsupported_version(request) unless versioned?(path)
+
+        dispatch(request, path.delete_prefix(VERSION_PREFIX))
+      end
+
+      def dispatch(request, path)
+        match = @router.match(request.request_method, path)
+        return route_miss(request, match) unless match.handler
+        return Auth.forbidden(request, match.scope) unless request.principal.permits?(match.scope)
+
+        request.path_params = match.params
+        match.handler.call(request)
+      end
+
+      # The document a client hits to confirm which mount and which contract it
+      # is talking to before it starts guessing paths. It carries the two
+      # deployment-wide refusals as well: both are things a producer would
+      # otherwise only learn by having a write refused, and a client that can
+      # read "this one is frozen" at startup fails in its own logs instead of
+      # halfway through a batch.
+      def root(request)
+        Response.json(
+          200,
+          api_version: API_VERSION, wurk_version: ::Wurk::VERSION, url: request.url_for(VERSION_PREFIX),
+          read_only: ReadOnly.enabled?(request), rate_limit: rate_limit(request.config)
+        )
+      end
+
+      # nil, not an object with nil members: "there is no ceiling here" and
+      # "there is one, of unknown size" are different answers.
+      def rate_limit(config)
+        limit = config.api_rate_limit
+        return nil unless limit
+
+        { limit: limit, interval_seconds: Throttle.interval_seconds(config.api_rate_limit_interval) }
+      end
+
+      def versioned?(path)
+        path == VERSION_PREFIX || path.start_with?(NESTED_PREFIX)
+      end
+
+      def route_miss(request, match)
+        return not_found(request) if match.allowed.empty?
+
+        Problem.render(
+          Problem::METHOD_NOT_ALLOWED,
+          status: 405,
+          detail: "#{request.request_method} is not allowed on #{request.path_info}.",
+          instance: request.path,
+          headers: { 'allow' => allow_header(match.allowed) }
+        )
+      end
+
+      # A path that answers GET answers HEAD too, so advertise both.
+      def allow_header(verbs)
+        verbs = verbs.dup
+        verbs << 'HEAD' if verbs.include?('GET')
+        verbs.join(', ')
+      end
+
+      def not_found(request)
+        Problem.render(
+          Problem::NOT_FOUND,
+          status: 404,
+          detail: "No route matches #{request.request_method} #{request.path_info}.",
+          instance: request.path
+        )
+      end
+
+      # 404 rather than 400: an unknown version is an address that does not
+      # exist, and the client's own request was well-formed.
+      def unsupported_version(request)
+        Problem.render(
+          Problem::UNSUPPORTED_API_VERSION,
+          status: 404,
+          detail: "The Wurk HTTP API is served under #{VERSION_PREFIX}.",
+          instance: request.path,
+          supported_versions: SUPPORTED_VERSIONS
+        )
+      end
+
+      # The exception details stay in the log. A machine client gets a stable
+      # slug it can retry on, never a backtrace naming host internals.
+      def internal_error(request, error)
+        ::Wurk.logger.error { "Wurk::API #{request.request_method} #{request.path}: #{error.class}: #{error.message}" }
+        ::Wurk.logger.debug { Array(error.backtrace).join("\n") }
+        Problem.render(
+          Problem::INTERNAL_ERROR,
+          status: 500,
+          detail: 'The request could not be completed.',
+          instance: request.path
+        )
+      end
+    end
+  end
+end

data/lib/wurk/api/auth.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'openssl'
+require_relative 'problem'
+
+module Wurk
+  module API
+    # Bearer-token authentication and scope checks for the machine-facing HTTP
+    # API. Nothing behind /v1 answers without passing through here.
+    #
+    # Deliberately a separate plane from the dashboard's. That one is cookie-
+    # authenticated and CSRF-guarded by Wurk::SameOriginGuard, which denies any
+    # request that doesn't carry `Sec-Fetch-Site: same-origin` — a header the
+    # browser sets and a Python or Go producer never sends. Reusing it would
+    # mean either 403ing every legitimate machine client or relaxing the one
+    # check that stops a cross-site page from driving a logged-in operator's
+    # dashboard.
+    module Auth
+      # `admin` grants the other two. An operator token allowed to stop a
+      # process but refused a queue listing would be a surprise, not a
+      # safeguard.
+      SCOPES = %i[enqueue read admin].freeze
+
+      # Required scope for a route every authenticated client needs whatever it
+      # was granted — the discovery document, which an enqueue-only producer
+      # has to read to confirm the contract it is about to post to.
+      ANY = :any
+
+      ROUTE_SCOPES = (SCOPES + [ANY]).freeze
+
+      # Under 20 characters the host almost certainly typed the token instead of
+      # generating one (`SecureRandom.urlsafe_base64(16)` is 22). A guessable
+      # token on this API is remote code selection, not just a data leak.
+      MIN_TOKEN_LENGTH = 20
+
+      # Printable ASCII, no spaces — what an Authorization header carries
+      # intact. A token that loses a byte in transit fails as "wrong token",
+      # the least debuggable 401 there is, so reject the shape up front.
+      TOKEN_FORMAT = /\A[\x21-\x7e]+\z/
+
+      # RFC 6750 §2.1. The scheme is case-insensitive (RFC 9110 §11.1); the
+      # credential is not.
+      BEARER = /\ABearer[ \t]+([\x21-\x7e]+)[ \t]*\z/i
+
+      REALM = 'Bearer realm="wurk"'
+
+      # Domain-separated so the label below is not a digest of the raw token —
+      # a value that leaked into a log would otherwise be a free head start on
+      # confirming a guessed token offline.
+      FINGERPRINT_DOMAIN = 'wurk.api.token.'
+
+      # 128 bits of the digest. Long enough that two credentials never share a
+      # label, short enough to read in a log line.
+      FINGERPRINT_LENGTH = 32
+
+      # What the request proved about itself: the scopes it was granted, and a
+      # stable label for the credential that granted them. `id` is a truncated
+      # domain-separated digest, never the token — enough to namespace
+      # per-credential state (an Idempotency-Key record belongs to the producer
+      # that chose it, not to whoever guesses the same string), and nothing a
+      # holder could work backwards from.
+      Principal = Struct.new(:id, :scopes) do
+        def permits?(scope)
+          scope == ANY || scopes.include?(scope) || scopes.include?(:admin)
+        end
+      end
+
+      module_function
+
+      # The gate the whole API hangs off. No token registered → the engine
+      # never mounts the app, and an app mounted directly answers 404 rather
+      # than advertising a surface with nothing behind it.
+      def configured?(config)
+        !config.api_tokens.empty?
+      end
+
+      # Validates a credential where it is declared, so a typo raises in the
+      # initializer that wrote it instead of surfacing as a 401 in production.
+      #
+      # @return [Array(String, Array<Symbol>)] token value and granted scopes
+      def credential!(token, scopes)
+        value = token.to_s
+        unless value.length >= MIN_TOKEN_LENGTH
+          raise ArgumentError, "api_token must be at least #{MIN_TOKEN_LENGTH} characters"
+        end
+        raise ArgumentError, 'api_token must be printable ASCII with no spaces' unless TOKEN_FORMAT.match?(value)
+
+        [value, granted!(scopes)]
+      end
+
+      def granted!(scopes)
+        granted = Array(scopes).map { |scope| scope.to_s.to_sym }.uniq
+        raise ArgumentError, 'api_token requires at least one scope' if granted.empty?
+
+        unknown = granted - SCOPES
+        unless unknown.empty?
+          raise ArgumentError, "unknown api_token scope #{unknown.inspect}; valid scopes are #{SCOPES.inspect}"
+        end
+
+        granted.freeze
+      end
+
+      # @return [Principal, nil] nil when no credential was presented, or the
+      #   one presented matches nothing registered.
+      def authenticate(request, config)
+        presented = bearer(request.get_header('HTTP_AUTHORIZATION'))
+        return nil unless presented
+
+        token, scopes = lookup(presented, config.api_tokens)
+        scopes && Principal.new(fingerprint(token), scopes)
+      end
+
+      def bearer(header)
+        match = BEARER.match(header.to_s)
+        match && match[1]
+      end
+
+      # Walks every registered token with no early return on a hit, so the
+      # clock can't tell a client where in the table its guess landed — or
+      # whether it landed at all. Both sides are digested first: OpenSSL's
+      # compare demands equal lengths, and the bytesize pre-check the obvious
+      # implementation reaches for (Rack::Utils.secure_compare does exactly
+      # that) answers "how long is the real token" to anyone who can time this.
+      def lookup(presented, tokens)
+        digest = ::Digest::SHA256.digest(presented)
+        found = nil
+        tokens.each do |token, scopes|
+          found = [token, scopes] if OpenSSL.fixed_length_secure_compare(digest, ::Digest::SHA256.digest(token))
+        end
+        found
+      end
+
+      def fingerprint(token)
+        ::Digest::SHA256.hexdigest("#{FINGERPRINT_DOMAIN}#{token}")[0, FINGERPRINT_LENGTH]
+      end
+
+      # RFC 6750 §3. The challenge names `invalid_token` only when the client
+      # actually presented one — telling a client that sent no credential that
+      # its credential was rejected sends it hunting for the wrong bug.
+      def unauthorized(request)
+        presented = request.get_header('HTTP_AUTHORIZATION')
+        Problem.render(
+          Problem::UNAUTHORIZED,
+          status: 401,
+          detail: presented ? 'The bearer token presented is not valid.' : 'A bearer token is required.',
+          instance: request.path,
+          headers: { 'www-authenticate' => presented ? %(#{REALM}, error="invalid_token") : REALM }
+        )
+      end
+
+      # 403, not a 404 hiding the route: the client already authenticated, so
+      # concealing the address buys nothing and costs it the one fact it needs
+      # — which scope to ask its operator for.
+      def forbidden(request, scope)
+        Problem.render(
+          Problem::INSUFFICIENT_SCOPE,
+          status: 403,
+          detail: "This token is not granted the #{scope} scope.",
+          instance: request.path,
+          headers: { 'www-authenticate' => %(#{REALM}, error="insufficient_scope", scope="#{scope}") },
+          required_scope: scope
+        )
+      end
+    end
+  end
+end

data/lib/wurk/api/flows.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative 'problem'
+require_relative 'response'
+require_relative 'serializers'
+require_relative 'validation'
+
+module Wurk
+  module API
+    # One route: read a flow.
+    #
+    # A producer that posted a graph needs to know how far it got, and a fid is
+    # the only thing it holds — so this answers by fid and nothing else. There
+    # is no listing: the `flows` index is a dashboard affordance for a human
+    # who lost an id, and paging a machine client through every flow in the
+    # deployment is not a question a producer has.
+    #
+    # Nor is there a write. Abandonment is an operator decision made with the
+    # graph on screen (slice 11 decision 4), and the dashboard is where that
+    # screen is; a producer that could abandon its own flows over HTTP is one
+    # bad retry away from killing a run that was merely slow.
+    #
+    # Reads through {Wurk::Flow::Status}, the same view the dashboard uses, for
+    # the reason every other observe-plane route reads through an inspector: a
+    # second reader of the flow key schema is a second thing to keep in step
+    # with the completion scripts that write it.
+    module Flows
+      module_function
+
+      TABLE = [
+        [:get, '/flows/:fid', :read, :show]
+      ].freeze
+
+      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 show(request)
+        fid = Validation.fid!(request.path_params[:fid])
+        status = ::Wurk::Flow::Status.new(fid)
+        return not_found(request, fid) unless status.exists?
+
+        Response.json(200, Serializers.flow(status))
+      end
+
+      # Expiry is named because it is the likeliest answer for a producer whose
+      # fid used to work: a flow is kept on the batch clock and then goes, and
+      # a client that assumed otherwise is the one reading this.
+      def not_found(request, fid)
+        Problem.render(
+          Problem::FLOW_NOT_FOUND,
+          status: 404,
+          detail: "No flow has fid #{fid}; it was never created, or it has expired.",
+          instance: request.path,
+          fid: fid
+        )
+      end
+    end
+  end
+end

data/lib/wurk/api/idempotency.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'digest'
+require_relative '../keys'
+require_relative 'problem'
+require_relative 'response'
+require_relative 'validation'
+
+module Wurk
+  module API
+    # `Idempotency-Key` replay protection for the produce plane.
+    #
+    # A producer whose connection drops mid-`POST /jobs` cannot tell a lost
+    # request from a lost response, so its only safe move is to send it again —
+    # and without this, the retry is a second job. The header turns that retry
+    # into a replay: the first request's response comes back verbatim and
+    # nothing is enqueued twice.
+    #
+    # Entirely client-driven. No header means no key, no record and no round
+    # trip, so a producer that does not need this pays nothing for it.
+    module Idempotency
+      HEADER = 'HTTP_IDEMPOTENCY_KEY'
+
+      # The same shape a bearer token has to survive: printable ASCII, no
+      # spaces. A key that loses a byte in transit would silently address a
+      # different record, which is the one failure this module exists to
+      # prevent.
+      KEY_FORMAT = /\A[\x21-\x7e]{1,255}\z/
+
+      # Marks a replayed response, so a client can tell "your job was enqueued"
+      # from "your job was enqueued, earlier".
+      REPLAY_HEADER = 'idempotency-replayed'
+
+      # A record is `<status>\n<body digest>\n<body>`, and status `0` means a
+      # claim still in flight. Line-oriented rather than JSON because it is
+      # read back under contention: a truncated or hand-poisoned value has to
+      # degrade to "still in progress", not to a parser exception on the
+      # request path.
+      PENDING = 0
+
+      module_function
+
+      # Wraps a state-changing handler. Without the header this is a bare call
+      # through; with it, exactly one of the requests sharing a key runs the
+      # handler and the rest replay its answer.
+      #
+      # @param raw_body [String] the bytes the response is pinned to, so the
+      #   same key sent with a different body is a client bug, not a replay.
+      def around(request, raw_body, config, &handler)
+        key = presented(request)
+        return handler.call unless key
+
+        slot = slot_for(request, key)
+        fingerprint = ::Digest::SHA256.hexdigest(raw_body)
+        stored = claim(slot, fingerprint, config.api_idempotency_ttl)
+        return replay(request, stored, fingerprint) if stored
+
+        settle(slot, fingerprint, &handler)
+      end
+
+      def presented(request)
+        key = request.get_header(HEADER)
+        return nil if key.nil?
+        return key if KEY_FORMAT.match?(key)
+
+        raise Validation::Invalid, 'Idempotency-Key must be 1-255 printable ASCII characters with no spaces.'
+      end
+
+      # Scoped to the credential and to the route. The key is a string the
+      # client chose: two producers that both sent `1` must not see each
+      # other's jids, and the same key on `/jobs` and `/jobs/bulk` addresses two
+      # different requests. Hashed rather than concatenated so the client's own
+      # string never reaches Redis in the clear and every slot is one length.
+      def slot_for(request, key)
+        ::Wurk::Keys.idempotency(
+          ::Digest::SHA256.hexdigest("#{request.principal.id}\n#{request.path_info}\n#{key}")
+        )
+      end
+
+      # One round trip: reserve the key if it is free, and read what is there
+      # either way. Deliberately not a MULTI — the SET already picked the
+      # winner, and the GET only has to explain the loss.
+      #
+      # @return [String, nil] nil when this request owns the key; otherwise the
+      #   record the owner left, or is still to leave. An empty string when the
+      #   owner's record expired in between, which reads as "in flight" and is
+      #   the safe answer: it never enqueues a second job.
+      def claim(slot, fingerprint, ttl)
+        reserved, existing = ::Wurk.redis do |conn|
+          conn.pipelined do |pipe|
+            pipe.call('SET', slot, encode(PENDING, fingerprint, ''), 'NX', 'EX', ttl)
+            pipe.call('GET', slot)
+          end
+        end
+        reserved ? nil : existing.to_s
+      end
+
+      # Only a success is worth replaying. A rejected body is a request the
+      # client should be able to correct and send again under the same key, and
+      # a raise is a request whose outcome nobody knows — both release the key
+      # rather than pinning an answer to it.
+      def settle(slot, fingerprint)
+        response = yield
+        response[0] < 300 ? record(slot, fingerprint, response) : release(slot)
+        response
+      rescue StandardError
+        release(slot)
+        raise
+      end
+
+      # KEEPTTL so the window is the first request's, not this write's, and XX
+      # so a claim whose TTL lapsed mid-flight is not resurrected as a record
+      # with no expiry at all.
+      def record(slot, fingerprint, response)
+        status, _headers, body = response
+        ::Wurk.redis { |conn| conn.call('SET', slot, encode(status, fingerprint, body.join), 'XX', 'KEEPTTL') }
+      end
+
+      def release(slot)
+        ::Wurk.redis { |conn| conn.call('DEL', slot) }
+      end
+
+      def replay(request, stored, fingerprint)
+        record = decode(stored)
+        return in_progress(request) unless record
+
+        status, digest, body = record
+        return reused(request) unless digest == fingerprint
+        return in_progress(request) if status == PENDING
+
+        [status, Response::HEADERS.merge(REPLAY_HEADER => 'true'), [body]]
+      end
+
+      def encode(status, digest, body) = "#{status}\n#{digest}\n#{body}"
+
+      # @return [Array(Integer, String, String), nil] nil for a record that is
+      #   gone or unreadable — the caller treats both as still in flight.
+      def decode(stored)
+        status, digest, body = stored.split("\n", 3)
+        return nil if digest.nil? || digest.empty?
+
+        [status.to_i, digest, body.to_s]
+      end
+
+      # 409 rather than 400: the request is well-formed, and what it collides
+      # with is a fact about the server's state that the client can resolve by
+      # rotating the key.
+      def reused(request)
+        Problem.render(
+          Problem::IDEMPOTENCY_KEY_REUSED,
+          status: 409,
+          detail: 'This Idempotency-Key was already used for a different request body.',
+          instance: request.path
+        )
+      end
+
+      def in_progress(request)
+        Problem.render(
+          Problem::REQUEST_IN_PROGRESS,
+          status: 409,
+          detail: 'A request with this Idempotency-Key is still in flight.',
+          instance: request.path,
+          headers: { 'retry-after' => '1' }
+        )
+      end
+    end
+  end
+end