flashpi 0.1.0

data/lib/flashpi/internal/engine.rb

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+module Flashpi
+  module Internal
+    # Requests to the Flashpi API: retries, timeouts, idempotency and typed errors.
+    #
+    # @api private
+    class Engine
+      USER_AGENT = "flashpi-ruby/#{VERSION}".freeze
+
+      # Longest `Retry-After`, in seconds, the SDK waits for by itself; longer waits (daily quotas)
+      # are raised.
+      MAX_RETRY_AFTER = 60
+
+      INITIAL_RETRY_DELAY = 0.5
+      MAX_RETRY_DELAY = 8.0
+      # Waits between checks on an earlier attempt that the API is still running.
+      IN_PROGRESS_FIRST_WAIT = 1.0
+      IN_PROGRESS_MAX_WAIT = 5.0
+      IN_PROGRESS = "idempotency_key_in_progress"
+
+      OPTION_NAMES = %i[idempotency_key timeout max_retries language correlation_id extra_headers].freeze
+
+      # What every attempt of one call shares, resolved before the first one is sent. It is a local
+      # of the methods that raise the call's errors, and error trackers can record those locals: the
+      # body (possibly a .p12 and its password) is kept in a Secret, and `inspect` shows the URL only.
+      class Call
+        attr_reader :options, :max_retries, :timeout, :url, :target, :idempotency_key
+
+        def initialize(options:, max_retries:, timeout:, url:, target:, idempotency_key:, content:)
+          @options = options
+          @max_retries = max_retries
+          @timeout = timeout
+          @url = url
+          @target = target
+          @idempotency_key = idempotency_key
+          @content = Secret.new(content)
+          freeze
+        end
+
+        # @return [String, nil] the body every attempt sends
+        def content
+          @content.reveal
+        end
+
+        def inspect
+          "#<#{self.class.name} #{url}>"
+        end
+      end
+      private_constant :Call
+
+      # @return [ClientConfig]
+      attr_reader :config
+      # @return [Transport] how attempts are sent (tests replace it)
+      attr_accessor :transport
+      # @return [#now, #sleep, #rand] the clock of retries and waits (tests replace it)
+      attr_accessor :clock
+
+      def initialize(config, transport, clock = Clock)
+        @config = config
+        @transport = transport
+        @clock = clock
+        @base_path = URI.parse(config.base_url).path.to_s.sub(%r{/+\z}, "")
+      end
+
+      # Sends a request with its retries and recoveries.
+      #
+      # @param spec [RequestSpec]
+      # @return [Flashpi::APIResponse]
+      def request(spec)
+        call = prepare(spec)
+        started = clock.now
+        attempt = retries = waits = 0
+        # Whether an earlier attempt may have reached the API without its answer reaching us (a
+        # network error, a timeout, or a 5xx from a proxy). Only then can a 409
+        # idempotency_key_in_progress be this call's own attempt still running.
+        unanswered = false
+
+        loop do
+          failure = attempt_once(spec, call)
+          return failure if failure.is_a?(APIResponse)
+
+          # The error of this attempt: an APIError or an APIConnectionError.
+          failure.idempotency_key = call.idempotency_key
+
+          if attempt.positive? && failure.is_a?(APIError)
+            document_id = recoverable_document(spec, failure)
+            return recover_document(call, document_id) if document_id
+            # A DELETE retried after a lost answer finds the resource already gone.
+            return deleted(failure) if spec.http_method == :delete && failure.status == 404
+
+            # This call's earlier attempt is still running on the API (a sync issue whose answer
+            # was lost): wait for it with the same key while the call has time left. These checks
+            # do not count as retries; once the time is up, the normal retry rules apply.
+            if unanswered && failure.status == 409 && failure.code == IN_PROGRESS
+              wait = [IN_PROGRESS_FIRST_WAIT * (2**[waits, 16].min), IN_PROGRESS_MAX_WAIT].min
+              if clock.now + wait - started <= call.timeout
+                waits += 1
+                attempt += 1
+                clock.sleep(wait)
+                next
+              end
+            end
+          end
+
+          unanswered = true if unanswered?(failure)
+          delay = retry_delay(failure, retries)
+          raise failure if delay.nil? || retries >= call.max_retries
+
+          retries += 1
+          attempt += 1
+          clock.sleep(delay)
+        end
+      end
+
+      private
+
+      # One attempt: its APIResponse, or the APIError or APIConnectionError to handle. Any other
+      # Flashpi::Error is raised with the call's Idempotency-Key.
+      def attempt_once(spec, call)
+        raw = transport.perform(attempt_of(spec, call))
+        read_response(raw, spec.response_type)
+      rescue APIConnectionError => e
+        e
+      rescue Error => e
+        e.idempotency_key = call.idempotency_key
+        raise
+      end
+
+      # Whether the attempt may have reached the API without its answer reaching us: a network
+      # error, a timeout, or a 5xx from a proxy (no Problem Details).
+      def unanswered?(failure)
+        failure.is_a?(APIConnectionError) || (failure.is_a?(APIError) && failure.status >= 500 && failure.problem.nil?)
+      end
+
+      # Checks the options and builds what the attempts share. Raises before anything is sent.
+      def prepare(spec)
+        options = check_options(spec.options)
+        max_retries = if options[:max_retries].nil?
+                        config.max_retries
+                      else
+                        Validate.retries!("max_retries",
+                                          options[:max_retries])
+                      end
+        timeout = options[:timeout].nil? ? config.timeout : Validate.timeout!("timeout", options[:timeout])
+        target = build_target(spec.path, spec.query)
+        longest = [spec.min_timeout, timeout].max
+        Call.new(
+          options:,
+          max_retries:,
+          timeout: [longest, Validate::MAX_TIMEOUT].min,
+          url: config.base_url.sub(%r{/+\z}, "") + target,
+          target: @base_path + target,
+          idempotency_key: idempotency_key_of(spec.http_method, options),
+          # Serialized once: every attempt sends the same bytes under the same Idempotency-Key,
+          # even when the caller changes the body meanwhile.
+          content: spec.multipart ? spec.multipart.content : body_content(spec)
+        )
+      end
+
+      def body_content(spec)
+        spec.body.nil? ? nil : JSONText.encode(spec.body)
+      end
+
+      def attempt_of(spec, call)
+        Attempt.new(
+          http_method: spec.http_method,
+          url: call.url,
+          target: call.target,
+          headers: build_headers(spec, call),
+          content: call.content,
+          timeout: call.timeout,
+          response_type: spec.response_type
+        )
+      end
+
+      # Reads the document an earlier attempt of the call created. A failure to read it keeps the
+      # call's key on the error, so trying again later with that key returns the document instead
+      # of issuing another.
+      def recover_document(call, document_id)
+        options = call.options.except(:idempotency_key)
+        request(RequestSpec.new(http_method: :get, path: Path.of("/v1/documents/{}", document_id), options:))
+      rescue Error => e
+        e.idempotency_key = call.idempotency_key
+        raise
+      end
+
+      # Seconds to wait before retrying, or nil when the failure must not be retried.
+      #
+      # Retried: network errors and timeouts, 408, 429 and 5xx except 501 (with a `Retry-After` of
+      # {MAX_RETRY_AFTER} or less), and 409 `idempotency_key_in_progress` (an attempt with the
+      # same key is still running). POSTs are safe to retry because they keep their
+      # Idempotency-Key.
+      def retry_delay(failure, retries)
+        return backoff(retries) if failure.is_a?(APIConnectionError)
+        return nil unless failure.is_a?(APIError)
+
+        status = failure.status
+        return failure.code == IN_PROGRESS ? [IN_PROGRESS_FIRST_WAIT, backoff(retries)].max : nil if status == 409
+
+        transient = [408, 429].include?(status) || (status >= 500 && status != 501)
+        # The shared demo certificate is missing: no retry within seconds will fix that.
+        return nil if !transient || failure.code == "demo_issuer_unavailable"
+
+        retry_after = failure.retry_after
+        return backoff(retries) if retry_after.nil?
+
+        retry_after <= MAX_RETRY_AFTER ? retry_after.to_f : nil
+      end
+
+      # Exponential backoff from 0.5 s up to 8 s, minus up to 25 % of jitter.
+      def backoff(retries)
+        delay = [INITIAL_RETRY_DELAY * (2**[retries, 16].min), MAX_RETRY_DELAY].min
+        (delay * (1 - (clock.rand * 0.25))).round(3).to_f
+      end
+
+      # The id of the document an earlier attempt of this call created, if the answer shows one.
+      def recoverable_document(spec, failure)
+        return nil unless spec.recover_document && failure.status == 422 && failure.code == "idempotency_key_reused"
+
+        document_id = (failure.problem || {})[:documentId]
+        document_id.is_a?(String) && !document_id.empty? ? document_id : nil
+      end
+
+      # The result of a DELETE whose resource is gone: a 204 with the 404's headers.
+      def deleted(failure)
+        dropped = %w[content-length content-type content-encoding transfer-encoding]
+        headers = failure.headers.except(*dropped)
+        APIResponse.new(data: nil, status: 204, headers:, request_id: failure.request_id)
+      end
+
+      # The caller's options with the values that become headers checked and trimmed, so the
+      # attempts, the errors and a recovered read all use the same ones.
+      def check_options(options)
+        unknown = options.keys - OPTION_NAMES
+        unless unknown.empty?
+          raise ArgumentError, "Unknown request options: #{unknown.map(&:inspect).join(", ")}. The options are " \
+                               "#{OPTION_NAMES.join(", ")}; bodies and list filters go in a Hash before them"
+        end
+
+        checked = options.dup
+        unless options[:extra_headers].nil?
+          checked[:extra_headers] =
+            Validate.headers!("extra_headers", options[:extra_headers])
+        end
+        %i[idempotency_key correlation_id].each do |name|
+          checked[name] = Validate.header_value!(name.to_s, options[name]) unless options[name].nil?
+        end
+        checked[:language] = language("language", options[:language]) unless options[:language].nil?
+        checked
+      end
+
+      def language(label, value)
+        Validate.header_value!(label, value.is_a?(Symbol) ? value.to_s : value)
+      end
+
+      # The caller's Idempotency-Key of a POST (option or header), or a new one.
+      def idempotency_key_of(http_method, options)
+        return nil unless http_method == :post
+        return options[:idempotency_key] unless options[:idempotency_key].nil?
+
+        # The last spelling wins, as in build_headers.
+        header = nil
+        (options[:extra_headers] || {}).each { |name, value| header = value if name.downcase == "idempotency-key" }
+        header || SecureRandom.uuid
+      end
+
+      # The path and query of a request, after the base URL. Query values that are nil are left
+      # out.
+      def build_target(path, query)
+        pairs = (query || {}).filter_map do |name, value|
+          [query_name(name), query_value(value)] unless value.nil?
+        end #: Array[[String, String]]
+        search = URI.encode_www_form(pairs)
+        search.empty? ? path : "#{path}?#{search}"
+      end
+
+      def query_name(name)
+        return name.to_s if name.is_a?(Symbol) || name.is_a?(String)
+
+        raise TypeError, "Filter names must be Strings or Symbols, not #{name.class}"
+      end
+
+      def query_value(value)
+        case value
+        when true then "true"
+        when false then "false"
+        when String, Symbol then query_text(value.to_s)
+        when Integer then value.to_s
+        when Float
+          raise ArgumentError, "A filter cannot be NaN or infinite" unless value.finite?
+
+          value.to_s
+        when Date then value.iso8601
+        else raise TypeError, "Filter values must be Strings, numbers, booleans or Dates, not #{value.class}"
+        end
+      end
+
+      # A filter as UTF-8 text, as the API reads the query.
+      def query_text(value)
+        text = Validate.utf8(value)
+        raise ArgumentError, "A filter must be valid UTF-8 text" if text.nil?
+
+        text
+      end
+
+      # The headers of an attempt, by lowercase name, from the lowest priority to the highest:
+      # client language, client headers, request language, request headers, then the SDK's own.
+      def build_headers(spec, call)
+        headers = { "accept" => spec.accept, "user-agent" => USER_AGENT }
+        language = config.language
+        headers["accept-language"] = language if language && !language.empty?
+        config.default_headers.each { |name, value| headers[name.downcase] = value }
+        language = call.options[:language]
+        headers["accept-language"] = language if language && !language.empty?
+        (call.options[:extra_headers] || {}).each { |name, value| headers[name.downcase] = value }
+        headers["x-correlation-id"] = call.options[:correlation_id] unless call.options[:correlation_id].nil?
+        headers["idempotency-key"] = call.idempotency_key unless call.idempotency_key.nil?
+        if spec.multipart
+          headers["content-type"] = spec.multipart.content_type
+        elsif !spec.body.nil?
+          headers["content-type"] = "application/json"
+        end
+        headers["authorization"] = "Bearer #{config.api_key}"
+        headers
+      end
+
+      # The data of a successful answer, or the APIError of an error status.
+      def read_response(raw, response_type)
+        return Problems.error(raw.status, raw.headers, JSONText.decode(raw.body)) unless (200..299).cover?(raw.status)
+
+        APIResponse.new(
+          data: read_data(raw, response_type),
+          status: raw.status,
+          headers: raw.headers,
+          request_id: raw.headers["x-request-id"]
+        )
+      end
+
+      def read_data(raw, response_type)
+        return raw.body if response_type == :bytes
+
+        text = JSONText.decode(raw.body)
+        return text if response_type == :text
+        return nil if response_type == :none || raw.status == 204 || text.empty?
+
+        begin
+          JSONText.parse(text)
+        rescue JSONText::Invalid
+          raise Error, "The API answered #{raw.status} with a body that is not JSON"
+        end
+      end
+    end
+  end
+end

