verisec 1.0.0

data/lib/verisec/image.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module VeriSec
+  # An image for a KYC API. The KYC APIs take images as base64 inside the JSON
+  # body; the library makes that base64 from whatever you have:
+  #
+  #   client.face.verify(
+  #     image1: "selfie.jpg",                         # a path (String or Pathname)
+  #     image2: VeriSec::Image.bytes(id_photo_bytes)  # bytes you already hold
+  #   )
+  #
+  # An image field (and each entry of an image list) also takes an open IO
+  # (File, StringIO, an uploaded file), a `data:` URI, base64 you already have,
+  # a {FileInput}, or a String of raw bytes in binary encoding (what
+  # `File.binread` returns). A String that is none of those raises a
+  # {VeriSecError} naming the field, before anything is sent.
+  class Image
+    # Base64 the way the API checks it: whole groups of four, `=` padding only at the end.
+    BASE64 = %r{\A[A-Za-z0-9+/]+={0,2}\z}.freeze
+    # `data:<type>;base64,<data>`
+    DATA_URI = /\Adata:[^,]*;base64,(.*)\z/m.freeze
+
+    # An image from bytes you already hold.
+    #
+    # @param data [String] the file's bytes
+    # @return [Image]
+    def self.bytes(data)
+      new(data)
+    end
+
+    # @return [String] the image's bytes (binary)
+    attr_reader :data
+
+    # @param data [String] the image's bytes
+    def initialize(data)
+      raise TypeError, "VeriSec::Image.bytes needs a String of bytes, not #{data.class}" unless data.is_a?(String)
+
+      @data = data.b.freeze
+    end
+
+    # @return [String] the bytes as plain base64 (no `data:` prefix)
+    def base64
+      [@data].pack("m0")
+    end
+
+    def inspect
+      "#<#{self.class.name} bytes=#{@data.bytesize}>"
+    end
+
+    class << self
+      # Any accepted image input as plain base64.
+      #
+      # @api private
+      # @param value [Object] what the caller passed for the field
+      # @param field [String] the field's name in the API's spelling, for errors ("images[1].data")
+      # @return [String] base64
+      # @raise [VeriSecError] when it is none of the accepted forms
+      def base64_of(value, field)
+        case value
+        when Image then value.base64
+        when FileInput then [value.bytes].pack("m0")
+        when String then string_base64(value, field)
+        when Pathname then [read_file(value.to_path, field)].pack("m0")
+        else
+          if value.respond_to?(:read) then [value.read.to_s.b].pack("m0")
+          elsif value.respond_to?(:to_path) then [read_file(value.to_path, field)].pack("m0")
+          else
+            raise VeriSecError, "#{field}: expected a file path, an IO, VeriSec::Image.bytes(…), a data: URI or " \
+                                "base64, not #{value.nil? ? 'nil' : value.class}."
+          end
+        end
+      end
+
+      # A copy of a request body with every image as base64, following the
+      # operation's image plan (generated from the spec): `fields` hold one
+      # image each (dotted when nested), `lists` are lists of images. In a list
+      # whose entries are objects (an `image_key`), an entry can be the image
+      # itself: it is wrapped as `{image_key => base64}`, `index_key` is set to
+      # the entry's position when left out, and `id_key` to "face-1",
+      # "face-2", … (`item_label`) when left out or empty.
+      #
+      # @api private
+      # @param body [Hash{String => Object}] a wire copy of the parameters ({Util.wire}); changed in place
+      # @param plan [Hash] `fields: [String]`, `lists: [{name:, image_key:, index_key:, id_key:, item_label:}]`
+      # @return [Hash] the body
+      def prepare(body, plan)
+        Array(plan[:fields]).each do |path|
+          value = get(body, path)
+          set(body, path, base64_of(value, path)) unless value.nil?
+        end
+        Array(plan[:lists]).each do |list|
+          items = get(body, list[:name])
+          next unless items.is_a?(Array)
+
+          set(body, list[:name], items.each_with_index.map { |item, index| list_entry(item, index, list) })
+        end
+        body
+      end
+
+      private
+
+      def list_entry(item, index, list)
+        where = "#{list[:name]}[#{index}]"
+        image_key = list[:image_key]
+        return base64_of(item, where) unless image_key
+
+        entry = item.is_a?(Hash) ? item.dup : { image_key => item }
+        entry[image_key] = base64_of(entry[image_key], "#{where}.#{image_key}")
+        index_key = list[:index_key]
+        entry[index_key] = index if index_key && !entry.key?(index_key)
+        id_key = list[:id_key]
+        entry[id_key] = "#{list[:item_label] || 'item'}-#{index + 1}" if id_key && entry[id_key].to_s.empty?
+        entry
+      end
+
+      # A String is a data: URI, a path to an existing file, raw bytes, or base64.
+      def string_base64(value, field)
+        return [value.b].pack("m0") unless value.valid_encoding? # bytes read as text
+
+        text = value.strip
+        uri = DATA_URI.match(text)
+        return uri[1].gsub(/\s+/, "") if uri
+        return [read_file(text, field)].pack("m0") if file?(text)
+        return [value.b].pack("m0") if raw_bytes?(value)
+
+        compact = text.gsub(/\s+/, "")
+        return compact if compact.length >= 16 && (compact.length % 4).zero? && BASE64.match?(compact)
+
+        raise VeriSecError, "#{field}: not a file that exists, a data: URI or base64."
+      end
+
+      # Bytes rather than text: binary encoding (as File.binread returns) with bytes outside ASCII.
+      def raw_bytes?(value)
+        value.encoding == Encoding::BINARY && !value.ascii_only?
+      end
+
+      def file?(text)
+        !text.empty? && !text.include?("\0") && File.file?(text)
+      rescue ArgumentError, EncodingError, SystemCallError
+        false
+      end
+
+      def read_file(path, field)
+        File.binread(path)
+      rescue SystemCallError, IOError, ArgumentError, EncodingError => e
+        raise VeriSecError, "#{field}: cannot read #{Util.shorten(path)} (#{Util.reason(e)})"
+      end
+
+      def get(body, path)
+        path.split(".").reduce(body) { |node, key| node.is_a?(Hash) ? node[key] : nil }
+      end
+
+      def set(body, path, value)
+        *parents, last = path.split(".")
+        node = parents.reduce(body) { |inner, key| inner[key] = inner[key].is_a?(Hash) ? inner[key] : {} }
+        node[last] = value
+      end
+    end
+  end
+end

