api2convert 10.2.0

data/lib/api2convert/errors.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  # The typed exception hierarchy.
+  #
+  # Every failure raised by the SDK descends from {Error}. HTTP error responses
+  # (status >= 400) map to {ApiError} and its subclasses; transport failures,
+  # conversion failures, poll timeouts and webhook verification failures descend
+  # directly from the base.
+  #
+  # The class names use Ruby's `...Error` convention; they map 1:1 to the PHP
+  # SDK's `...Exception` classes.
+  class Error < StandardError; end
+
+  # An HTTP error response (status >= 400).
+  #
+  # Used directly for a 4xx with no more specific subclass; specific statuses map
+  # to the dedicated subclasses below.
+  class ApiError < Error
+    # @return [Integer] the HTTP status code.
+    attr_reader :status_code
+    # @return [String, nil] the `X-Request-Id` response header, if any. Quote it
+    #   in support requests.
+    attr_reader :request_id
+    # @return [Hash] the decoded JSON error body, or `{}` when absent/unparseable.
+    attr_reader :body
+
+    def initialize(message, status_code: 0, request_id: nil, body: nil)
+      super(message)
+      @status_code = status_code
+      @request_id = request_id
+      @body = body || {}
+    end
+  end
+
+  # The API key is missing, invalid or not permitted (HTTP 401 / 403).
+  class AuthenticationError < ApiError; end
+
+  # The account has no remaining quota/credit (HTTP 402).
+  class PaymentRequiredError < ApiError; end
+
+  # The requested resource does not exist (HTTP 404).
+  class NotFoundError < ApiError; end
+
+  # The request was rejected as invalid, e.g. an unknown target (HTTP 400 / 422).
+  class ValidationError < ApiError; end
+
+  # Too many requests (HTTP 429), raised only once auto-retries are exhausted.
+  class RateLimitError < ApiError
+    # @return [Integer, nil] seconds to wait before retrying, parsed from the
+    #   `Retry-After` header (raw, uncapped).
+    attr_reader :retry_after
+
+    def initialize(message, status_code: 429, request_id: nil, body: nil, retry_after: nil)
+      super(message, status_code: status_code, request_id: request_id, body: body)
+      @retry_after = retry_after
+    end
+  end
+
+  # A server-side error (HTTP >= 500), raised once auto-retries are exhausted.
+  class ServerError < ApiError; end
+
+  # A request did not yield a usable response.
+  #
+  # Raised for a transport-level failure (DNS/connection/TLS/read) once idempotent
+  # retries are exhausted, or for a 2xx response whose body is not valid JSON.
+  class NetworkError < Error; end
+
+  # A job reached the `failed` (or `canceled`) status.
+  #
+  # The originating {Model::Job} is attached so you can inspect its errors and
+  # warnings.
+  class ConversionFailedError < Error
+    # @return [Model::Job] the failed job.
+    attr_reader :job
+
+    def initialize(job, message = nil)
+      @job = job
+      super(message.nil? ? self.class.build_message(job) : message)
+    end
+
+    # @return [Array<Model::JobMessage>] the failed job's errors (may be empty if
+    #   the API gave no detail).
+    def errors
+      @job.errors
+    end
+
+    def self.build_message(job)
+      first = job.errors.first
+      unless first.nil?
+        code = first.code.nil? ? "" : " (code #{first.code})"
+        return "Conversion failed: #{first.message}#{code}"
+      end
+      info = job.status.info
+      info.nil? ? "Conversion failed." : "Conversion failed: #{info}"
+    end
+  end
+
+  # A job did not reach a terminal status within the configured poll timeout.
+  #
+  # The job is still running server-side — re-fetch it later with
+  # `client.jobs.get(job.id)`. (Maps to the PHP SDK's `TimeoutException`; named to
+  # avoid shadowing Ruby's `Timeout::Error`.)
+  class ConversionTimeoutError < Error
+    # @return [Model::Job] the job that was still running when the wait timed out.
+    attr_reader :job
+
+    def initialize(job, timeout_seconds)
+      @job = job
+      super(
+        "Timed out after #{timeout_seconds}s waiting for job #{job.id} to finish " \
+        "(last status: #{job.status.code})."
+      )
+    end
+  end
+
+  # A webhook payload could not be verified against the provided signature/secret.
+  #
+  # Treat this as a security event: do not trust or process the payload.
+  class SignatureVerificationError < Error; end
+end