data/lib/flashpi/internal/json_text.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Flashpi
+  module Internal
+    # JSON in and out: request bodies serialized once, answers parsed with Symbol keys.
+    #
+    # @api private
+    module JSONText
+      # A body that is not JSON.
+      class Invalid < StandardError; end
+
+      MAX_NESTING = 512
+
+      module_function
+
+      # Compact UTF-8 JSON of a request body, like `JSON.stringify`.
+      #
+      # The body may hold Hashes (String, Symbol or Integer keys), Arrays, Strings, Symbols,
+      # Integers, finite Floats, true, false and nil. Anything else is refused before anything is
+      # sent: amounts and dates are text in the Flashpi API.
+      #
+      # @return [String]
+      # @raise [TypeError] for a value JSON has no counterpart for
+      # @raise [ArgumentError] for NaN or infinite numbers, text that is not valid UTF-8, a key
+      #   given twice or a Hash or Array that contains itself
+      def encode(body)
+        JSON.generate(plain(body, {}), max_nesting: false)
+      end
+
+      # Parses JSON text with Symbol keys.
+      #
+      # @return [Object]
+      # @raise [Invalid] when the text is not JSON
+      def parse(text)
+        JSON.parse(text, symbolize_names: true, max_nesting: MAX_NESTING)
+      rescue JSON::ParserError, EncodingError, ArgumentError => e
+        raise Invalid, e.class.name
+      end
+
+      # UTF-8 text from bytes, with invalid sequences replaced (like the Node SDK's TextDecoder).
+      #
+      # @return [String]
+      def decode(bytes)
+        bytes.dup.force_encoding(Encoding::UTF_8).scrub("�")
+      end
+
+      # @api private
+      def plain(value, seen)
+        case value
+        when Hash then plain_hash(value, seen)
+        when Array then nested(value, seen) { value.map { |item| plain(item, seen) } }
+        when String then text(value)
+        when Symbol then text(value.to_s)
+        when Integer, true, false, nil then value
+        when Float
+          raise ArgumentError, "The body has a number JSON cannot hold (NaN or infinite)" unless value.finite?
+
+          value
+        else
+          raise TypeError, "The body must hold only Hashes, Arrays, Strings, numbers, booleans and nil, " \
+                           "not #{value.class} (amounts and dates are Strings)"
+        end
+      end
+
+      # @api private
+      def plain_hash(hash, seen)
+        nested(hash, seen) do
+          result = {} #: Hash[String, untyped]
+          hash.each do |key, item|
+            name = key_text(key)
+            raise ArgumentError, "The body has the key #{name.inspect} twice" if result.key?(name)
+
+            result[name] = plain(item, seen)
+          end
+          result
+        end
+      end
+
+      # @api private
+      def key_text(key)
+        case key
+        when String then text(key)
+        when Symbol, Integer then text(key.to_s)
+        else raise TypeError, "The keys of the body must be Strings or Symbols, not #{key.class}"
+        end
+      end
+
+      # @api private
+      def nested(container, seen)
+        id = container.object_id
+        raise ArgumentError, "The body contains itself" if seen.key?(id)
+
+        seen[id] = true
+        result = yield
+        seen.delete(id)
+        result
+      end
+
+      # @api private
+      def text(value)
+        utf8 = Validate.utf8(value)
+        raise ArgumentError, "The body has text that is not valid UTF-8" if utf8.nil?
+
+        utf8
+      end
+    end
+  end
+end

