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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 260e53c135137f098cf627393777300544df0b1dfd30489389af1b5703ce2acd
-  data.tar.gz: 219d07fcc8c72e40aea5bdcc41e3de9eefae11f4dad02c7fa269d55df370276f
+  metadata.gz: '0370233596fffe27112b67ca1690b835ad255607fa5cbe9916e93e6e2b866102'
+  data.tar.gz: abd43b5d6d449169a59044c49cd32a405953da7320c1028d8cc40b39f66c16f1
 SHA512:
-  metadata.gz: 3b4f44ef66f40d2dea1c354c256983ed4749aad16e978cacfee6513cccf895fa0ca8fb9bbb3455ca75c85820772cc92caca029f6578b522d941d742932dd8f32
-  data.tar.gz: 342f5568ee0508357aeef589fc05eba8f06b119b3935ef6b4c83a04c16cb686085feacbd8f6083d785e39de6dfb121dcb2d8c6107744e8f828b855100357ca39
+  metadata.gz: 2dad341274fdce9f06659285a16f30fbda6152928fcb9479323364a7f10b43ef53d1f9a0180c1e022d8c240dae07c3dda0eb4578483fdb8a4eaa169994a6b8cf
+  data.tar.gz: bde034ab00e4331713dc8f60048df9e58fa90e7eb97b784902b0e765bbf5331daf46ca880f459ce640838f1f09f6ac4bff3025571b17f237573c846be94c710e

data/README.md

@@ -1,20 +1,18 @@
 # Finch Ruby API library
 
