lithic 0.1.0.pre.alpha.1 → 0.1.0.pre.alpha.3

data/lib/lithic/transport/pooled_net_requester.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Transport
+    # @api private
+    class PooledNetRequester
+      # from the golang stdlib
+      #   https://github.com/golang/go/blob/c8eced8580028328fde7c03cbfcb720ce15b2358/src/net/http/transport.go#L49
+      KEEP_ALIVE_TIMEOUT = 30
+
+      class << self
+        # @api private
+        #
+        # @param url [URI::Generic]
+        #
+        # @return [Net::HTTP]
+        def connect(url)
+          port =
+            case [url.port, url.scheme]
+            in [Integer, _]
+              url.port
+            in [nil, "http" | "ws"]
+              Net::HTTP.http_default_port
+            in [nil, "https" | "wss"]
+              Net::HTTP.https_default_port
+            end
+
+          Net::HTTP.new(url.host, port).tap do
+            _1.use_ssl = %w[https wss].include?(url.scheme)
+            _1.max_retries = 0
+          end
+        end
+
+        # @api private
+        #
+        # @param conn [Net::HTTP]
+        # @param deadline [Float]
+        def calibrate_socket_timeout(conn, deadline)
+          timeout = deadline - Lithic::Util.monotonic_secs
+          conn.open_timeout = conn.read_timeout = conn.write_timeout = conn.continue_timeout = timeout
+        end
+
+        # @api private
+        #
+        # @param request [Hash{Symbol=>Object}] .
+        #
+        #   @option request [Symbol] :method
+        #
+        #   @option request [URI::Generic] :url
+        #
+        #   @option request [Hash{String=>String}] :headers
+        #
+        # @param blk [Proc]
+        #
+        # @yieldparam [String]
+        # @return [Net::HTTPGenericRequest]
+        def build_request(request, &blk)
+          method, url, headers, body = request.fetch_values(:method, :url, :headers, :body)
+          req = Net::HTTPGenericRequest.new(
+            method.to_s.upcase,
+            !body.nil?,
+            method != :head,
+            url.to_s
+          )
+
+          headers.each { req[_1] = _2 }
+
+          case body
+          in nil
+            nil
+          in String
+            req["content-length"] ||= body.bytesize.to_s unless req["transfer-encoding"]
+            req.body_stream = Lithic::Util::ReadIOAdapter.new(body, &blk)
+          in StringIO
+            req["content-length"] ||= body.size.to_s unless req["transfer-encoding"]
+            req.body_stream = Lithic::Util::ReadIOAdapter.new(body, &blk)
+          in IO | Enumerator
+            req["transfer-encoding"] ||= "chunked" unless req["content-length"]
+            req.body_stream = Lithic::Util::ReadIOAdapter.new(body, &blk)
+          end
+
+          req
+        end
+      end
+
+      # @api private
+      #
+      # @param url [URI::Generic]
+      # @param deadline [Float]
+      # @param blk [Proc]
+      #
+      # @raise [Timeout::Error]
+      # @yieldparam [Net::HTTP]
+      private def with_pool(url, deadline:, &blk)
+        origin = Lithic::Util.uri_origin(url)
+        timeout = deadline - Lithic::Util.monotonic_secs
+        pool =
+          @mutex.synchronize do
+            @pools[origin] ||= ConnectionPool.new(size: @size) do
+              self.class.connect(url)
+            end
+          end
+
+        pool.with(timeout: timeout, &blk)
+      end
+
+      # @api private
+      #
+      # @param request [Hash{Symbol=>Object}] .
+      #
+      #   @option request [Symbol] :method
+      #
+      #   @option request [URI::Generic] :url
+      #
+      #   @option request [Hash{String=>String}] :headers
+      #
+      #   @option request [Object] :body
+      #
+      #   @option request [Float] :deadline
+      #
+      # @return [Array(Integer, Net::HTTPResponse, Enumerable)]
+      def execute(request)
+        url, deadline = request.fetch_values(:url, :deadline)
+
+        eof = false
+        finished = false
+        enum = Enumerator.new do |y|
+          with_pool(url, deadline: deadline) do |conn|
+            next if finished
+
+            req = self.class.build_request(request) do
+              self.class.calibrate_socket_timeout(conn, deadline)
+            end
+
+            self.class.calibrate_socket_timeout(conn, deadline)
+            unless conn.started?
+              conn.keep_alive_timeout = self.class::KEEP_ALIVE_TIMEOUT
+              conn.start
+            end
+
+            self.class.calibrate_socket_timeout(conn, deadline)
+            conn.request(req) do |rsp|
+              y << [conn, req, rsp]
+              break if finished
+
+              rsp.read_body do |bytes|
+                y << bytes
+                break if finished
+
+                self.class.calibrate_socket_timeout(conn, deadline)
+              end
+              eof = true
+            end
+          end
+        rescue Timeout::Error
+          raise Lithic::APITimeoutError
+        end
+
+        conn, _, response = enum.next
+        body = Lithic::Util.fused_enum(enum, external: true) do
+          finished = true
+          tap do
+            enum.next
+          rescue StopIteration
+            nil
+          end
+          conn.finish if !eof && conn&.started?
+        end
+        [Integer(response.code), response, (response.body = body)]
+      end
+
+      # @api private
+      #
+      # @param size [Integer]
+      def initialize(size: Etc.nprocessors)
+        @mutex = Mutex.new
+        @size = size
+        @pools = {}
+      end
+    end
+  end
+end