data/lib/api2convert/http/net_http_sender.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "openssl"
+require "timeout"
+
+module Api2Convert
+  module Http
+    # The default {HttpSender}, built on Ruby's stdlib `Net::HTTP` (zero runtime
+    # dependencies).
+    #
+    # `Net::HTTP` does not follow redirects on its own — this SDK relies on that.
+    # A request only follows a 3xx when {Request#follow_redirects} is true (the
+    # no-secret download path); a redirect is then re-issued as a bare GET carrying
+    # only `Accept`/`User-Agent`, so a custom `X-Oc-*` secret header can never be
+    # forwarded to the redirect target.
+    #
+    # An {HttpSender} is any object responding to `call(request) -> Response`. Unit
+    # tests inject a fake in its place; this real sender is exercised end-to-end by
+    # the independent security suite against loopback servers.
+    class NetHttpSender
+      MAX_REDIRECTS = 5
+      REDIRECT_CODES = [301, 302, 303, 307, 308].freeze
+
+      # Errors worth surfacing when they strike mid-stream (after bytes have
+      # already reached the sink). They are re-raised as {NetworkError} so the
+      # transport does NOT retry — replaying would re-stream the whole body and
+      # append it to the partial file, silently corrupting the download.
+      #
+      # This MUST stay a superset of {Transport::TRANSPORT_ERRORS}: any transport
+      # error the retry loop would otherwise catch (notably OpenSSL::SSL::SSLError
+      # on a truncated/reset TLS body) has to be intercepted here first, or an
+      # idempotent streamed GET gets retried and the file is corrupted.
+      STREAM_ERRORS = [
+        IOError, EOFError, SocketError, SystemCallError, Timeout::Error,
+        OpenSSL::SSL::SSLError, URI::Error,
+        Net::OpenTimeout, Net::ReadTimeout, Net::HTTPBadResponse, Net::ProtocolError
+      ].freeze
+
+      METHOD_CLASSES = {
+        "GET" => Net::HTTP::Get,
+        "HEAD" => Net::HTTP::Head,
+        "POST" => Net::HTTP::Post,
+        "PUT" => Net::HTTP::Put,
+        "PATCH" => Net::HTTP::Patch,
+        "DELETE" => Net::HTTP::Delete,
+        "OPTIONS" => Net::HTTP::Options
+      }.freeze
+
+      def initialize(timeout: 30)
+        @timeout = timeout
+      end
+
+      def call(request)
+        perform(
+          request.method, request.url, request.headers,
+          request.body, request.body_stream, request.content_length,
+          request.follow_redirects, request.response_sink, 0
+        )
+      end
+
+      private
+
+      def perform(method, url, headers, body, body_stream, content_length, follow, sink, hops)
+        uri = URI.parse(url)
+        raise Api2Convert::NetworkError, "Unsupported or non-HTTP URL: #{url}" unless uri.is_a?(URI::HTTP)
+
+        http = build_http(uri)
+        req = build_request(method, uri, headers, body, body_stream, content_length)
+
+        redirect_to = nil
+        result = nil
+        http.start do |conn|
+          conn.request(req) do |res|
+            status = res.code.to_i
+            if follow && REDIRECT_CODES.include?(status) && hops < MAX_REDIRECTS &&
+               !res["location"].to_s.empty?
+              redirect_to = res["location"]
+            elsif sink && status >= 200 && status < 300
+              # Stream the success body straight to the sink — never buffered whole
+              # in memory — and hand back an empty-body Response.
+              stream_body(res, sink)
+              result = to_response(res, "")
+            else
+              result = to_response(res, res.body || "")
+            end
+          end
+        end
+
+        if redirect_to
+          # Re-issue as a bare GET carrying only non-secret headers, so no X-Oc-*
+          # secret header is ever forwarded to the redirect target.
+          safe = {}
+          %w[Accept User-Agent].each { |k| safe[k] = headers[k] unless headers[k].nil? }
+          next_url = URI.join(url, redirect_to).to_s
+          return perform("GET", next_url, safe, nil, nil, nil, follow, sink, hops + 1)
+        end
+
+        result
+      end
+
+      def stream_body(res, sink)
+        res.read_body { |chunk| sink.write(chunk) }
+      rescue *STREAM_ERRORS => e
+        # A failure once bytes have flowed to the sink must not be retried: a replay
+        # would append to a partial file and corrupt it. Raise a NetworkError (not a
+        # retryable transport error) so the transport surfaces it directly and the
+        # caller can delete the partial target.
+        raise Api2Convert::NetworkError, "Download stream failed: #{e.message}"
+      end
+
+      def build_http(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.is_a?(URI::HTTPS)
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        http.write_timeout = @timeout if http.respond_to?(:write_timeout=)
+        # The SDK's own retry policy (in Transport) is the sole authority. Disable
+        # Net::HTTP's built-in idempotent connection-error retry so requests are
+        # never silently re-sent underneath us (double retries / duplicate hits).
+        http.max_retries = 0 if http.respond_to?(:max_retries=)
+        http
+      end
+
+      def build_request(method, uri, headers, body, body_stream, content_length)
+        klass = METHOD_CLASSES[method]
+        raise Api2Convert::NetworkError, "Unsupported HTTP method: #{method}" if klass.nil?
+
+        req = klass.new(uri.request_uri)
+        headers.each { |key, value| req[key] = value unless value.nil? }
+        if body_stream
+          req.body_stream = body_stream
+          req["Content-Length"] = content_length.to_s unless content_length.nil?
+        elsif body
+          req.body = body
+        end
+        req
+      end
+
+      def to_response(res, body)
+        headers = {}
+        res.each_header { |key, value| headers[key.downcase] = value }
+        Response.new(res.code.to_i, headers, body, res.message.to_s)
+      end
+    end
+  end
+end

data/lib/api2convert/http/request.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Http
+    # A transport-agnostic HTTP request. The {Transport} builds these and hands
+    # them to an {HttpSender}; a retry rebuilds a fresh one so a seekable body is
+    # replayed from the start.
+    #
+    # Exactly one of {#body} (a String) or {#body_stream} (an IO whose byte length
+    # is {#content_length}) is set on a request with a payload.
+    class Request
+      attr_reader :method, :url, :headers, :body, :body_stream, :content_length, :response_sink
+      # Whether the sender may follow a 3xx redirect. Set by the transport per
+      # request: authenticated requests carry a secret in a custom `X-Oc-*` header,
+      # so they must NOT follow redirects (the header could leak to another host).
+      attr_accessor :follow_redirects
+
+      def initialize(method:, url:, headers: {}, body: nil, body_stream: nil,
+                     content_length: nil, follow_redirects: false, response_sink: nil)
+        @method = method.to_s.upcase
+        @url = url
+        @headers = headers
+        @body = body
+        @body_stream = body_stream
+        @content_length = content_length
+        @follow_redirects = follow_redirects
+        # An IO-like object (responds to `write`) to stream a successful download
+        # body into, instead of buffering it whole. nil for a normal request.
+        @response_sink = response_sink
+      end
+
+      # Redacted representation — {#headers} carries the raw `X-Oc-Api-Key` /
+      # `X-Oc-Download-Password` secrets, so the default `#inspect` would print
+      # them in cleartext in a log line or a backtrace. Mask every `X-Oc-*` value.
+      def inspect
+        safe = @headers.to_h do |key, value|
+          [key, key.to_s.downcase.start_with?("x-oc-") ? Support::Secret.mask(value) : value]
+        end
+        "#<#{self.class.name} method=#{@method.inspect} url=#{@url.inspect} headers=#{safe.inspect}>"
+      end
+
+      def to_s
+        inspect
+      end
+    end
+  end
+end

data/lib/api2convert/http/response.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Http
+    # A transport-agnostic HTTP response. Headers are stored with downcased keys
+    # so {#header} lookups are case-insensitive regardless of the sender.
+    class Response
+      attr_reader :status, :headers, :body, :reason
+
+      def initialize(status, headers, body, reason = "")
+        @status = status
+        @headers = headers || {}
+        @body = body || ""
+        @reason = reason || ""
+      end
+
+      # Case-insensitive header lookup. Returns nil when absent.
+      def header(name)
+        @headers[name.to_s.downcase]
+      end
+    end
+  end
+end

data/lib/api2convert/http/transport.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "socket"
+require "time"
+require "timeout"
+require "uri"
+
+module Api2Convert
+  module Http
+    # The HTTP layer: authenticated requests, transient-failure retries with
+    # exponential backoff, error-response mapping to typed exceptions, and JSON
+    # decoding.
+    #
+    # Resources talk to the API through {#request}; the uploader and the
+    # downloader use {#send_request} / {#interpret} directly because they need
+    # non-JSON bodies and per-job auth. Internal.
+    class Transport
+      RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+      IDEMPOTENT_METHODS = %w[GET HEAD PUT DELETE OPTIONS TRACE].freeze
+      MAX_BACKOFF_SECONDS = 8.0
+      # Upper bound for an honored `Retry-After` — a hostile/misconfigured value
+      # asking for an absurd delay can never stall a worker for hours.
+      MAX_RETRY_AFTER_SECONDS = 120.0
+
+      # Transport-level failures worth wrapping as {NetworkError} (and retrying,
+      # for idempotent requests). `SystemCallError` covers the `Errno::*` family.
+      TRANSPORT_ERRORS = [
+        SocketError, SystemCallError, IOError, EOFError,
+        Timeout::Error, OpenSSL::SSL::SSLError, URI::Error,
+        Net::OpenTimeout, Net::ReadTimeout, Net::HTTPBadResponse, Net::ProtocolError
+      ].freeze
+
+      attr_reader :config
+
+      def initialize(sender, config, sleeper: nil, rng: nil)
+        @sender = sender
+        @config = config
+        @sleeper = sleeper || ->(seconds) { Kernel.sleep(seconds) }
+        @rng = rng || -> { Kernel.rand }
+      end
+
+      # Redacted representation — the default `#inspect` would dump the config's
+      # API key in cleartext, so it is overridden to mask it.
+      def inspect
+        "#<#{self.class.name} base_url=#{@config.base_url.inspect} " \
+          "api_key=#{Support::Secret.mask(@config.api_key)}>"
+      end
+
+      def to_s
+        inspect
+      end
+
+      # Sleep for (at least) +seconds+ with a small upward jitter. Used by job
+      # polling; the jitter keeps a fleet from polling in lockstep.
+      def pause(seconds)
+        @sleeper.call(jitter(seconds))
+      end
+
+      # Perform an authenticated JSON request and return the decoded body.
+      def request(method, path, body = nil, query = nil, headers = nil)
+        request_headers = { "X-Oc-Api-Key" => @config.api_key }
+        request_headers.merge!(headers) unless headers.nil?
+        content = nil
+        unless body.nil?
+          content = JSON.generate(body)
+          request_headers["Content-Type"] = "application/json"
+        end
+        url = build_url(path, query)
+
+        build = lambda do
+          Request.new(method: method, url: url, headers: request_headers.dup, body: content)
+        end
+        interpret(send_request(build))
+      end
+
+      # Send a request (rebuilt fresh each attempt) with retry/backoff. +build+
+      # returns a fresh {Request} — a retry re-invokes it so a seekable body is
+      # replayed from the start. Adds the common `Accept`/`User-Agent` headers but
+      # no auth (callers add the header they need). +replayable+ must be false for
+      # a non-seekable body so it is sent once.
+      #
+      # +follow_redirects+ defaults to false: authenticated requests carry a secret
+      # in a custom `X-Oc-*` header, which a redirect could leak to another host.
+      # Only the self-contained download path (no account key) opts in.
+      def send_request(build, replayable: true, follow_redirects: false)
+        attempt = 0
+        loop do
+          request = build.call
+          request.headers["Accept"] = "application/json"
+          request.headers["User-Agent"] = user_agent
+          request.follow_redirects = follow_redirects
+          idempotent = idempotent?(request)
+
+          begin
+            response = @sender.call(request)
+          rescue *TRANSPORT_ERRORS => e
+            # A non-idempotent request must not be replayed on a network error:
+            # the backend may already have acted, so a blind retry could create a
+            # duplicate job (and a duplicate charge).
+            if replayable && idempotent && attempt < @config.max_retries
+              backoff(attempt)
+              attempt += 1
+              next
+            end
+            raise NetworkError, "Request to API2Convert failed: #{e.message}"
+          end
+
+          status = response.status
+          may_retry = RETRYABLE_STATUSES.include?(status) && replayable &&
+                      attempt < @config.max_retries && (status == 429 || idempotent)
+          if may_retry
+            backoff(attempt, response.header("retry-after"))
+            attempt += 1
+            next
+          end
+
+          return response
+        end
+      end
+
+      # Raise a typed exception for error responses; otherwise decode JSON.
+      def interpret(response)
+        ensure_successful(response)
+
+        raw = response.body
+        return {} if raw.nil? || raw.empty?
+
+        begin
+          decoded = JSON.parse(raw)
+        rescue JSON::ParserError => e
+          # A 2xx carrying a non-JSON body (e.g. an intermediary HTML page) must
+          # surface as an SDK exception, not a raw parser error escaping the tree.
+          raise NetworkError, "API2Convert returned a non-JSON success response: #{e.message}"
+        end
+        decoded.is_a?(Hash) || decoded.is_a?(Array) ? decoded : {}
+      end
+
+      # Raise the appropriate typed exception when +response+ is an HTTP error.
+      def ensure_successful(response)
+        status = response.status
+        return if status < 400
+
+        body = decode_safe(response)
+        api_message = body["message"]
+        message = api_message.is_a?(String) ? api_message : fallback_message(response)
+        request_id = response.header("x-request-id")
+        request_id = nil if request_id.nil? || request_id.empty?
+
+        case status
+        when 401, 403
+          raise AuthenticationError.new(message, status_code: status, request_id: request_id, body: body)
+        when 402
+          raise PaymentRequiredError.new(message, status_code: status, request_id: request_id, body: body)
+        when 404
+          raise NotFoundError.new(message, status_code: status, request_id: request_id, body: body)
+        when 429
+          raise RateLimitError.new(
+            message, status_code: status, request_id: request_id, body: body,
+                     retry_after: parse_retry_after(response.header("retry-after"))
+          )
+        when 400, 422
+          raise ValidationError.new(message, status_code: status, request_id: request_id, body: body)
+        else
+          if status >= 500
+            raise ServerError.new(message, status_code: status, request_id: request_id, body: body)
+          end
+
+          raise ApiError.new(message, status_code: status, request_id: request_id, body: body)
+        end
+      end
+
+      # Download a (self-contained) URL. Used for output downloads — these URLs
+      # need no API key.
+      #
+      # When +sink+ is an IO-like object (responds to `write`), the body is streamed
+      # to it chunk-by-chunk and +nil+ is returned, so a large file never has to be
+      # buffered whole in memory. With no +sink+ the body is buffered and returned
+      # (the in-memory `contents` path).
+      #
+      # +follow_redirects+ is true for a passwordless download (storage URLs
+      # legitimately redirect, and no secret is carried) and false when a
+      # download-password header is present (so it can never leak on a redirect).
+      def download(uri, headers = {}, follow_redirects: true, sink: nil)
+        request_headers = headers.nil? ? {} : headers
+        build = lambda do
+          Request.new(method: "GET", url: uri, headers: request_headers.dup, response_sink: sink)
+        end
+        response = send_request(build, replayable: true, follow_redirects: follow_redirects)
+        ensure_successful(response)
+        # A no-follow download that resolved to a 3xx (e.g. a password-protected
+        # download whose redirect the policy refused to follow) must never be
+        # written as the file: the body is the redirect page, not the content.
+        # Guard the success path to 2xx so a 3xx can never silently corrupt output.
+        unless (200..299).cover?(response.status)
+          raise NetworkError,
+                "Unexpected HTTP #{response.status} on download: refusing to write a " \
+                "non-2xx (redirect) response as file content."
+        end
+        sink.nil? ? response.body : nil
+      end
+
+      # Build a request object without sending it (used by the uploader, which
+      # supplies a streamed multipart body).
+      def build_request(method, url, headers: {}, body_stream: nil, content_length: nil)
+        Request.new(
+          method: method, url: url, headers: headers,
+          body_stream: body_stream, content_length: content_length
+        )
+      end
+
+      private
+
+      def build_url(path, query)
+        url = "#{@config.base_url}/#{path.sub(%r{\A/+}, "")}"
+        url = "#{url}?#{URI.encode_www_form(query)}" if query && !query.empty?
+        url
+      end
+
+      def decode_safe(response)
+        raw = response.body
+        return {} if raw.nil? || raw.empty?
+
+        decoded = JSON.parse(raw)
+        decoded.is_a?(Hash) ? decoded : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      def fallback_message(response)
+        response.reason.to_s.empty? ? "Request failed" : response.reason
+      end
+
+      def backoff(attempt, retry_after = nil)
+        retry_secs = parse_retry_after(retry_after)
+        seconds =
+          if retry_secs&.positive?
+            # Honor a positive Retry-After (capped so a hostile value can't stall
+            # us for hours). Not jittered: the server asked for this exact delay.
+            [MAX_RETRY_AFTER_SECONDS, retry_secs.to_f].min
+          else
+            # A zero/absent Retry-After falls through to jittered exponential
+            # backoff so we never retry-storm with no delay.
+            jitter([MAX_BACKOFF_SECONDS, 0.5 * (2**attempt)].min)
+          end
+        @sleeper.call(seconds)
+      end
+
+      # Parse `Retry-After` (delay-seconds or HTTP-date) into whole seconds.
+      # Returns nil when absent/unparseable; never negative.
+      def parse_retry_after(value)
+        return nil if value.nil? || value.empty?
+
+        begin
+          number = Float(value)
+          # A non-finite value (e.g. "1e400" -> Infinity, "NaN") must not crash:
+          # Float::INFINITY.to_i raises FloatDomainError. Fall through so a hostile
+          # Retry-After can never stall a worker (matches Python's OverflowError guard).
+          return [0, number.to_i].max if number.finite?
+        rescue ArgumentError, TypeError
+          # not a plain number — fall through to the HTTP-date form
+        end
+
+        begin
+          parsed = Time.httpdate(value)
+        rescue ArgumentError
+          return nil
+        end
+        [0, (parsed - Time.now).to_i].max
+      end
+
+      # Add a small upward jitter (0-25%) so correlated clients don't lockstep.
+      def jitter(seconds)
+        seconds + (seconds * 0.25 * @rng.call)
+      end
+
+      def idempotent?(request)
+        return true if IDEMPOTENT_METHODS.include?(request.method)
+
+        !request.headers["Idempotency-Key"].to_s.empty?
+      end
+
+      def user_agent
+        @user_agent ||= "api2convert-ruby/#{Api2Convert::VERSION} ruby/#{RUBY_VERSION}"
+      end
+    end
+  end
+end

data/lib/api2convert/input_type.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  # The kinds of source an input file can be created from (the input `type`
+  # field). A typed reference for building input descriptors by hand, e.g.
+  # `add_input(job_id, { "type" => Api2Convert::InputType::REMOTE, "source" => ... })`.
+  module InputType
+    UPLOAD = "upload"
+    REMOTE = "remote"
+    OUTPUT = "output"
+    INPUT_ID = "input_id"
+    GDRIVE_PICKER = "gdrive_picker"
+    BASE64 = "base64"
+    CLOUD = "cloud"
+  end
+end

data/lib/api2convert/job_status.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  # Well-known job status codes (the `status.code` field).
+  #
+  # The API may introduce further codes; treat any code not listed here as
+  # non-terminal. Use {terminal?} for a raw status string rather than comparing
+  # by hand.
+  module JobStatus
+    CREATED = "created"
+    INCOMPLETE = "incomplete"
+    DOWNLOADING = "downloading"
+    QUEUED = "queued"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELED = "canceled"
+
+    # The finished states — a job in one of these will not change further.
+    TERMINAL = [COMPLETED, FAILED, CANCELED].freeze
+
+    module_function
+
+    # Is the given raw status code terminal? Unknown codes are non-terminal.
+    def terminal?(code)
+      TERMINAL.include?(code)
+    end
+  end
+end