finch-api 0.1.0.pre.alpha.1 → 0.1.0.pre.alpha.2

data/lib/finch-api/page.rb

@@ -2,84 +2,79 @@
 
 module FinchAPI
   # @example
-  # ```ruby
-  # if page.has_next?
-  #   page = page.next_page
-  # end
-  # ```
+  #   if page.has_next?
+  #     page = page.next_page
+  #   end
   #
   # @example
-  # ```ruby
-  # page.auto_paging_each do |item|
-  # #   item ...
-  # end
-  # ```
+  #   page.auto_paging_each do |item|
+  #     puts(item)
+  #   end
   #
   # @example
-  # ```ruby
-  # items = page.to_enum.take(2)
+  #   items =
+  #     page
+  #     .to_enum
+  #     .lazy
+  #     .select { _1.object_id.even? }
+  #     .map(&:itself)
+  #     .take(2)
+  #     .to_a
   #
-  # items => Array
-  # ```
+  #   items => Array
   class Page
     include FinchAPI::BasePage
 
-    # @return [Array<Object>]
+    # @return [Array<Object>, nil]
     attr_accessor :data
 
     # @return [FinchAPI::Models::Paging]
     attr_accessor :paging
 
-    # rubocop:disable Lint/UnusedMethodArgument
-    # @private
+    # @api private
     #
     # @param client [FinchAPI::BaseClient]
     # @param req [Hash{Symbol=>Object}]
     # @param headers [Hash{String=>String}, Net::HTTPHeader]
-    # @param unwrapped [Hash{Symbol=>Object}]
-    #
-    def initialize(client:, req:, headers:, unwrapped:)
-      @client = client
-      @req = req
+    # @param page_data [Hash{Symbol=>Object}]
+    def initialize(client:, req:, headers:, page_data:)
+      super
       model = req.fetch(:model)
 
-      case unwrapped
+      case page_data
       in {data: Array | nil => data}
-        @data = data&.map { model.coerce(_1) }
+        @data = data&.map { FinchAPI::Converter.coerce(model, _1) }
       else
       end
 
-      case unwrapped
+      case page_data
       in {paging: Hash | nil => paging}
         @paging = FinchAPI::Models::Paging.coerce(paging)
       else
       end
     end
-    # rubocop:enable Lint/UnusedMethodArgument
 
     # @return [Boolean]
-    #
     def next_page?
-      paging&.offset.to_i + data.size < paging&.count.to_i
+      paging&.offset.to_i + data.to_a.size < paging&.count.to_i
     end
 
     # @raise [FinchAPI::HTTP::Error]
     # @return [FinchAPI::Page]
-    #
     def next_page
       unless next_page?
-        raise RuntimeError.new("No more pages available; please check #next_page? before calling #next_page")
+        message = "No more pages available. Please check #next_page? before calling ##{__method__}"
+        raise RuntimeError.new(message)
       end
 
-      req = FinchAPI::Util.deep_merge(@req, {query: {offset: paging&.offset.to_i + data.size}})
+      req = FinchAPI::Util.deep_merge(@req, {query: {offset: paging&.offset.to_i + data.to_a.size}})
       @client.request(req)
     end
 
     # @param blk [Proc]
-    #
     def auto_paging_each(&blk)
       unless block_given?
-        raise ArgumentError.new("A block must be given to #auto_paging_each")
+        raise ArgumentError.new("A block must be given to ##{__method__}")
       end
       page = self
       loop do
@@ -90,7 +85,6 @@ module FinchAPI
     end
 
     # @return [String]
-    #
     def inspect
       "#<#{self.class}:0x#{object_id.to_s(16)} data=#{data.inspect} paging=#{paging.inspect}>"
     end

data/lib/finch-api/pooled_net_requester.rb

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
 module FinchAPI
-  # @private
-  #
+  # @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
-      # @private
+      # @api private
       #
       # @param url [URI::Generic]
       #
       # @return [Net::HTTP]
-      #
       def connect(url)
         port =
           case [url.port, url.scheme]
@@ -28,17 +30,16 @@ module FinchAPI
         end
       end
 
-      # @private
+      # @api private
       #
       # @param conn [Net::HTTP]
       # @param deadline [Float]