data/lib/lithic/type/array_of.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Type
+    # @api private
+    #
+    # @abstract
+    #
+    # Array of items of a given type.
+    class ArrayOf
+      include Lithic::Type::Converter
+
+      # @param type_info [Hash{Symbol=>Object}, Proc, Lithic::Type::Converter, Class]
+      #
+      # @param spec [Hash{Symbol=>Object}] .
+      #
+      #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+      #
+      #   @option spec [Proc] :enum
+      #
+      #   @option spec [Proc] :union
+      #
+      #   @option spec [Boolean] :"nil?"
+      def self.[](type_info, spec = {}) = new(type_info, spec)
+
+      # @param other [Object]
+      #
+      # @return [Boolean]
+      def ===(other) = other.is_a?(Array) && other.all?(item_type)
+
+      # @param other [Object]
+      #
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(Lithic::ArrayOf) && other.nilable? == nilable? && other.item_type == item_type
+      end
+
+      # @api private
+      #
+      # @param value [Enumerable, Object]
+      #
+      # @param state [Hash{Symbol=>Object}] .
+      #
+      #   @option state [Boolean, :strong] :strictness
+      #
+      #   @option state [Hash{Symbol=>Object}] :exactness
+      #
+      #   @option state [Integer] :branched
+      #
+      # @return [Array<Object>, Object]
+      def coerce(value, state:)
+        exactness = state.fetch(:exactness)
+
+        unless value.is_a?(Array)
+          exactness[:no] += 1
+          return value
+        end
+
+        target = item_type
+        exactness[:yes] += 1
+        value
+          .map do |item|
+            case [nilable?, item]
+            in [true, nil]
+              exactness[:yes] += 1
+              nil
+            else
+              Lithic::Type::Converter.coerce(target, item, state: state)
+            end
+          end
+      end
+
+      # @api private
+      #
+      # @param value [Enumerable, Object]
+      #
+      # @return [Array<Object>, Object]
+      def dump(value)
+        target = item_type
+        value.is_a?(Array) ? value.map { Lithic::Type::Converter.dump(target, _1) } : super
+      end
+
+      # @api private
+      #
+      # @return [Lithic::Type::Converter, Class]
+      protected def item_type = @item_type_fn.call
+
+      # @api private
+      #
+      # @return [Boolean]
+      protected def nilable? = @nilable
+
+      # @api private
+      #
+      # @param type_info [Hash{Symbol=>Object}, Proc, Lithic::Type::Converter, Class]
+      #
+      # @param spec [Hash{Symbol=>Object}] .
+      #
+      #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+      #
+      #   @option spec [Proc] :enum
+      #
+      #   @option spec [Proc] :union
+      #
+      #   @option spec [Boolean] :"nil?"
+      def initialize(type_info, spec = {})
+        @item_type_fn = Lithic::Type::Converter.type_info(type_info || spec)
+        @nilable = spec[:nil?]
+      end
+    end
+  end
+end