data/lib/verisec/multipart.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module VeriSec
+  # Builds `multipart/form-data` bodies (RFC 7578) for the image uploads.
+  #
+  # @api private
+  module Multipart
+    module_function
+
+    # @param fields [Array<Array(String, String)>] text fields, as name and value
+    # @param files [Array<Array(String, FileInput)>] file parts, as name and file
+    # @return [Array(String, String)] the body (binary) and its Content-Type
+    def encode(fields, files)
+      boundary = "verisec-#{SecureRandom.hex(16)}"
+      body = String.new(encoding: Encoding::BINARY)
+      files.each do |name, file|
+        body << "--#{boundary}\r\n".b
+        body << %(Content-Disposition: form-data; name="#{quote(name)}"; filename="#{quote(file.filename)}"\r\n).b
+        body << "Content-Type: #{file.content_type}\r\n\r\n".b
+        body << file.bytes << "\r\n".b
+      end
+      fields.each do |name, value|
+        body << "--#{boundary}\r\n".b
+        body << %(Content-Disposition: form-data; name="#{quote(name)}"\r\n\r\n).b
+        body << value.to_s.b << "\r\n".b
+      end
+      body << "--#{boundary}--\r\n".b
+      [body, "multipart/form-data; boundary=#{boundary}"]
+    end
+
+    # Escapes a name for a quoted header parameter, as browsers do.
+    def quote(name)
+      name.to_s.gsub(/["\r\n]/, '"' => "%22", "\r" => "%0D", "\n" => "%0A")
+    end
+  end
+end

data/lib/verisec/resource.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module VeriSec
+  # The API's resources, one class per group of operations
+  # (generated/resources.rb, from the spec).
+  module Resources
+    # Base class of every resource. Its helpers turn a method call into a
+    # request and the answer into a result.
+    class Resource
+      # The header that files a Financial upload under "SDK" in the console's scan logs.
+      SOURCE_HEADER = { "X-VeriSec-Source" => "sdk" }.freeze
+
+      # @api private
+      # @param transport [Transport]
+      def initialize(transport)
+        @transport = transport
+      end
+
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      private
+
+      # A JSON call: the parameters exactly as given, images as base64.
+      #
+      # @param verb [Symbol] :post
+      # @param path [String]
+      # @param params [Hash] the keyword arguments, in the API's spelling
+      # @param type [Class<VeriSecObject>] the answer type
+      # @param envelope [Symbol] :data (KYC) or :object (Financial)
+      # @param images [Hash, nil] where the images sit (see {Image.prepare})
+      def _json(verb, path, params, type, envelope:, images: nil, request_options: nil)
+        body = Util.wire(params)
+        Image.prepare(body, images) if images
+        data, info = @transport.request(verb, path, body: body, envelope: envelope, request_options: request_options)
+        type.construct(data, info)
+      end
+
+      # A Financial read: the image as `multipart/form-data` under `image`, the
+      # other parameters as text fields, and `X-VeriSec-Source: sdk`.
+      def _upload(verb, path, params, type, operation:, envelope:, request_options: nil)
+        fields = Util.wire(params)
+        image = fields.delete("image")
+        raise ArgumentError, "#{operation} needs image: a file path, an IO or a VeriSec::FileInput" if image.nil?
+
+        file = FileInput.wrap(image, "image")
+        text = fields.map { |name, value| [name, value.is_a?(Hash) || value.is_a?(Array) ? JSON.generate(value) : value.to_s] }
+        data, info = @transport.request(verb, path, multipart: [text, [["image", file]]], envelope: envelope,
+                                                    headers: SOURCE_HEADER, request_options: request_options)
+        type.construct(data, info)
+      end
+
+      # A call without a body: path parameters already in `path`, the rest as the query.
+      def _call(verb, path, type, envelope:, query: nil, request_options: nil)
+        data, info = @transport.request(verb, path, query: query && Util.wire(query), envelope: envelope,
+                                                    request_options: request_options)
+        type.construct(data, info)
+      end
+
+      def _segment(value, name)
+        Util.path_segment(value, name)
+      end
+    end
+  end
+end

data/lib/verisec/response_info.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module VeriSec
+  # Where an answer came from. Every result an API call returns has one as
+  # `last_response`:
+  #
+  #   result = client.face.verify(image1: "selfie.jpg", image2: "id-photo.jpg")
+  #   result.last_response.request_id   # => "req_…" (quote it when you contact support)
+  #   result.last_response.warnings     # => [] (notes about the result that are not errors)
+  #   result.last_response.latency_ms   # => 412 (how long the check took on the server)
+  #   result.last_response.status       # => 200
+  #   result.last_response.headers      # => {"content-type" => "application/json", …}
+  #
+  # `warnings` and `latency_ms` come from the KYC envelope; Financial answers
+  # have no warnings and no latency.
+  #
+  # @!attribute [r] status
+  #   @return [Integer] the HTTP status
+  # @!attribute [r] headers
+  #   @return [Hash{String => String}] the response headers, with lower-case names
+  # @!attribute [r] request_id
+  #   @return [String, nil] the envelope's `request_id`, else the `X-Request-Id` header
+  # @!attribute [r] warnings
+  #   @return [Array<String>] the envelope's `warnings` (KYC answers)
+  # @!attribute [r] latency_ms
+  #   @return [Numeric, nil] the envelope's `latency_ms` (KYC answers)
+  ResponseInfo = Struct.new(:status, :headers, :request_id, :warnings, :latency_ms, keyword_init: true) do
+    def inspect
+      "#<VeriSec::ResponseInfo status=#{status} request_id=#{request_id.inspect} warnings=#{warnings.inspect} " \
+        "latency_ms=#{latency_ms.inspect}>"
+    end
+    alias_method :to_s, :inspect
+  end
+end

data/lib/verisec/transport.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+module VeriSec
+  # The HTTP layer every resource uses: authentication, the standard headers,
+  # the KYC envelope, error mapping, and the retry rules that keep a charged
+  # call from running twice. One request per connection and no shared mutable
+  # state but the token cache, so a client can be shared between threads.
+  #
+  # @api private
+  class Transport
+    # Seconds per attempt: a deep cheque read can take up to about 250 s, and a
+    # call cut off by the client may still finish (and be charged) on the server.
+    DEFAULT_TIMEOUT = 300
+    # The longest wait to open a connection (TCP and TLS), whatever the timeout:
+    # a connection that is slower than this is not coming, and as it never
+    # opened, it is retried.
+    CONNECT_TIMEOUT = 30
+    # Retries after the first attempt, only where nothing was charged.
+    DEFAULT_MAX_RETRIES = 2
+    # The longest Retry-After the library waits, in seconds.
+    MAX_RETRY_WAIT = 60
+    # What a single call takes as `request_options:`.
+    REQUEST_OPTIONS = %i[timeout max_retries headers].freeze
+    USER_AGENT = "verisec-ruby/#{VERSION}".freeze
+    TOKEN_PATH = "/v2/oauth/token"
+
+    HTTP_METHODS = {
+      get: Net::HTTP::Get, post: Net::HTTP::Post, put: Net::HTTP::Put, patch: Net::HTTP::Patch,
+      delete: Net::HTTP::Delete
+    }.freeze
+
+    # Failures while opening the connection, before any byte of the request
+    # left: connection refused, DNS failure, host or network unreachable, a
+    # connect timeout. Retrying them can never run (or charge) a call twice.
+    NEVER_SENT = [
+      Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::EADDRNOTAVAIL, Errno::ETIMEDOUT,
+      SocketError, Net::OpenTimeout
+    ].freeze
+    # Waiting for the answer (or writing the request) took too long. The call
+    # may have run, so it is reported, never retried.
+    TIMEOUTS = [Net::ReadTimeout, Net::WriteTimeout, Timeout::Error, Errno::ETIMEDOUT].freeze
+    # The connection failed after the request was (perhaps partly) sent: a
+    # reset, a dropped connection, a broken answer. Reported, never retried.
+    DROPPED = [
+      IOError, SystemCallError, SocketError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError,
+      Net::ProtocolError, Zlib::Error
+    ].freeze
+
+    # Raised inside an attempt when the connection could not be opened (the
+    # original error is its #cause). Only the {NEVER_SENT} failures are worth
+    # another try; a TLS failure, say, is reported without one.
+    class NotConnected < StandardError
+      attr_reader :retryable
+
+      def initialize(retryable)
+        super("not connected")
+        @retryable = retryable
+      end
+    end
+    private_constant :NotConnected
+
+    # @return [String]
+    attr_reader :base_url
+    # @return [Numeric]
+    attr_reader :timeout
+    # @return [Integer]
+    attr_reader :max_retries
+
+    # See {Client#initialize}.
+    def initialize(api_key: nil, client_id: nil, client_secret: nil, base_url: nil, timeout: nil, max_retries: nil)
+      api_key = Util.presence(api_key) || Util.presence(ENV["VERISEC_API_KEY"])
+      raise VeriSecError, "No API key. Pass api_key: or set VERISEC_API_KEY." unless api_key
+
+      @base_url = (Util.presence(base_url) || Util.presence(ENV["VERISEC_BASE_URL"]) || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+      @uri = parse_base_url(@base_url)
+      @timeout = timeout.nil? ? DEFAULT_TIMEOUT : check_timeout(timeout, "timeout")
+      @max_retries = max_retries.nil? ? DEFAULT_MAX_RETRIES : check_retries(max_retries, "max_retries")
+      @credentials = credentials_for(api_key, client_id, client_secret)
+    end
+
+    # Makes one API call. Retries (up to `max_retries`) only when nothing can
+    # have been charged: a connection that never opened, a 429 or a 5xx. A
+    # timeout, or a connection that dropped after the request was sent, is
+    # raised as {APITimeoutError} / {APIConnectionError}, because the call may
+    # have run. A 401 fetches a new live token once and repeats the call.
+    #
+    # @param method [Symbol] the HTTP verb: :get, :post, …
+    # @param path [String] e.g. "/v1/face/verify" (path parameters already encoded)
+    # @param query [Hash, nil] query parameters
+    # @param body [Hash, nil] a JSON body, sent exactly as given (images already base64)
+    # @param multipart [Array(Array, Array), nil] text fields and file parts, see {Multipart.encode}
+    # @param envelope [Symbol] :data (a KYC answer: return its `data`), :object
+    #   (a Financial object: return it as it is) or :raw (the body, no response info)
+    # @param request_options [Hash, nil] see {REQUEST_OPTIONS}
+    # @param headers [Hash{String => String}, nil] the operation's own headers
+    #   (`X-VeriSec-Source: sdk` on uploads); the caller's headers win
+    # @param anonymous [Boolean] send no bearer token (the token endpoint itself)
+    # @return [Array(Object, ResponseInfo)] the result (the envelope's `data` for
+    #   KYC) and where it came from
+    # @raise [APIError, APIConnectionError]
+    def request(method, path, query: nil, body: nil, multipart: nil, envelope: :object, request_options: nil,
+                headers: nil, anonymous: false)
+      options = normalize_options(request_options)
+      max_retries = options.key?(:max_retries) ? check_retries(options[:max_retries], "max_retries") : @max_retries
+      timeout = options.key?(:timeout) ? check_timeout(options[:timeout], "timeout") : @timeout
+      target = request_target(path, query)
+      payload, content_type = encode_body(body, multipart)
+
+      refreshed = false
+      attempt = 0
+      loop do
+        token = anonymous ? nil : @credentials.token
+        sent = build_headers(options, headers, token, content_type)
+        begin
+          raw = perform(method, target, sent, payload, timeout)
+        rescue NotConnected => e
+          if e.retryable && attempt < max_retries
+            sleep_for(retry_delay(attempt, nil))
+            attempt += 1
+            next
+          end
+          raise APIConnectionError.new("Could not connect to #{@base_url}: #{e.cause.message} (#{e.cause.class}). " \
+                                       "The request was not sent."), cause: e.cause
+        rescue *TIMEOUTS
+          raise APITimeoutError, "No answer within #{timeout} s. The call may still have run (and been charged) " \
+                                 "on the server, so it was not sent again."
+        rescue *DROPPED => e
+          raise APIConnectionError, "The connection to #{@base_url} dropped after the request was sent " \
+                                    "(#{e.message}, #{e.class}). The call may have run (and been charged) on the " \
+                                    "server, so it was not sent again."
+        end
+
+        status = raw.code.to_i
+        response_headers = {}
+        raw.each_header { |name, value| response_headers[name] = value }
+        data = Util.parse_body(raw.body)
+        info = response_info(status, response_headers, data)
+
+        if status.between?(200, 299)
+          return [data, info] if envelope == :raw
+
+          return unwrap(data, envelope, status, response_headers, info)
+        end
+        if status == 401 && !anonymous && !refreshed && @credentials.invalidate(token)
+          refreshed = true # a token refresh isn't a retry
+          next
+        end
+        if retryable?(status) && attempt < max_retries
+          sleep_for(retry_delay(attempt, response_headers["retry-after"]))
+          attempt += 1
+          next
+        end
+        raise APIError.from(status, Util.error_body(data), response_headers, info.request_id)
+      end
+    end
+
+    # Seconds to wait before retry number `attempt + 1`: the server's
+    # Retry-After when it sent one (at most {MAX_RETRY_WAIT}), else exponential
+    # backoff `min(0.5 * 2^attempt, 8)` with ±25% jitter.
+    #
+    # @param attempt [Integer] 0 for the first retry
+    # @param retry_after [String, nil] the Retry-After header
+    # @return [Numeric]
+    def retry_delay(attempt, retry_after)
+      told = Util.parse_seconds(retry_after)
+      return [told, MAX_RETRY_WAIT].min if told
+
+      [0.5 * (2**attempt), 8.0].min * (0.75 + (rand * 0.5))
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect} credentials=#{@credentials.inspect}>"
+    end
+
+    private
+
+    # Calls are charged only when they succeed, so a 429 (refused before
+    # running) or a 5xx (the check did not complete) costs nothing.
+    def retryable?(status)
+      status == 429 || status >= 500
+    end
+
+    def credentials_for(api_key, client_id, client_secret)
+      return Auth::SecretKey.new(api_key) unless api_key.start_with?("ak_live_")
+
+      client_id = Util.presence(client_id) || Util.presence(ENV["VERISEC_CLIENT_ID"])
+      client_secret = Util.presence(client_secret) || Util.presence(ENV["VERISEC_CLIENT_SECRET"])
+      unless client_id && client_secret
+        raise VeriSecError, "Live keys (ak_live_…) also need client_id: and client_secret:, " \
+                            "or VERISEC_CLIENT_ID and VERISEC_CLIENT_SECRET."
+      end
+
+      body = { "grant_type" => "client_credentials", "api_key" => api_key, "client_id" => client_id,
+               "client_secret" => client_secret }
+      Auth::ClientCredentials.new do
+        request(:post, TOKEN_PATH, body: body, envelope: :raw, anonymous: true, request_options: { max_retries: 0 }).first
+      end
+    end
+
+    # One attempt: open the connection (a failure there raises NotConnected),
+    # then send the request and read the answer.
+    def perform(method, target, headers, payload, timeout)
+      http = Net::HTTP.new(@uri.hostname, @uri.port)
+      http.use_ssl = @uri.scheme == "https"
+      http.open_timeout = [timeout, CONNECT_TIMEOUT].min
+      http.read_timeout = timeout
+      http.write_timeout = timeout
+      http.max_retries = 0 # net/http would resend idempotent requests itself; the retry rules are ours
+      begin
+        http.start
+      rescue *NEVER_SENT
+        raise NotConnected.new(true)
+      rescue *TIMEOUTS, *DROPPED
+        raise NotConnected.new(false)
+      end
+      begin
+        request = HTTP_METHODS.fetch(method).new(target, headers)
+        request.body = payload unless payload.nil?
+        http.request(request)
+      ensure
+        http.finish if http.started?
+      end
+    end
+
+    def unwrap(data, envelope, status, headers, info)
+      unless data.is_a?(Hash)
+        raise APIError.new("The API answered #{status} with a body that is not a JSON object.",
+                           status: status, request_id: info.request_id, headers: headers)
+      end
+      return [data, info] unless envelope == :data
+      # a 2xx always carries a result; `ok: false` here is a handled problem
+      raise APIError.from(status, Util.error_body(data), headers, info.request_id) if data["ok"] == false
+
+      [data["data"], info]
+    end
+
+    def response_info(status, headers, data)
+      envelope = data.is_a?(Hash) ? data : {}
+      request_id = envelope["request_id"].is_a?(String) ? envelope["request_id"] : headers["x-request-id"]
+      warnings = envelope["warnings"].is_a?(Array) ? envelope["warnings"] : []
+      latency = envelope["latency_ms"].is_a?(Numeric) ? envelope["latency_ms"] : nil
+      ResponseInfo.new(status: status, headers: headers, request_id: request_id, warnings: warnings, latency_ms: latency)
+    end
+
+    # The standard headers, then the operation's, then the caller's, then the
+    # ones nobody may change. Names match case-insensitively, so a later one
+    # replaces an earlier one whatever its spelling.
+    def build_headers(options, operation_headers, token, content_type)
+      headers = {}
+      put_header(headers, "Accept", "application/json")
+      put_header(headers, "User-Agent", USER_AGENT)
+      (operation_headers || {}).each { |name, value| put_header(headers, name, value) }
+      options.fetch(:headers, {}).each { |name, value| put_header(headers, name, value) }
+      put_header(headers, "Authorization", "Bearer #{token}") if token
+      put_header(headers, "Content-Type", content_type) if content_type
+      headers
+    end
+
+    def put_header(headers, name, value)
+      name = name.to_s
+      headers.delete_if { |existing, _| existing.casecmp?(name) }
+      headers[name] = value.to_s unless value.nil?
+    end
+
+    def encode_body(body, multipart)
+      return Multipart.encode(*multipart) if multipart
+      return [JSON.generate(body), "application/json"] unless body.nil?
+
+      [nil, nil]
+    end
+
+    def request_target(path, query)
+      target = "#{@uri.path.sub(%r{/+\z}, '')}#{path}"
+      search = query.nil? || query.empty? ? "" : Util.query_string(query)
+      search.empty? ? target : "#{target}?#{search}"
+    end
+
+    def sleep_for(seconds)
+      sleep(seconds) if seconds.positive?
+    end
+
+    def normalize_options(options)
+      return {} if options.nil?
+      raise ArgumentError, "request_options must be a Hash, not #{options.class}" unless options.is_a?(Hash)
+
+      options.each_with_object({}) do |(key, value), out|
+        name = key.to_s.to_sym
+        unless REQUEST_OPTIONS.include?(name)
+          raise ArgumentError, "Unknown request option #{key.inspect}; expected one of #{REQUEST_OPTIONS.join(', ')}."
+        end
+        if name == :headers && !(value.nil? || value.is_a?(Hash))
+          raise ArgumentError, "request_options[:headers] must be a Hash"
+        end
+
+        out[name] = value unless value.nil?
+      end
+    end
+
+    def parse_base_url(url)
+      uri = URI.parse(url)
+      unless %w[http https].include?(uri.scheme) && uri.hostname && !uri.hostname.empty?
+        raise ArgumentError, "base_url must be an http(s) URL, not #{url.inspect}"
+      end
+
+      uri
+    rescue URI::InvalidURIError
+      raise ArgumentError, "base_url must be an http(s) URL, not #{url.inspect}"
+    end
+
+    def check_timeout(value, name)
+      return value if value.is_a?(Numeric) && value.positive?
+
+      raise ArgumentError, "#{name} must be a positive number of seconds, not #{value.inspect}"
+    end
+
+    def check_retries(value, name)
+      return value if value.is_a?(Integer) && value >= 0
+
+      raise ArgumentError, "#{name} must be an Integer of 0 or more, not #{value.inspect}"
+    end
+  end
+end