-The Finch Ruby library provides convenient access to the Finch REST API from any Ruby 3.0.0+
-application.
+The Finch Ruby library provides convenient access to the Finch REST API from any Ruby 3.0.0+ application.
 
 It is generated with [Stainless](https://www.stainless.com/).
 
 ## Documentation
 
-Documentation for the most recent release of this gem can be found [on RubyDoc](https://gemdocs.org/gems/finch-api/latest).
+Documentation for released of this gem can be found [on RubyDoc](https://gemdocs.org/gems/finch-api).
 
 The underlying REST API documentation can be found on [developer.tryfinch.com](https://developer.tryfinch.com/).
 
 ## Installation
 
-To use this gem during the beta, install directly from GitHub with Bundler by
-adding the following to your application's `Gemfile`:
+To use this gem during the beta, install directly from GitHub with Bundler by adding the following to your application's `Gemfile`:
 
 ```ruby
 gem "finch-api", git: "https://github.com/Finch-API/finch-api-ruby", branch: "main"
@@ -26,8 +24,7 @@ To fetch an initial copy of the gem:
 bundle install
 ```
 
-To update the version used by your application when updates are pushed to
-GitHub:
+To update the version used by your application when updates are pushed to GitHub:
 
 ```sh
 bundle update finch-api
@@ -46,11 +43,28 @@ page = finch.hris.directory.list
 puts(page.id)
 ```
 
+### Pagination
+
+List methods in the Finch API are paginated.
+
+This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
+
+```ruby
+page = finch.hris.directory.list
+
+# Fetch single item from page.
+directory = page.individuals[0]
+puts(directory.id)
+
+# Automatically fetches more pages as needed.
+page.auto_paging_each do |directory|
+  puts(directory.id)
+end
+```
+
 ### Errors
 
-When the library is unable to connect to the API, or if the API returns a
-non-success status code (i.e., 4xx or 5xx response), a subclass of
-`FinchAPI::Error` will be thrown:
+When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `FinchAPI::Error` will be thrown:
 
 ```ruby
 begin
@@ -78,10 +92,9 @@ Error codes are as followed:
 
 ### Retries
 
-Certain errors will be automatically retried 2 times by default, with a short
-exponential backoff. Connection errors (for example, due to a network
-connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors,
-and timeouts will all be retried by default.
+Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
+
+Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
 
 You can use the `max_retries` option to configure or disable this:
 
@@ -98,8 +111,8 @@ finch.hris.directory.list(request_options: {max_retries: 5})
 ### Timeouts
 
 By default, requests will time out after 60 seconds.
-Timeouts are applied separately to the initial connection and the overall request time,
-so in some cases a request could wait 2\*timeout seconds before it fails.
+
+Timeouts are applied separately to the initial connection and the overall request time, so in some cases a request could wait 2\*timeout seconds before it fails.
 
 You can use the `timeout` option to configure or disable this:
 
@@ -113,12 +126,42 @@ finch = FinchAPI::Client.new(
 finch.hris.directory.list(request_options: {timeout: 5})
 ```
 
+## Sorbet Support
+
+**This library emits an intentional warning under the [`tapioca` toolchain](https://github.com/Shopify/tapioca)**. This is normal, and does not impact functionality.
+
+This library is written with [Sorbet type definitions](https://sorbet.org/docs/rbi). However, there is no runtime dependency on the `sorbet-runtime`.
+
+What this means is that while you can use Sorbet to type check your code statically, and benefit from the [Sorbet Language Server](https://sorbet.org/docs/lsp) in your editor, there is no runtime type checking and execution overhead from Sorbet itself.
+
+Due to limitations with the Sorbet type system, where a method otherwise can take an instance of `FinchAPI::BaseModel` class, you will need to use the `**` splat operator to pass the arguments:
+
+Please follow Sorbet's [setup guides](https://sorbet.org/docs/adopting) for best experience.
+
+```ruby
+model = DirectoryListParams.new
+
+finch.hris.directory.list(**model)
+```
+
+## Advanced
+
+### Concurrency & Connection Pooling
+
+The `FinchAPI::Client` instances are thread-safe, and should be re-used across multiple threads. By default, each `Client` have their own HTTP connection pool, with a maximum number of connections equal to thread count.
+
+When the maximum number of connections has been checked out from the connection pool, the `Client` will wait for an in use connection to become available. The queue time for this mechanism is accounted for by the per-request timeout.
+
+Unless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.
+
+Currently, `FinchAPI::Client` instances are only fork-safe if there are no in-flight HTTP requests.
+
 ## Versioning
 
-This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the
-library is in initial development and has a major version of `0`, APIs may change
-at any time.
+This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.
+
+This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.
 
 ## Requirements
 
-Ruby 3.0 or higher.
+Ruby 3.0.0 or higher.

data/lib/finch-api/base_client.rb

@@ -1,32 +1,31 @@
 # frozen_string_literal: true
 
 module FinchAPI
-  # @private
+  # @api private
   #
   # @abstract
-  #
   class BaseClient
     # from whatwg fetch spec
     MAX_REDIRECTS = 20
 
     # rubocop:disable Style/MutableConstant
-    PLATFORM_HEADERS = {
-      "x-stainless-arch" => FinchAPI::Util.arch,
-      "x-stainless-lang" => "ruby",
-      "x-stainless-os" => FinchAPI::Util.os,
-      "x-stainless-package-version" => FinchAPI::VERSION,
-      "x-stainless-runtime" => ::RUBY_ENGINE,
-      "x-stainless-runtime-version" => ::RUBY_ENGINE_VERSION
-    }
+    PLATFORM_HEADERS =
+      {
+        "x-stainless-arch" => FinchAPI::Util.arch,
+        "x-stainless-lang" => "ruby",
+        "x-stainless-os" => FinchAPI::Util.os,
+        "x-stainless-package-version" => FinchAPI::VERSION,
+        "x-stainless-runtime" => ::RUBY_ENGINE,
+        "x-stainless-runtime-version" => ::RUBY_ENGINE_VERSION
+      }
     # rubocop:enable Style/MutableConstant
 
     class << self
-      # @private
+      # @api private
       #
       # @param req [Hash{Symbol=>Object}]
       #
       # @raise [ArgumentError]
-      #
       def validate!(req)
         keys = [:method, :path, :query, :headers, :body, :unwrap, :page, :stream, :model, :options]
         case req
@@ -41,13 +40,12 @@ module FinchAPI
         end
       end
 
-      # @private
+      # @api private
       #
       # @param status [Integer]
       # @param headers [Hash{String=>String}, Net::HTTPHeader]
       #
       # @return [Boolean]
-      #
       def should_retry?(status, headers:)
         coerced = FinchAPI::Util.coerce_boolean(headers["x-should-retry"])
         case [coerced, status]
@@ -65,7 +63,7 @@ module FinchAPI
         end
       end
 
-      # @private
+      # @api private
       #
       # @param request [Hash{Symbol=>Object}] .
       #
@@ -86,7 +84,6 @@ module FinchAPI
       # @param response_headers [Hash{String=>String}, Net::HTTPHeader]
       #
       # @return [Hash{Symbol=>Object}]
-      #
       def follow_redirect(request, status:, response_headers:)
         method, url, headers = request.fetch_values(:method, :url, :headers)
         location =
@@ -128,14 +125,27 @@ module FinchAPI
 
         request
       end
+
+      # @api private
+      #
+      # @param status [Integer, FinchAPI::APIConnectionError]
+      # @param stream [Enumerable, nil]
+      def reap_connection!(status, stream:)
+        case status
+        in (..199) | (300..499)
+          stream&.each { next }
+        in FinchAPI::APIConnectionError | (500..)
+          FinchAPI::Util.close_fused!(stream)
+        else
+        end
+      end
     end
 
-    # @private
-    #
+    # @api private
     # @return [FinchAPI::PooledNetRequester]
     attr_accessor :requester
 
-    # @private
+    # @api private
     #
     # @param base_url [String]
     # @param timeout [Float]
@@ -144,7 +154,6 @@ module FinchAPI
     # @param max_retry_delay [Float]
     # @param headers [Hash{String=>String, Integer, Array<String, Integer, nil>, nil}]
     # @param idempotency_header [String, nil]
-    #
     def initialize(
       base_url:,
       timeout: 0.0,
@@ -171,19 +180,17 @@ module FinchAPI
       @max_retry_delay = max_retry_delay
     end
 
-    # @private
+    # @api private
     #
     # @return [Hash{String=>String}]
-    #
     private def auth_headers = {}
 
-    # @private
+    # @api private
     #
     # @return [String]
-    #
     private def generate_idempotency_key = "stainless-ruby-retry-#{SecureRandom.uuid}"
 
-    # @private
+    # @api private
     #
     # @param req [Hash{Symbol=>Object}] .
     #
@@ -213,14 +220,13 @@ module FinchAPI
     #
     #   @option opts [Hash{String=>String, nil}, nil] :extra_headers
     #
-    #   @option opts [Hash{Symbol=>Object}, nil] :extra_body
+    #   @option opts [Object, nil] :extra_body
     #
     #   @option opts [Integer, nil] :max_retries
     #
     #   @option opts [Float, nil] :timeout
     #
     # @return [Hash{Symbol=>Object}]
-    #
     private def build_request(req, opts)
       method, uninterpolated_path = req.fetch_values(:method, :path)
 
@@ -246,8 +252,8 @@ module FinchAPI
       end
 
       timeout = opts.fetch(:timeout, @timeout).to_f.clamp((0..))
-      unless headers.key?("x-stainless-read-timeout") || timeout.zero?
-        headers["x-stainless-read-timeout"] = timeout.to_s
+      unless headers.key?("x-stainless-timeout") || timeout.zero?
+        headers["x-stainless-timeout"] = timeout.to_s
       end
 
       headers.reject! { |_, v| v.to_s.empty? }
@@ -271,13 +277,12 @@ module FinchAPI
       }
     end
 
-    # @private
+    # @api private
     #
     # @param headers [Hash{String=>String}]
     # @param retry_count [Integer]
     #
     # @return [Float]
-    #
     private def retry_delay(headers, retry_count:)
       # Non-standard extension
       span = Float(headers["retry-after-ms"], exception: false)&.then { _1 / 1000 }
@@ -298,7 +303,7 @@ module FinchAPI
       (@initial_retry_delay * scale * jitter).clamp(0, @max_retry_delay)
     end
 
-    # @private
+    # @api private
     #
     # @param request [Hash{Symbol=>Object}] .
     #
@@ -322,7 +327,6 @@ module FinchAPI
     #
     # @raise [FinchAPI::APIError]
     # @return [Array(Integer, Net::HTTPResponse, Enumerable)]
-    #
     private def send_request(request, redirect_count:, retry_count:, send_retry_header:)
       url, headers, max_retries, timeout = request.fetch_values(:url, :headers, :max_retries, :timeout)
       input = {**request.except(:timeout), deadline: FinchAPI::Util.monotonic_secs + timeout}
@@ -332,28 +336,23 @@ module FinchAPI
       end
 
       begin
-        response, stream = @requester.execute(input)
-        status = Integer(response.code)
+        status, response, stream = @requester.execute(input)
       rescue FinchAPI::APIConnectionError => e
         status = e
       end
 
-      # normally we want to drain the response body and reuse the HTTP session by clearing the socket buffers
-      # unless we hit a server error
-      srv_fault = (500...).include?(status)
-
       case status
       in ..299
         [status, response, stream]
       in 300..399 if redirect_count >= self.class::MAX_REDIRECTS
-        message = "Failed to complete the request within #{self.class::MAX_REDIRECTS} redirects."
+        self.class.reap_connection!(status, stream: stream)
 
-        stream.each { next }
+        message = "Failed to complete the request within #{self.class::MAX_REDIRECTS} redirects."
         raise FinchAPI::APIConnectionError.new(url: url, message: message)
       in 300..399
-        request = self.class.follow_redirect(request, status: status, response_headers: response)
+        self.class.reap_connection!(status, stream: stream)
 
-        stream.each { next }
+        request = self.class.follow_redirect(request, status: status, response_headers: response)
         send_request(
           request,
           redirect_count: redirect_count + 1,
@@ -363,12 +362,10 @@ module FinchAPI
       in FinchAPI::APIConnectionError if retry_count >= max_retries
         raise status
       in (400..) if retry_count >= max_retries || !self.class.should_retry?(status, headers: response)
-        decoded = FinchAPI::Util.decode_content(response, stream: stream, suppress_error: true)
-
-        if srv_fault
-          FinchAPI::Util.close_fused!(stream)
-        else
-          stream.each { next }
+        decoded = Kernel.then do
+          FinchAPI::Util.decode_content(response, stream: stream, suppress_error: true)
+        ensure
+          self.class.reap_connection!(status, stream: stream)
         end
 
         raise FinchAPI::APIStatusError.for(
@@ -379,13 +376,9 @@ module FinchAPI
           response: response
         )
       in (400..) | FinchAPI::APIConnectionError
-        delay = retry_delay(response, retry_count: retry_count)
+        self.class.reap_connection!(status, stream: stream)
 
-        if srv_fault
-          FinchAPI::Util.close_fused!(stream)
-        else
-          stream&.each { next }
-        end
+        delay = retry_delay(response, retry_count: retry_count)
         sleep(delay)
 
         send_request(
@@ -424,7 +417,6 @@ module FinchAPI
     #
     # @raise [FinchAPI::APIError]
     # @return [Object]
-    #
     def request(req)
       self.class.validate!(req)
       model = req.fetch(:model) { FinchAPI::Unknown }
@@ -445,9 +437,9 @@ module FinchAPI
       decoded = FinchAPI::Util.decode_content(response, stream: stream)
       case req
       in { stream: Class => st }
-        st.new(model: model, url: url, status: status, response: response, messages: decoded)
+        st.new(model: model, url: url, status: status, response: response, stream: decoded)
       in { page: Class => page }
-        page.new(client: self, req: req, headers: response, unwrapped: decoded)
+        page.new(client: self, req: req, headers: response, page_data: decoded)
       else
         unwrapped = FinchAPI::Util.dig(decoded, req[:unwrap])
         FinchAPI::Converter.coerce(model, unwrapped)
@@ -455,10 +447,11 @@ module FinchAPI
     end
 
     # @return [String]
-    #
     def inspect
+      # rubocop:disable Layout/LineLength
       base_url = FinchAPI::Util.unparse_uri(@base_url)
       "#<#{self.class.name}:0x#{object_id.to_s(16)} base_url=#{base_url} max_retries=#{@max_retries} timeout=#{@timeout}>"
+      # rubocop:enable Layout/LineLength
     end
   end
 end