data/lib/lithic/type/base_model.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Type
+    # @abstract
+    #
+    # @example
+    #   # `address` is a `Lithic::Models::Address`
+    #   address => {
+    #     address1: address1,
+    #     city: city,
+    #     country: country
+    #   }
+    class BaseModel
+      extend Lithic::Type::Converter
+
+      class << self
+        # @api private
+        #
+        # Assumes superclass fields are totally defined before fields are accessed /
+        #   defined on subclasses.
+        #
+        # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
+        def known_fields
+          @known_fields ||= (self < Lithic::BaseModel ? superclass.known_fields.dup : {})
+        end
+
+        # @api private
+        #
+        # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
+        def fields
+          known_fields.transform_values do |field|
+            {**field.except(:type_fn), type: field.fetch(:type_fn).call}
+          end
+        end
+
+        # @api private
+        #
+        # @param name_sym [Symbol]
+        #
+        # @param required [Boolean]
+        #
+        # @param type_info [Hash{Symbol=>Object}, Proc, Lithic::Type::Converter, Class]
+        #
+        # @param spec [Hash{Symbol=>Object}] .
+        #
+        #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+        #
+        #   @option spec [Proc] :enum
+        #
+        #   @option spec [Proc] :union
+        #
+        #   @option spec [Boolean] :"nil?"
+        private def add_field(name_sym, required:, type_info:, spec:)
+          type_fn, info =
+            case type_info
+            in Proc | Lithic::Type::Converter | Class
+              [Lithic::Type::Converter.type_info({**spec, union: type_info}), spec]
+            in Hash
+              [Lithic::Type::Converter.type_info(type_info), type_info]
+            end
+
+          setter = "#{name_sym}="
+          api_name = info.fetch(:api_name, name_sym)
+          nilable = info[:nil?]
+          const = required && !nilable ? info.fetch(:const, Lithic::Util::OMIT) : Lithic::Util::OMIT
+
+          [name_sym, setter].each { undef_method(_1) } if known_fields.key?(name_sym)
+
+          known_fields[name_sym] =
+            {
+              mode: @mode,
+              api_name: api_name,
+              required: required,
+              nilable: nilable,
+              const: const,
+              type_fn: type_fn
+            }
+
+          define_method(setter) { @data.store(name_sym, _1) }
+
+          define_method(name_sym) do
+            target = type_fn.call
+            value = @data.fetch(name_sym) { const == Lithic::Util::OMIT ? nil : const }
+            state = {strictness: :strong, exactness: {yes: 0, no: 0, maybe: 0}, branched: 0}
+            if (nilable || !required) && value.nil?
+              nil
+            else
+              Lithic::Type::Converter.coerce(
+                target,
+                value,
+                state: state
+              )
+            end
+          rescue StandardError
+            cls = self.class.name.split("::").last
+            # rubocop:disable Layout/LineLength
+            message = "Failed to parse #{cls}.#{__method__} from #{value.class} to #{target.inspect}. To get the unparsed API response, use #{cls}[:#{__method__}]."
+            # rubocop:enable Layout/LineLength
+            raise Lithic::ConversionError.new(message)
+          end
+        end
+
+        # @api private
+        #
+        # @param name_sym [Symbol]
+        #
+        # @param type_info [Hash{Symbol=>Object}, Proc, Lithic::Type::Converter, Class]
+        #
+        # @param spec [Hash{Symbol=>Object}] .
+        #
+        #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+        #
+        #   @option spec [Proc] :enum
+        #
+        #   @option spec [Proc] :union
+        #
+        #   @option spec [Boolean] :"nil?"
+        def required(name_sym, type_info, spec = {})
+          add_field(name_sym, required: true, type_info: type_info, spec: spec)
+        end
+
+        # @api private
+        #
+        # @param name_sym [Symbol]
+        #
+        # @param type_info [Hash{Symbol=>Object}, Proc, Lithic::Type::Converter, Class]
+        #
+        # @param spec [Hash{Symbol=>Object}] .
+        #
+        #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+        #
+        #   @option spec [Proc] :enum
+        #
+        #   @option spec [Proc] :union
+        #
+        #   @option spec [Boolean] :"nil?"
+        def optional(name_sym, type_info, spec = {})
+          add_field(name_sym, required: false, type_info: type_info, spec: spec)
+        end
+
+        # @api private
+        #
+        # `request_only` attributes not excluded from `.#coerce` when receiving responses
+        #   even if well behaved servers should not send them
+        #
+        # @param blk [Proc]
+        private def request_only(&blk)
+          @mode = :dump
+          blk.call
+        ensure
+          @mode = nil
+        end
+
+        # @api private
+        #
+        # `response_only` attributes are omitted from `.#dump` when making requests
+        #
+        # @param blk [Proc]
+        private def response_only(&blk)
+          @mode = :coerce
+          blk.call
+        ensure
+          @mode = nil
+        end
+
+        # @param other [Object]
+        #
+        # @return [Boolean]
+        def ==(other) = other.is_a?(Class) && other <= Lithic::BaseModel && other.fields == fields
+      end
+
+      # @param other [Object]
+      #
+      # @return [Boolean]
+      def ==(other) = self.class == other.class && @data == other.to_h
+
+      class << self
+        # @api private
+        #
+        # @param value [Lithic::BaseModel, Hash{Object=>Object}, Object]
+        #
+        # @param state [Hash{Symbol=>Object}] .
+        #
+        #   @option state [Boolean, :strong] :strictness
+        #
+        #   @option state [Hash{Symbol=>Object}] :exactness
+        #
+        #   @option state [Integer] :branched
+        #
+        # @return [Lithic::BaseModel, Object]
+        def coerce(value, state:)
+          exactness = state.fetch(:exactness)
+
+          if value.is_a?(self.class)
+            exactness[:yes] += 1
+            return value
+          end
+
+          unless (val = Lithic::Util.coerce_hash(value)).is_a?(Hash)
+            exactness[:no] += 1
+            return value
+          end
+          exactness[:yes] += 1
+
+          keys = val.keys.to_set
+          instance = new
+          data = instance.to_h
+
+          # rubocop:disable Metrics/BlockLength
+          fields.each do |name, field|
+            mode, required, target = field.fetch_values(:mode, :required, :type)
+            api_name, nilable, const = field.fetch_values(:api_name, :nilable, :const)
+
+            unless val.key?(api_name)
+              if required && mode != :dump && const == Lithic::Util::OMIT
+                exactness[nilable ? :maybe : :no] += 1
+              else
+                exactness[:yes] += 1
+              end
+              next
+            end
+
+            item = val.fetch(api_name)
+            keys.delete(api_name)
+
+            converted =
+              if item.nil? && (nilable || !required)
+                exactness[nilable ? :yes : :maybe] += 1
+                nil
+              else
+                coerced = Lithic::Type::Converter.coerce(target, item, state: state)
+                case target
+                in Lithic::Type::Converter | Symbol
+                  coerced
+                else
+                  item
+                end
+              end
+            data.store(name, converted)
+          end
+          # rubocop:enable Metrics/BlockLength
+
+          keys.each { data.store(_1, val.fetch(_1)) }
+          instance
+        end
+
+        # @api private
+        #
+        # @param value [Lithic::BaseModel, Object]
+        #
+        # @return [Hash{Object=>Object}, Object]
+        def dump(value)
+          unless (coerced = Lithic::Util.coerce_hash(value)).is_a?(Hash)
+            return super
+          end
+
+          acc = {}
+
+          coerced.each do |key, val|
+            name = key.is_a?(String) ? key.to_sym : key
+            case (field = known_fields[name])
+            in nil
+              acc.store(name, super(val))
+            else
+              mode, api_name, type_fn = field.fetch_values(:mode, :api_name, :type_fn)
+              case mode
+              in :coerce
+                next
+              else
+                target = type_fn.call
+                acc.store(api_name, Lithic::Type::Converter.dump(target, val))
+              end
+            end
+          end
+
+          known_fields.each_value do |field|
+            mode, api_name, const = field.fetch_values(:mode, :api_name, :const)
+            next if mode == :coerce || acc.key?(api_name) || const == Lithic::Util::OMIT
+            acc.store(api_name, const)
+          end
+
+          acc
+        end
+      end
+
+      # Returns the raw value associated with the given key, if found. Otherwise, nil is
+      #   returned.
+      #
+      #   It is valid to lookup keys that are not in the API spec, for example to access
+      #   undocumented features. This method does not parse response data into
+      #   higher-level types. Lookup by anything other than a Symbol is an ArgumentError.
+      #
+      # @param key [Symbol]
+      #
+      # @return [Object, nil]
+      def [](key)
+        unless key.instance_of?(Symbol)
+          raise ArgumentError.new("Expected symbol key for lookup, got #{key.inspect}")
+        end
+
+        @data[key]
+      end
+
+      # Returns a Hash of the data underlying this object. O(1)
+      #
+      #   Keys are Symbols and values are the raw values from the response. The return
+      #   value indicates which values were ever set on the object. i.e. there will be a
+      #   key in this hash if they ever were, even if the set value was nil.
+      #
+      #   This method is not recursive. The returned value is shared by the object, so it
+      #   should not be mutated.
+      #
+      # @return [Hash{Symbol=>Object}]
+      def to_h = @data
+
+      alias_method :to_hash, :to_h
+
+      # @param keys [Array<Symbol>, nil]
+      #
+      # @return [Hash{Symbol=>Object}]
+      def deconstruct_keys(keys)
+        (keys || self.class.known_fields.keys)
+          .filter_map do |k|
+            unless self.class.known_fields.key?(k)
+              next
+            end
+
+            [k, public_send(k)]
+          end
+          .to_h
+      end
+
+      # Create a new instance of a model.
+      #
+      # @param data [Hash{Symbol=>Object}, Lithic::BaseModel]
+      def initialize(data = {})
+        case Lithic::Util.coerce_hash(data)
+        in Hash => coerced
+          @data = coerced
+        else
+          raise ArgumentError.new("Expected a #{Hash} or #{Lithic::BaseModel}, got #{data.inspect}")
+        end
+      end
+
+      # @return [String]
+      def inspect
+        rows = self.class.known_fields.keys.map do
+          "#{_1}=#{@data.key?(_1) ? public_send(_1) : ''}"
+        rescue Lithic::ConversionError
+          "#{_1}=#{@data.fetch(_1)}"
+        end
+        "#<#{self.class.name}:0x#{object_id.to_s(16)} #{rows.join(' ')}>"
+      end
+    end
+  end
+end