-      #
       def calibrate_socket_timeout(conn, deadline)
         timeout = deadline - FinchAPI::Util.monotonic_secs
         conn.open_timeout = conn.read_timeout = conn.write_timeout = conn.continue_timeout = timeout
       end
 
-      # @private
+      # @api private
       #
       # @param request [Hash{Symbol=>Object}] .
       #
@@ -48,9 +49,11 @@ module FinchAPI
       #
       #   @option request [Hash{String=>String}] :headers
       #
-      # @return [Net::HTTPGenericRequest]
+      # @param blk [Proc]
       #
-      def build_request(request)
+      # @yieldparam [String]
+      # @return [Net::HTTPGenericRequest]
+      def build_request(request, &)
         method, url, headers, body = request.fetch_values(:method, :url, :headers, :body)
         req = Net::HTTPGenericRequest.new(
           method.to_s.upcase,
@@ -63,54 +66,44 @@ module FinchAPI
 
         case body
         in nil
+          nil
         in String
-          req.body = body
+          req["content-length"] ||= body.bytesize.to_s unless req["transfer-encoding"]
+          req.body_stream = FinchAPI::Util::ReadIOAdapter.new(body, &)
         in StringIO
-          req.body = body.string
-        in IO
-          body.rewind
-          req.body_stream = body
+          req["content-length"] ||= body.size.to_s unless req["transfer-encoding"]
+          req.body_stream = FinchAPI::Util::ReadIOAdapter.new(body, &)
+        in IO | Enumerator
+          req["transfer-encoding"] ||= "chunked" unless req["content-length"]
+          req.body_stream = FinchAPI::Util::ReadIOAdapter.new(body, &)
         end
 
         req
       end
     end
 
-    # @private
+    # @api private
     #
     # @param url [URI::Generic]
+    # @param deadline [Float]
     # @param blk [Proc]
     #
-    private def with_pool(url, &blk)
+    # @raise [Timeout::Error]
+    # @yieldparam [Net::HTTP]
+    private def with_pool(url, deadline:, &blk)
       origin = FinchAPI::Util.uri_origin(url)
-      th = Thread.current
-      key = :"#{object_id}-#{self.class.name}-connection_in_use_for_#{origin}"
-
-      if th[key]
-        tap do
-          conn = self.class.connect(url)
-          return blk.call(conn)
-        ensure
-          conn.finish if conn&.started?
-        end
-      end
-
+      timeout = deadline - FinchAPI::Util.monotonic_secs
       pool =
         @mutex.synchronize do
-          @pools[origin] ||= ConnectionPool.new(size: Etc.nprocessors) do
+          @pools[origin] ||= ConnectionPool.new(size: @size) do
             self.class.connect(url)
           end
         end
 
-      pool.with do |conn|
-        th[key] = true
-        blk.call(conn)
-      ensure
-        th[key] = nil
-      end
+      pool.with(timeout: timeout, &blk)
     end
 
-    # @private
+    # @api private
     #
     # @param request [Hash{Symbol=>Object}] .
     #
@@ -124,24 +117,29 @@ module FinchAPI
     #
     #   @option request [Float] :deadline
     #
-    # @return [Array(Net::HTTPResponse, Enumerable)]
-    #
+    # @return [Array(Integer, Net::HTTPResponse, Enumerable)]
     def execute(request)
       url, deadline = request.fetch_values(:url, :deadline)
-      req = self.class.build_request(request)
 
       eof = false
       finished = false
       enum = Enumerator.new do |y|
-        with_pool(url) do |conn|
+        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)
-          conn.start unless conn.started?
+          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, rsp]
+            y << [conn, req, rsp]
             break if finished
 
             rsp.read_body do |bytes|
@@ -153,22 +151,29 @@ module FinchAPI
             eof = true
           end
         end
+      rescue Timeout::Error
+        raise FinchAPI::APITimeoutError
       end
 
-      conn, response = enum.next
-      body = FinchAPI::Util.fused_enum(enum) do
+      conn, _, response = enum.next
+      body = FinchAPI::Util.fused_enum(enum, external: true) do
         finished = true
         tap do
           enum.next
         rescue StopIteration
+          nil
         end
         conn.finish if !eof && conn&.started?
       end
-      [response, (response.body = body)]
+      [Integer(response.code), response, (response.body = body)]
     end
 
