flashpi 0.1.0

data/lib/flashpi/internal/problems.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Flashpi
+  module Internal
+    # Reading the error answers of the API (RFC 9457 Problem Details) and their Retry-After.
+    #
+    # @api private
+    module Problems
+      # The error class of each status; other 5xx are InternalServerError, the rest APIError.
+      ERROR_CLASSES = {
+        400 => BadRequestError,
+        401 => AuthenticationError,
+        403 => PermissionDeniedError,
+        404 => NotFoundError,
+        409 => ConflictError,
+        422 => UnprocessableEntityError,
+        429 => RateLimitError
+      }.freeze
+
+      DELTA_SECONDS = /\A[0-9]+\z/
+      # Longer digit strings are past any useful wait.
+      MAX_DELTA_DIGITS = 18
+      MAX_DELTA = 1_000_000_000_000_000_000
+      TIME_ZONE = /(?:Z|[+-][0-9]{2}(?::?[0-9]{2})?)\z/i
+
+      module_function
+
+      # The error that matches the status of an answer.
+      #
+      # @param status [Integer]
+      # @param headers [Hash{String => String}]
+      # @param body_text [String]
+      # @return [Flashpi::APIError]
+      def error(status, headers, body_text)
+        error_class = ERROR_CLASSES.fetch(status) { status >= 500 ? InternalServerError : APIError }
+        error_class.new(status, headers, parse(body_text), body_text)
+      end
+
+      # The Problem Details of a body: a JSON object whose `code` is a String, or nil (an answer
+      # from the edge, such as a CDN or a firewall, is not one).
+      #
+      # @return [Hash{Symbol => Object}, nil]
+      def parse(body_text)
+        return nil if body_text.empty?
+
+        parsed = JSONText.parse(body_text)
+        parsed.is_a?(Hash) && parsed[:code].is_a?(String) ? parsed : nil
+      rescue JSONText::Invalid
+        nil
+      end
+
+      # The message of an error answer.
+      #
+      # @return [String]
+      def message(status, problem, body_text)
+        if problem
+          detail = text(problem[:detail]) || text(problem[:title])
+          return detail ? "#{status} #{problem[:code]}: #{detail}" : "#{status} #{problem[:code]}"
+        end
+        excerpt = body_text.split(/[[:space:]]+/).reject(&:empty?).join(" ")[0, 200] || ""
+        excerpt.empty? ? "#{status} (no response body)" : "#{status} #{excerpt}"
+      end
+
+      # @return [String, nil] the value when it is a String
+      def text(value)
+        value.is_a?(String) ? value : nil
+      end
+
+      # Seconds from a `Retry-After` value (delta-seconds or an HTTP date), or nil.
+      #
+      # @param value [String, nil]
+      # @param now [Float] the current Unix time in seconds
+      # @return [Integer, nil]
+      def retry_after(value, now = Time.now.to_f)
+        return nil unless value.is_a?(String)
+
+        trimmed = value.strip
+        if DELTA_SECONDS.match?(trimmed)
+          return trimmed.length <= MAX_DELTA_DIGITS ? trimmed.to_i : MAX_DELTA
+        end
+
+        moment = date(trimmed)
+        moment && [0, (moment - now).ceil].max
+      end
+
+      # Unix seconds of an HTTP date (or an ISO 8601 one, UTC when it has no zone), or nil.
+      #
+      # @return [Float, nil]
+      def date(value)
+        Time.httpdate(value).to_f
+      rescue ArgumentError
+        begin
+          Time.rfc2822(value).to_f
+        rescue ArgumentError
+          iso8601(value)
+        end
+      end
+
+      # @return [Float, nil]
+      def iso8601(value)
+        if /\A[0-9]{4}-[0-9]{2}-[0-9]{2}\z/.match?(value)
+          parts = value.split("-").map(&:to_i)
+          return Time.utc(parts.fetch(0), parts.fetch(1), parts.fetch(2)).to_f
+        end
+        Time.iso8601(TIME_ZONE.match?(value) ? value : "#{value}Z").to_f
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/flashpi/internal/request.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Flashpi
+  module Internal
+    # The settings of a client that the requests need. The API key is kept in a {Secret}.
+    #
+    # @api private
+    class ClientConfig
+      attr_reader :base_url, :timeout, :max_retries, :language, :default_headers
+
+      def initialize(api_key:, base_url:, timeout:, max_retries:, language:, default_headers:)
+        @api_key = Secret.new(api_key)
+        @base_url = base_url
+        @timeout = timeout
+        @max_retries = max_retries
+        @language = language
+        @default_headers = default_headers.freeze
+        freeze
+      end
+
+      # @return [String]
+      def api_key
+        @api_key.reveal
+      end
+
+      # Never the API key.
+      def inspect
+        "#<#{self.class.name} base_url=#{base_url.inspect} timeout=#{timeout} max_retries=#{max_retries}>"
+      end
+    end
+
+    # One API operation, as the resources declare it.
+    #
+    # @api private
+    class RequestSpec
+      # @return [Symbol] :get, :post, :patch or :delete
+      attr_reader :http_method
+      # @return [String] the path, built with {Path.of} when it carries ids
+      attr_reader :path
+      # @return [Hash, nil] query parameters; nil values are left out
+      attr_reader :query
+      # @return [Object] a JSON body, serialized once for every attempt; nil sends no body
+      attr_reader :body
+      # @return [Multipart, nil] a multipart body, instead of `body`
+      attr_reader :multipart
+      # @return [String] the Accept header
+      attr_reader :accept
+      # @return [Symbol] how to read a successful answer: :json, :text, :bytes or :none
+      attr_reader :response_type
+      # @return [Hash{Symbol => Object}] the caller's options
+      attr_reader :options
+      # @return [Float] a floor, in seconds, for the timeout of requests the API holds open
+      attr_reader :min_timeout
+      # @return [Boolean] for document POSTs: return the document an earlier attempt created
+      attr_reader :recover_document
+
+      def initialize(http_method:, path:, query: nil, body: nil, multipart: nil, accept: "application/json",
+                     response_type: :json, options: {}, min_timeout: 0.0, recover_document: false)
+        @http_method = http_method
+        @path = path
+        @query = query
+        @body = body
+        @multipart = multipart
+        @accept = accept
+        @response_type = response_type
+        @options = options
+        @min_timeout = min_timeout
+        @recover_document = recover_document
+        freeze
+      end
+
+      # The same request with other query parameters (the next page of a list).
+      #
+      # @return [RequestSpec]
+      def with_query(query)
+        RequestSpec.new(http_method:, path:, query:, body:, multipart:, accept:, response_type:, options:,
+                        min_timeout:, recover_document:)
+      end
+
+      def inspect
+        "#<#{self.class.name} #{http_method.to_s.upcase} #{path}>"
+      end
+    end
+
+    # One attempt of a call: what the transport sends.
+    #
+    # @api private
+    class Attempt
+      attr_reader :http_method, :url, :target, :timeout, :response_type
+
+      # @param http_method [Symbol]
+      # @param url [String] the whole URL, for messages
+      # @param target [String] the path and query sent in the request line
+      # @param headers [Hash{String => String}] by lowercase name; they carry the API key
+      # @param content [String, nil] the body
+      # @param timeout [Float] seconds the attempt may take
+      # @param response_type [Symbol]
+      def initialize(http_method:, url:, target:, headers:, content:, timeout:, response_type:)
+        @http_method = http_method
+        @url = url
+        @target = target
+        @headers = Secret.new(headers.freeze)
+        @content = Secret.new(content)
+        @timeout = timeout
+        @response_type = response_type
+        freeze
+      end
+
+      # @return [String, nil] the body, which may be a .p12 and its password
+      def content
+        @content.reveal
+      end
+
+      # @return [Hash{String => String}] the headers, with the API key
+      def headers
+        @headers.reveal
+      end
+
+      # @return [String] the method in capitals
+      def verb
+        http_method.to_s.upcase
+      end
+
+      def inspect
+        "#<#{self.class.name} #{verb} #{url}>"
+      end
+    end
+
+    # The answer of an attempt, as the transport read it.
+    #
+    # @api private
+    class RawResponse
+      attr_reader :status, :headers, :body
+
+      # @param status [Integer]
+      # @param headers [Hash{String => String}] by lowercase name
+      # @param body [String] the bytes of the body
+      def initialize(status, headers, body)
+        @status = status
+        @headers = headers.freeze
+        @body = body
+        freeze
+      end
+
+      def inspect
+        "#<#{self.class.name} #{status}>"
+      end
+    end
+
+    # Paths with ids.
+    #
+    # @api private
+    module Path
+      # What `encodeURIComponent` leaves as it is.
+      UNRESERVED = /[^A-Za-z0-9\-_.!~*'()]/
+      # An id of spaces only.
+      BLANK = /\A[[:space:]]*\z/
+
+      module_function
+
+      # A path from a template with `{}` placeholders, each id percent-encoded.
+      #
+      #   Path.of("/v1/issuers/{}", issuer_id)
+      #
+      # Rejects ids that are not Strings or are blank, and `.` and `..`, which URL normalization
+      # would turn into the parent path (another resource).
+      #
+      # @return [String]
+      # @raise [Flashpi::Error]
+      def of(template, *ids)
+        parts = template.split("{}", -1)
+        if parts.size != ids.size + 1
+          raise ArgumentError,
+                "#{template} has #{parts.size - 1} placeholders, not #{ids.size}"
+        end
+
+        shown = template.gsub("{}", "{id}")
+        path = parts.first.to_s
+        ids.each_with_index do |id, index|
+          path += encode(segment(id, shown)) + parts.fetch(index + 1)
+        end
+        path
+      end
+
+      # An id as UTF-8 text, checked once converted: not blank (Unicode spaces included, as
+      # Python's `strip`), and not `.` or `..` in any encoding.
+      #
+      # @return [String]
+      # @raise [Flashpi::Error]
+      def segment(id, shown)
+        raise Error, "Missing id in #{shown}: got #{id.inspect}" unless id.is_a?(String)
+
+        text = Validate.utf8(id)
+        raise Error, "Invalid id in #{shown}: it is not valid UTF-8 text" if text.nil?
+        raise Error, "Missing id in #{shown}: got #{id.inspect}" if BLANK.match?(text)
+        raise Error, "Invalid id in #{shown}: #{text.inspect}" if [".", ".."].include?(text)
+
+        text
+      end
+
+      # Percent-encodes UTF-8 text as `encodeURIComponent` does.
+      #
+      # @return [String]
+      def encode(text)
+        text.gsub(UNRESERVED) { |char| char.unpack("C*").map { |byte| format("%%%02X", byte) }.join }
+      end
+    end
+
+    # The clock of the requests: monotonic time, sleeping and jitter. Tests replace it.
+    #
+    # @api private
+    module Clock
+      module_function
+
+      # @return [Float] monotonic seconds
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # @param seconds [Float]
+      def sleep(seconds)
+        Kernel.sleep(seconds)
+      end
+
+      # @return [Float] a random number in [0, 1)
+      def rand
+        Random.rand
+      end
+    end
+  end
+end

data/lib/flashpi/internal/resource.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Flashpi
+  module Internal
+    # Base of every resource: resources only declare their operations as {RequestSpec}s.
+    #
+    #   class Documents < Internal::Resource
+    #     response_methods :get
+    #
+    #     def get(document_id, **options)
+    #       send_request(RequestSpec.new(http_method: :get, path: Path.of("/v1/documents/{}", document_id),
+    #                                    options:))
+    #     end
+    #   end
+    #
+    # @api private
+    class Resource
+      # Declares the methods of the resource's `with_response` view: each runs the method and
+      # returns an {APIResponse} with its data and the answer it came from.
+      def self.response_methods(*names)
+        view = Class.new(ResponseView)
+        names.each do |name|
+          # Defined at run time, so its body is outside Steep's view of the class.
+          view.define_method(name) do |*args, **options, &block|
+            capture { resource.public_send(name, *args, **options, &block) } # steep:ignore
+          end
+        end
+        const_set(:WithResponse, view)
+      end
+
+      # @param engine [Engine]
+      def initialize(engine)
+        @engine = engine
+      end
+
+      # The same methods, returning an {APIResponse} with the HTTP status, headers and request id.
+      #
+      # @return [ResponseView]
+      def with_response
+        @with_response ||= self.class::WithResponse.new(self) # steep:ignore UnknownConstant
+      end
+
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      private
+
+      # The request of an operation: its path from a template and its ids (see {Path.of}).
+      def operation(http_method, template, *ids, **settings)
+        RequestSpec.new(http_method:, path: Path.of(template, *ids), **settings)
+      end
+
+      # Sends the request (with its retries) and returns its data.
+      def send_request(spec)
+        send_call(spec).data
+      end
+
+      # Sends the request (with its retries) and returns its data with the answer.
+      def send_call(spec)
+        result = @engine.request(spec)
+        ResponseView.record(result)
+        result
+      end
+
+      # The first page of a list; iterating it walks every page.
+      def paginate(spec)
+        first = fetch_page(spec, spec)
+        ResponseView.record(first)
+        first.data
+      end
+
+      def fetch_page(spec, page_spec)
+        result = @engine.request(page_spec)
+        page = Page.new(result.data) do |cursor|
+          query = (spec.query || {}).reject { |name, _| name.to_s == "cursor" }
+          fetch_page(spec, spec.with_query(query.merge(cursor:))).data
+        end
+        APIResponse.new(data: page, status: result.status, headers: result.headers, request_id: result.request_id)
+      end
+    end
+
+    # A resource's `with_response` view. The wrapped call records the last successful answer in a
+    # fiber-local slot, so the resource's methods themselves stay unchanged.
+    #
+    # @api private
+    class ResponseView
+      SLOT = :__flashpi_response_capture
+
+      # Keeps `result` for the `with_response` call running in this fiber, if any.
+      def self.record(result)
+        slot = Thread.current[SLOT]
+        slot[:result] = result if slot
+      end
+
+      def initialize(resource)
+        @resource = resource
+      end
+
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      private
+
+      attr_reader :resource
+
+      def capture
+        previous = Thread.current[SLOT]
+        slot = {} #: Hash[Symbol, APIResponse[untyped]]
+        data = nil #: untyped
+        Thread.current[SLOT] = slot
+        begin
+          data = yield
+        ensure
+          Thread.current[SLOT] = previous
+        end
+        result = slot[:result]
+        raise Error, "The call sent no request, so there is no response to return" if result.nil?
+
+        APIResponse.new(data:, status: result.status, headers: result.headers, request_id: result.request_id)
+      end
+    end
+  end
+end

data/lib/flashpi/internal/secret.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Flashpi
+  module Internal
+    # A value that must never be shown: an API key, a .p12 and its password.
+    #
+    # The value lives in a closure, not in an instance variable, so `inspect`, `pp`, `to_s`,
+    # ActiveSupport's `as_json` (which reads instance variables) and `Marshal.dump` (which refuses
+    # a Proc) never reveal it. {#reveal} is the only way to read it.
+    #
+    # @api private
+    class Secret
+      # @param value [Object]
+      def initialize(value)
+        @reader = -> { value }
+        freeze
+      end
+
+      # @return [Object] the value
+      def reveal
+        @reader.call
+      end
+
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} [FILTERED]>"
+      end
+      alias to_s inspect
+
+      # @raise [TypeError] always: a secret is never serialized.
+      def marshal_dump
+        raise TypeError, "A Flashpi secret cannot be serialized"
+      end
+
+      # @raise [TypeError] always: a secret is never serialized.
+      def _dump(_level)
+        raise TypeError, "A Flashpi secret cannot be serialized"
+      end
+    end
+  end
+end