data/lib/lithic/type/base_page.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Type
+    # @example
+    #   if page.has_next?
+    #     page = page.next_page
+    #   end
+    #
+    # @example
+    #   page.auto_paging_each do |client|
+    #     puts(client)
+    #   end
+    #
+    # @example
+    #   clients =
+    #     page
+    #     .to_enum
+    #     .lazy
+    #     .select { _1.object_id.even? }
+    #     .map(&:itself)
+    #     .take(2)
+    #     .to_a
+    #
+    #   clients => Array
+    module BasePage
+      # rubocop:disable Lint/UnusedMethodArgument
+
+      # @return [Boolean]
+      def next_page? = (raise NotImplementedError)
+
+      # @raise [Lithic::APIError]
+      # @return [Lithic::Type::BasePage]
+      def next_page = (raise NotImplementedError)
+
+      # @param blk [Proc]
+      #
+      # @return [void]
+      def auto_paging_each(&blk) = (raise NotImplementedError)
+
+      # @return [Enumerable]
+      def to_enum = super(:auto_paging_each)
+
+      alias_method :enum_for, :to_enum
+
+      # @api private
+      #
+      # @param client [Lithic::Transport::BaseClient]
+      # @param req [Hash{Symbol=>Object}]
+      # @param headers [Hash{String=>String}, Net::HTTPHeader]
+      # @param page_data [Object]
+      def initialize(client:, req:, headers:, page_data:)
+        @client = client
+        @req = req
+        super()
+      end
+
+      # rubocop:enable Lint/UnusedMethodArgument
+    end
+  end
+end