-    def initialize
+    # @api private
+    #
+    # @param size [Integer]
+    def initialize(size: Etc.nprocessors)
       @mutex = Mutex.new
+      @size = size
       @pools = {}
     end
   end

data/lib/finch-api/request_options.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
 module FinchAPI
-  # @private
-  #
-  # @abstract
-  #
+  # @api private
   module RequestParameters
     # @!parse
     #   # Options to specify HTTP behaviour for this request.
@@ -12,7 +9,6 @@ module FinchAPI
     #   attr_accessor :request_options
 
     # @param mod [Module]
-    #
     def self.included(mod)
       return unless mod <= FinchAPI::BaseModel
 
@@ -20,15 +16,13 @@ module FinchAPI
       mod.optional(:request_options, FinchAPI::RequestOptions)
     end
 
-    # @private
-    #
+    # @api private
     module Converter
-      # @private
+      # @api private
       #
       # @param params [Object]
       #
       # @return [Array(Object, Hash{Symbol=>Object})]
-      #
       def dump_request(params)
         case (dumped = dump(params))
         in Hash
@@ -46,12 +40,11 @@ module FinchAPI
   #   When making a request, you can pass an actual {RequestOptions} instance, or
   #   simply pass a Hash with symbol keys matching the attributes on this class.
   class RequestOptions < FinchAPI::BaseModel
-    # @private
+    # @api private
     #
     # @param opts [FinchAPI::RequestOptions, Hash{Symbol=>Object}]
     #
     # @raise [ArgumentError]
-    #
     def self.validate!(opts)
       case opts
       in FinchAPI::RequestOptions | Hash
@@ -90,7 +83,7 @@ module FinchAPI
     #   Extra data to send with the request. These are deep merged into any data
     #     generated as part of the normal request.
     #
-    #   @return [Hash{Symbol=>Object}, nil]
+    #   @return [Object, nil]
     optional :extra_body, FinchAPI::HashOf[FinchAPI::Unknown]
 
     # @!attribute max_retries

data/lib/finch-api/resources/access_tokens.rb

@@ -18,7 +18,6 @@ module FinchAPI
       #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [FinchAPI::Models::CreateAccessTokenResponse]