data/lib/flashpi/internal/settings.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Flashpi
+  module Internal
+    # The settings of a client, checked before anything is sent.
+    #
+    # @api private
+    module Settings
+      # What an API key is made of: visible ASCII, without spaces.
+      API_KEY_CHARACTERS = /\A[\x21-\x7e]+\z/
+      # What JavaScript's `trim()` removes around a string, the Node SDK's key included: its white
+      # space and line breaks, and the byte order mark (U+FEFF).
+      JS_SPACE = "[\t\n\v\f\r    - 

  　]"
+      AROUND = /\A#{JS_SPACE}+|#{JS_SPACE}+\z/o
+
+      module_function
+
+      # The checked settings. The key is checked first, so a missing or bad key is the error
+      # reported, and every error is raised by a method that holds no copy of the key (error
+      # trackers can record the local variables of the method that raises).
+      def configure(api_key, base_url:, timeout:, max_retries:, language:, default_headers:)
+        problem = key_problem(trimmed_key(api_key))
+        refuse!(problem) if problem
+        headers = Internal::Validate.headers!("default_headers", default_headers)
+        unless language.nil?
+          language = Internal::Validate.header_value!("language",
+                                                      language.is_a?(Symbol) ? language.to_s : language)
+        end
+        if headers.keys.any? { |name| name.casecmp?("idempotency-key") }
+          refuse!("default_headers cannot carry an Idempotency-Key: it must be unique per operation. " \
+                  "Pass idempotency_key: to each create instead")
+        end
+        url = base_url.nil? ? DEFAULT_BASE_URL : base_url
+        refuse!("base_url must be an http:// or https:// URL, got #{url.inspect}") unless http_url?(url)
+
+        Internal::ClientConfig.new(
+          api_key: trimmed_key(api_key),
+          base_url: url,
+          timeout: Internal::Validate.timeout!("timeout", timeout.nil? ? DEFAULT_TIMEOUT : timeout),
+          max_retries: Internal::Validate.retries!("max_retries", max_retries.nil? ? DEFAULT_MAX_RETRIES : max_retries),
+          language:,
+          default_headers: headers
+        )
+      end
+
+      def refuse!(message)
+        raise Error, message
+      end
+
+      def http_url?(url)
+        return false unless url.is_a?(String)
+
+        parsed = URI.parse(url)
+        %w[http https].include?(parsed.scheme) && !parsed.host.to_s.empty?
+      rescue URI::InvalidURIError
+        false
+      end
+
+      # The key: the argument or FLASHPI_API_KEY, trimmed as JavaScript's `trim()`, the byte order
+      # mark included. Anything that is not a String is no key.
+      def trimmed_key(api_key)
+        value = api_key.nil? ? ENV.fetch("FLASHPI_API_KEY", nil) : api_key
+        return "" unless value.is_a?(String)
+
+        text = Internal::Validate.utf8(value)
+        # A key that is not valid text is refused for its characters below.
+        text ? text.gsub(AROUND, "") : value.b
+      end
+
+      # Why a trimmed key cannot be used, or nil. It returns instead of raising, so its frame is
+      # never part of an error.
+      def key_problem(key)
+        if key.empty?
+          "Missing API key: pass it to Flashpi::Client.new(api_key: ...) or set the FLASHPI_API_KEY " \
+            "environment variable"
+        elsif key.start_with?("whsec_")
+          "That is a webhook signing secret (whsec_...), not an API key: use it with Flashpi::Webhooks"
+        elsif !key.start_with?("fp_test_", "fp_live_")
+          "The API key must start with fp_test_ or fp_live_"
+        elsif !API_KEY_CHARACTERS.match?(key)
+          # Never the key: net/http would refuse it in the Authorization header and quote it.
+          "The API key has spaces, line breaks or other characters an API key cannot have: copy it again " \
+            "from the Flashpi console"
+        end
+      end
+    end
+  end
+end