data/lib/flashpi/internal/multipart.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Flashpi
+  module Internal
+    # The multipart/form-data body of a .p12 upload, for `issuers.certificates.upload` and
+    # `issuer_onboardings.create`: a `password` field, then a `file` part.
+    #
+    # It is encoded once, so every retry sends the same bytes (an IO could not be read twice), and
+    # kept in a {Secret}: its `inspect` lists only the part names, never the .p12 or its password.
+    #
+    # @api private
+    class Multipart
+      # Largest .p12 the API accepts (413 `payload_too_large` above it).
+      MAX_CERTIFICATE_BYTES = 1_048_576
+      DEFAULT_FILENAME = "certificate.p12"
+      CONTENT_TYPE = "application/x-pkcs12"
+      PIECE = 65_536
+
+      # @return [String]
+      attr_reader :content_type
+
+      # The body of a certificate upload: `{ file:, password:, filename: }`.
+      #
+      # Raises before anything is sent: Flashpi::Error for a password that is not a String, an
+      # empty file or one over 1 MiB; TypeError for an upload that is not a Hash, a file that is
+      # neither a String of bytes nor an IO, or a filename that is not a String. Error trackers
+      # can record the local variables of the method that raises, so the errors are raised by
+      # {refuse!}, whose frame holds neither the .p12 nor its password.
+      #
+      # @param upload [Hash]
+      # @return [Multipart]
+      def self.certificate(upload)
+        refuse!(TypeError, "The certificate upload must be a Hash with file and password") unless upload.is_a?(Hash)
+
+        password = member(upload, :password)
+        refuse!(Error, "The certificate password must be a String") unless password.is_a?(String)
+        # Sent as UTF-8 text, as the API reads it (a password in another encoding would not match).
+        password = Validate.utf8(password) || refuse!(ArgumentError, "The certificate password must be valid text")
+
+        filename = member(upload, :filename) || DEFAULT_FILENAME
+        refuse!(TypeError, "The certificate filename must be a String") unless filename.is_a?(String)
+        filename = Validate.utf8(filename) || refuse!(ArgumentError, "The certificate filename must be valid text")
+
+        new(password, read(member(upload, :file)), filename)
+      end
+
+      # @api private
+      def self.member(upload, name)
+        upload.key?(name) ? upload[name] : upload[name.to_s]
+      end
+
+      # The bytes of the file: a String as it is, an IO read to its end in pieces, up to one byte
+      # past the largest certificate, so a big or wrong file is refused without loading it whole.
+      #
+      # @api private
+      def self.read(file)
+        content = file.is_a?(String) ? file.b : read_io(file)
+        refuse!(Error, "The certificate file is empty") if content.empty?
+        if content.bytesize > MAX_CERTIFICATE_BYTES
+          refuse!(Error, "The certificate file has more than #{MAX_CERTIFICATE_BYTES} bytes, the most the API accepts")
+        end
+        content
+      end
+
+      # @api private
+      def self.read_io(file)
+        unless file.respond_to?(:read)
+          refuse!(TypeError,
+                  "The certificate file must be a String of bytes or an IO opened in binary mode, not #{file.class}")
+        end
+
+        content = String.new(encoding: Encoding::BINARY)
+        while content.bytesize <= MAX_CERTIFICATE_BYTES
+          chunk = read_piece(file, [PIECE, MAX_CERTIFICATE_BYTES + 1 - content.bytesize].min)
+          break if chunk.nil?
+
+          unless chunk.is_a?(String)
+            refuse!(TypeError,
+                    "The read method of the certificate file returned #{chunk.class}, not a String")
+          end
+          break if chunk.empty?
+
+          content << chunk.b
+        end
+        content
+      end
+
+      # One read of the file. A failure of the file's own read (a broken gzip, a reset socket) is then
+      # raised with this frame on top, which holds no bytes of the .p12.
+      #
+      # @api private
+      def self.read_piece(file, length)
+        file.read(length)
+      end
+
+      # Raises from a frame that holds only the error.
+      #
+      # @api private
+      def self.refuse!(error, message)
+        raise error, message
+      end
+
+      def initialize(password, content, filename)
+        boundary = "flashpi-#{SecureRandom.hex(16)}"
+        boundary = "flashpi-#{SecureRandom.hex(16)}" while content.include?(boundary) || password.b.include?(boundary)
+        @content_type = "multipart/form-data; boundary=#{boundary}"
+        @body = Secret.new(encode(boundary, password, content, filename).freeze)
+        freeze
+      end
+
+      # @return [String] the encoded body
+      def content
+        @body.reveal
+      end
+
+      # Only the part names: the values are a .p12 and its password.
+      def inspect
+        "#<#{self.class.name} fields=[\"password\"] files=[\"file\"]>"
+      end
+
+      private
+
+      def encode(boundary, password, content, filename)
+        body = String.new(encoding: Encoding::BINARY)
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"password\"\r\n\r\n"
+        body << password.b << "\r\n"
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"file\"; filename=\"#{escape(filename)}\"\r\n"
+        body << "Content-Type: #{CONTENT_TYPE}\r\n\r\n"
+        body << content << "\r\n"
+        body << "--#{boundary}--\r\n"
+      end
+
+      # As browsers write a file name (WHATWG): quotes and line breaks percent-encoded.
+      def escape(filename)
+        filename.b.gsub("\"", "%22").gsub("\r", "%0D").gsub("\n", "%0A")
+      end
+    end
+  end
+end