-      #
       def create(params)
         parsed, options = FinchAPI::Models::AccessTokenCreateParams.dump_request(params)
         @client.request(
@@ -31,7 +30,6 @@ module FinchAPI
       end
 
       # @param client [FinchAPI::Client]
-      #
       def initialize(client:)
         @client = client
       end

data/lib/finch-api/resources/account.rb

@@ -10,7 +10,6 @@ module FinchAPI
       #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [FinchAPI::Models::DisconnectResponse]
-      #
       def disconnect(params = {})
         @client.request(
           method: :post,
@@ -27,7 +26,6 @@ module FinchAPI
       #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [FinchAPI::Models::Introspection]
-      #
       def introspect(params = {})
         @client.request(
           method: :get,
@@ -38,7 +36,6 @@ module FinchAPI
       end
 
       # @param client [FinchAPI::Client]
-      #
       def initialize(client:)
         @client = client
       end

data/lib/finch-api/resources/connect/sessions.rb

@@ -30,7 +30,6 @@ module FinchAPI
         #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
         #
         # @return [FinchAPI::Models::Connect::SessionNewResponse]
-        #
         def new(params)
           parsed, options = FinchAPI::Models::Connect::SessionNewParams.dump_request(params)
           @client.request(
@@ -58,7 +57,6 @@ module FinchAPI
         #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
         #
         # @return [FinchAPI::Models::Connect::SessionReauthenticateResponse]
-        #
         def reauthenticate(params)
           parsed, options = FinchAPI::Models::Connect::SessionReauthenticateParams.dump_request(params)
           @client.request(
@@ -71,7 +69,6 @@ module FinchAPI
         end
 
         # @param client [FinchAPI::Client]
-        #
         def initialize(client:)
           @client = client
         end

data/lib/finch-api/resources/connect.rb

@@ -7,7 +7,6 @@ module FinchAPI
       attr_reader :sessions
 
       # @param client [FinchAPI::Client]
-      #
       def initialize(client:)
         @client = client
         @sessions = FinchAPI::Resources::Connect::Sessions.new(client: client)

data/lib/finch-api/resources/hris/benefits/individuals.rb

@@ -19,7 +19,6 @@ module FinchAPI
           #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
           #
           # @return [FinchAPI::SinglePage<FinchAPI::Models::HRIS::Benefits::EnrolledIndividual>]
-          #
           def enroll_many(benefit_id, params = {})
             parsed, options = FinchAPI::Models::HRIS::Benefits::IndividualEnrollManyParams.dump_request(params)
             @client.request(
@@ -41,7 +40,6 @@ module FinchAPI
           #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
           #
           # @return [FinchAPI::Models::HRIS::Benefits::IndividualEnrolledIDsResponse]
-          #
           def enrolled_ids(benefit_id, params = {})
             @client.request(
               method: :get,
@@ -63,9 +61,9 @@ module FinchAPI
           #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
           #
           # @return [FinchAPI::SinglePage<FinchAPI::Models::HRIS::Benefits::IndividualBenefit>]
-          #
           def retrieve_many_benefits(benefit_id, params = {})
-            parsed, options = FinchAPI::Models::HRIS::Benefits::IndividualRetrieveManyBenefitsParams.dump_request(params)
+            parsed, options =
+              FinchAPI::Models::HRIS::Benefits::IndividualRetrieveManyBenefitsParams.dump_request(params)
             @client.request(
               method: :get,
               path: ["employer/benefits/%0s/individuals", benefit_id],
@@ -87,7 +85,6 @@ module FinchAPI
           #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
           #
           # @return [FinchAPI::SinglePage<FinchAPI::Models::HRIS::Benefits::UnenrolledIndividual>]
-          #
           def unenroll_many(benefit_id, params = {})
             parsed, options = FinchAPI::Models::HRIS::Benefits::IndividualUnenrollManyParams.dump_request(params)
             @client.request(
@@ -101,7 +98,6 @@ module FinchAPI
           end
 
           # @param client [FinchAPI::Client]
-          #
           def initialize(client:)
             @client = client
           end

data/lib/finch-api/resources/hris/benefits.rb

@@ -23,7 +23,6 @@ module FinchAPI
         #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
         #
         # @return [FinchAPI::Models::HRIS::CreateCompanyBenefitsResponse]
-        #
         def create(params = {})
           parsed, options = FinchAPI::Models::HRIS::BenefitCreateParams.dump_request(params)
           @client.request(
@@ -44,7 +43,6 @@ module FinchAPI
         #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
         #
         # @return [FinchAPI::Models::HRIS::CompanyBenefit]
-        #
         def retrieve(benefit_id, params = {})
           @client.request(
             method: :get,
@@ -65,7 +63,6 @@ module FinchAPI
         #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
         #
         # @return [FinchAPI::Models::HRIS::UpdateCompanyBenefitResponse]
-        #
         def update(benefit_id, params = {})
           parsed, options = FinchAPI::Models::HRIS::BenefitUpdateParams.dump_request(params)
           @client.request(
@@ -84,7 +81,6 @@ module FinchAPI
         #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
         #
         # @return [FinchAPI::SinglePage<FinchAPI::Models::HRIS::CompanyBenefit>]
-        #
         def list(params = {})
           @client.request(
             method: :get,
@@ -102,7 +98,6 @@ module FinchAPI
         #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
         #
         # @return [FinchAPI::SinglePage<FinchAPI::Models::HRIS::SupportedBenefit>]
-        #
         def list_supported_benefits(params = {})
           @client.request(
             method: :get,
@@ -114,7 +109,6 @@ module FinchAPI
         end
 
         # @param client [FinchAPI::Client]
-        #
         def initialize(client:)
           @client = client
           @individuals = FinchAPI::Resources::HRIS::Benefits::Individuals.new(client: client)

data/lib/finch-api/resources/hris/company.rb

@@ -11,7 +11,6 @@ module FinchAPI
         #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
         #
         # @return [FinchAPI::Models::HRIS::HRISCompany]
-        #
         def retrieve(params = {})
           @client.request(
             method: :get,
@@ -22,7 +21,6 @@ module FinchAPI
         end
 
         # @param client [FinchAPI::Client]
-        #
         def initialize(client:)
           @client = client
         end

data/lib/finch-api/resources/hris/directory.rb

@@ -15,7 +15,6 @@ module FinchAPI
         #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
         #
         # @return [FinchAPI::IndividualsPage<FinchAPI::Models::HRIS::IndividualInDirectory>]
-        #
         def list(params = {})
           parsed, options = FinchAPI::Models::HRIS::DirectoryListParams.dump_request(params)
           @client.request(
@@ -31,31 +30,9 @@ module FinchAPI
         # @deprecated use `list` instead
         #
         # Read company directory and organization structure
-        #
-        # @param params [FinchAPI::Models::HRIS::DirectoryListIndividualsParams, Hash{Symbol=>Object}] .
-        #
-        #   @option params [Integer] :limit Number of employees to return (defaults to all)
-        #
-        #   @option params [Integer] :offset Index to start from (defaults to 0)
-        #
-        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
-        #
-        # @return [FinchAPI::IndividualsPage<FinchAPI::Models::HRIS::IndividualInDirectory>]
-        #
-        def list_individuals(params = {})
-          parsed, options = FinchAPI::Models::HRIS::DirectoryListIndividualsParams.dump_request(params)
-          @client.request(
-            method: :get,
-            path: "employer/directory",
-            query: parsed,
-            page: FinchAPI::IndividualsPage,
-            model: FinchAPI::Models::HRIS::IndividualInDirectory,
-            options: options
-          )
-        end
+        alias_method :list_individuals, :list
 
         # @param client [FinchAPI::Client]
-        #
         def initialize(client:)
           @client = client
         end

data/lib/finch-api/resources/hris/documents.rb

@@ -4,8 +4,8 @@ module FinchAPI
   module Resources
     class HRIS
       class Documents
-        # **Beta:** This endpoint is in beta and may change.
-        #   Retrieve a list of company-wide documents.
+        # **Beta:** This endpoint is in beta and may change. Retrieve a list of
+        #   company-wide documents.
         #
         # @param params [FinchAPI::Models::HRIS::DocumentListParams, Hash{Symbol=>Object}] .
         #
@@ -22,7 +22,6 @@ module FinchAPI
         #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
         #
         # @return [FinchAPI::Models::HRIS::DocumentListResponse]
-        #
         def list(params = {})
           parsed, options = FinchAPI::Models::HRIS::DocumentListParams.dump_request(params)
           @client.request(
@@ -34,8 +33,8 @@ module FinchAPI
           )
         end
 
-        # **Beta:** This endpoint is in beta and may change.
-        #   Retrieve details of a specific document by its ID.
+        # **Beta:** This endpoint is in beta and may change. Retrieve details of a
+        #   specific document by its ID.
         #
         # @param document_id [String] The unique identifier of the document.
         #
@@ -44,7 +43,6 @@ module FinchAPI
         #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
         #
         # @return [FinchAPI::Models::HRIS::W42020, FinchAPI::Models::HRIS::W42005]
-        #
         def retreive(document_id, params = {})
           @client.request(
             method: :get,
@@ -55,7 +53,6 @@ module FinchAPI
         end
 
         # @param client [FinchAPI::Client]
-        #
         def initialize(client:)
           @client = client
         end

data/lib/finch-api/resources/hris/employments.rb

@@ -13,7 +13,6 @@ module FinchAPI
         #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
         #
         # @return [FinchAPI::ResponsesPage<FinchAPI::Models::HRIS::EmploymentDataResponse>]
-        #
         def retrieve_many(params)
           parsed, options = FinchAPI::Models::HRIS::EmploymentRetrieveManyParams.dump_request(params)
           @client.request(
@@ -27,7 +26,6 @@ module FinchAPI
         end
 
         # @param client [FinchAPI::Client]
-        #
         def initialize(client:)
           @client = client
         end

data/lib/finch-api/resources/hris/individuals.rb

@@ -15,7 +15,6 @@ module FinchAPI
         #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
         #
         # @return [FinchAPI::ResponsesPage<FinchAPI::Models::HRIS::IndividualResponse>]
-        #
         def retrieve_many(params = {})
           parsed, options = FinchAPI::Models::HRIS::IndividualRetrieveManyParams.dump_request(params)
           @client.request(
@@ -29,7 +28,6 @@ module FinchAPI
         end
 
         # @param client [FinchAPI::Client]
-        #
         def initialize(client:)
           @client = client
         end