modern_treasury 0.1.0.pre.alpha.15 → 0.1.0.pre.alpha.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 532a13898e83bd67cf04e925798b3650896608d5ff442dfa914de2863283f185
-  data.tar.gz: 1339f144efd62f1d6a8bf6d18872dece722854dae0e620133c47d62841ecac7a
+  metadata.gz: 982153c7e4a473fd98806a6a918c95e9d2c4089a8a078c3d0e9741cb6882cd3e
+  data.tar.gz: d76a8e63ff7c9359878ceef73ab83a5e709e606ac2a2a106d881130f426106bc
 SHA512:
-  metadata.gz: 7df9bb854141f00220a0e6520e7721593e14fc1d2e37053f145582e438beeb4d944f993fe3e7fc46fe78bc6ca9990db83fd6287fea746d5e949241f4545f5728
-  data.tar.gz: 7ba3abad5876a55d1b58c949ccaf88c0d9d0d4b5928d39e4d33f97c5e578f4b8d8317d5767490749855f1ae7856786834ad474b377853f850afb7a90929b82d2
+  metadata.gz: bdc2dcda7b64d7749815a72511cc0d3221d382c25358486ee2aa046c9df2f2ace210892069a298036f52391eae6392c4a626d22fae377e5d1f826a13925328d8
+  data.tar.gz: c012c05a94e1c98227696be30cc8b0bbbe40c4c7da42045ace1f0d8f0fed2d03c13140b426f91d7db5f4e0709a6c477997fff31573a122516f5cd8cd73b20c82

data/README.md

@@ -1,18 +1,16 @@
 # Modern Treasury Ruby API library
 
-The Modern Treasury Ruby library provides convenient access to the Modern Treasury REST API from any Ruby 3.0.0+
-application.
+The Modern Treasury Ruby library provides convenient access to the Modern Treasury REST API from any Ruby 3.0.0+ application.
 
 ## Documentation
 
-Documentation for the most recent release of this gem can be found [on RubyDoc](https://gemdocs.org/gems/modern_treasury/latest).
+Documentation for released of this gem can be found [on RubyDoc](https://gemdocs.org/gems/modern_treasury).
 
 The underlying REST API documentation can be found on [docs.moderntreasury.com](https://docs.moderntreasury.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 "modern_treasury", git: "https://github.com/Modern-Treasury/modern-treasury-ruby", branch: "main"
@@ -24,8 +22,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 modern_treasury
@@ -47,11 +44,28 @@ counterparty = modern_treasury.counterparties.create(name: "my first counterpart
 puts(counterparty.id)
 ```
 
+### Pagination
+
+List methods in the Modern Treasury 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 = modern_treasury.counterparties.list
+
+# Fetch single item from page.
+counterparty = page.items[0]
+puts(counterparty.id)
+
+# Automatically fetches more pages as needed.
+page.auto_paging_each do |counterparty|
+  puts(counterparty.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
-`ModernTreasury::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 `ModernTreasury::Error` will be thrown:
 
 ```ruby
 begin
@@ -79,10 +93,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:
 
@@ -99,8 +112,8 @@ modern_treasury.counterparties.create(name: "my first counterparty", request_opt
 ### 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:
 
@@ -114,12 +127,42 @@ modern_treasury = ModernTreasury::Client.new(
 modern_treasury.counterparties.create(name: "my first counterparty", 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 `ModernTreasury::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 = CounterpartyCreateParams.new(name: "my first counterparty")
+
+modern_treasury.counterparties.create(**model)
+```
+
+## Advanced
+
+### Concurrency & Connection Pooling
+
+The `ModernTreasury::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, `ModernTreasury::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/modern_treasury/base_client.rb

@@ -1,23 +1,33 @@
 # frozen_string_literal: true
 
 module ModernTreasury
-  # @private
+  # @api private
   #
   # @abstract
-  #
   class BaseClient
     # from whatwg fetch spec
     MAX_REDIRECTS = 20
 
+    # rubocop:disable Style/MutableConstant
+    PLATFORM_HEADERS =
+      {
+        "x-stainless-arch" => ModernTreasury::Util.arch,
+        "x-stainless-lang" => "ruby",
+        "x-stainless-os" => ModernTreasury::Util.os,
+        "x-stainless-package-version" => ModernTreasury::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, :model, :options]
+        keys = [:method, :path, :query, :headers, :body, :unwrap, :page, :stream, :model, :options]
         case req
         in Hash
           req.each_key do |k|
@@ -30,13 +40,12 @@ module ModernTreasury
         end
       end
 
-      # @private
+      # @api private
       #
       # @param status [Integer]
       # @param headers [Hash{String=>String}, Net::HTTPHeader]
       #
       # @return [Boolean]
-      #
       def should_retry?(status, headers:)
         coerced = ModernTreasury::Util.coerce_boolean(headers["x-should-retry"])
         case [coerced, status]
@@ -54,7 +63,7 @@ module ModernTreasury
         end
       end
 
-      # @private
+      # @api private
       #
       # @param request [Hash{Symbol=>Object}] .
       #
@@ -66,8 +75,6 @@ module ModernTreasury
       #
       #   @option request [Object] :body
       #
-      #   @option request [Boolean] :streaming
-      #
       #   @option request [Integer] :max_retries
       #
       #   @option request [Float] :timeout
@@ -77,19 +84,16 @@ module ModernTreasury
       # @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 =
-          ModernTreasury::Util.suppress(ArgumentError) do
+          Kernel.then do
             URI.join(url, response_headers["location"])
+          rescue ArgumentError
+            message = "Server responded with status #{status} but no valid location header."
+            raise ModernTreasury::APIConnectionError.new(url: url, message: message)
           end
 
-        unless location
-          message = "Server responded with status #{status} but no valid location header."
-          raise ModernTreasury::APIConnectionError.new(url: url, message: message)
-        end
-
         request = {**request, url: location}
 
         case [url.scheme, location.scheme]
@@ -121,23 +125,35 @@ module ModernTreasury
 
         request
       end
+
+      # @api private
+      #
+      # @param status [Integer, ModernTreasury::APIConnectionError]
+      # @param stream [Enumerable, nil]
+      def reap_connection!(status, stream:)
+        case status
+        in (..199) | (300..499)
+          stream&.each { next }
+        in ModernTreasury::APIConnectionError | (500..)
+          ModernTreasury::Util.close_fused!(stream)
+        else
+        end
+      end
     end
 
-    # @private
-    #
+    # @api private
     # @return [ModernTreasury::PooledNetRequester]
     attr_accessor :requester
 
-    # @private
+    # @api private
     #
     # @param base_url [String]
     # @param timeout [Float]
     # @param max_retries [Integer]
     # @param initial_retry_delay [Float]
     # @param max_retry_delay [Float]
-    # @param headers [Hash{String=>String, nil}]
+    # @param headers [Hash{String=>String, Integer, Array<String, Integer, nil>, nil}]
     # @param idempotency_header [String, nil]
-    #
     def initialize(
       base_url:,
       timeout: 0.0,
@@ -149,13 +165,10 @@ module ModernTreasury
     )
       @requester = ModernTreasury::PooledNetRequester.new
       @headers = ModernTreasury::Util.normalized_headers(
+        self.class::PLATFORM_HEADERS,
         {
-          "X-Stainless-Lang" => "ruby",
-          "X-Stainless-Package-Version" => ModernTreasury::VERSION,
-          "X-Stainless-Runtime" => RUBY_ENGINE,
-          "X-Stainless-Runtime-Version" => RUBY_ENGINE_VERSION,
-          "Content-Type" => "application/json",
-          "Accept" => "application/json"
+          "accept" => "application/json",
+          "content-type" => "application/json"
         },
         headers
       )
@@ -167,19 +180,17 @@ module ModernTreasury
       @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}] .
     #
@@ -189,7 +200,7 @@ module ModernTreasury
     #
     #   @option req [Hash{String=>Array<String>, String, nil}, nil] :query
     #
-    #   @option req [Hash{String=>String, nil}, nil] :headers
+    #   @option req [Hash{String=>String, Integer, Array<String, Integer, nil>, nil}, nil] :headers
     #
     #   @option req [Object, nil] :body
     #
@@ -197,6 +208,8 @@ module ModernTreasury
     #
     #   @option req [Class, nil] :page
     #
+    #   @option req [Class, nil] :stream
+    #
     #   @option req [ModernTreasury::Converter, Class, nil] :model
     #
     # @param opts [Hash{Symbol=>Object}] .
@@ -207,23 +220,19 @@ module ModernTreasury
     #
     #   @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)
 
       path = ModernTreasury::Util.interpolate_path(uninterpolated_path)
 
-      query = ModernTreasury::Util.deep_merge(
-        req[:query].to_h,
-        opts[:extra_query].to_h
-      )
+      query = ModernTreasury::Util.deep_merge(req[:query].to_h, opts[:extra_query].to_h)
 
       headers = ModernTreasury::Util.normalized_headers(
         @headers,
@@ -243,8 +252,8 @@ module ModernTreasury
       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? }
@@ -263,19 +272,17 @@ module ModernTreasury
         url: ModernTreasury::Util.join_parsed_uri(@base_url, {**req, path: path, query: query}),
         headers: headers,
         body: encoded,
-        streaming: false,
         max_retries: opts.fetch(:max_retries, @max_retries),
         timeout: timeout
       }
     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 }
@@ -284,8 +291,10 @@ module ModernTreasury
       retry_header = headers["retry-after"]
       return span if (span = Float(retry_header, exception: false))
 
-      span = retry_header && ModernTreasury::Util.suppress(ArgumentError) do
-        Time.httpdate(retry_header) - Time.now
+      span = retry_header&.then do
+        Time.httpdate(_1) - Time.now
+      rescue ArgumentError
+        nil
       end
       return span if span
 
@@ -294,7 +303,7 @@ module ModernTreasury
       (@initial_retry_delay * scale * jitter).clamp(0, @max_retry_delay)
     end
 
-    # @private
+    # @api private
     #
     # @param request [Hash{Symbol=>Object}] .
     #
@@ -306,8 +315,6 @@ module ModernTreasury
     #
     #   @option request [Object] :body
     #
-    #   @option request [Boolean] :streaming
-    #
     #   @option request [Integer] :max_retries
     #
     #   @option request [Float] :timeout
@@ -319,8 +326,7 @@ module ModernTreasury
     # @param send_retry_header [Boolean]
     #
     # @raise [ModernTreasury::APIError]
-    # @return [Array(Net::HTTPResponse, Enumerable)]
-    #
+    # @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: ModernTreasury::Util.monotonic_secs + timeout}
@@ -330,19 +336,22 @@ module ModernTreasury
       end
 
       begin
-        response, stream = @requester.execute(input)
-        status = Integer(response.code)
+        status, response, stream = @requester.execute(input)
       rescue ModernTreasury::APIConnectionError => e
         status = e
       end
 
       case status
       in ..299
-        [response, stream]
-      in 300..399 if redirect_count >= MAX_REDIRECTS
-        message = "Failed to complete the request within #{MAX_REDIRECTS} redirects."
+        [status, response, stream]
+      in 300..399 if redirect_count >= self.class::MAX_REDIRECTS
+        self.class.reap_connection!(status, stream: stream)
+
+        message = "Failed to complete the request within #{self.class::MAX_REDIRECTS} redirects."
         raise ModernTreasury::APIConnectionError.new(url: url, message: message)
       in 300..399
+        self.class.reap_connection!(status, stream: stream)
+
         request = self.class.follow_redirect(request, status: status, response_headers: response)
         send_request(
           request,
@@ -352,11 +361,12 @@ module ModernTreasury
         )
       in ModernTreasury::APIConnectionError if retry_count >= max_retries
         raise status
-      in (400..) if retry_count >= max_retries || (response && !self.class.should_retry?(
-        status,
-        headers: response
-      ))
-        decoded = ModernTreasury::Util.decode_content(response, stream: stream, suppress_error: true)
+      in (400..) if retry_count >= max_retries || !self.class.should_retry?(status, headers: response)
+        decoded = Kernel.then do
+          ModernTreasury::Util.decode_content(response, stream: stream, suppress_error: true)
+        ensure
+          self.class.reap_connection!(status, stream: stream)
+        end
 
         raise ModernTreasury::APIStatusError.for(
           url: url,
@@ -366,6 +376,8 @@ module ModernTreasury
           response: response
         )
       in (400..) | ModernTreasury::APIConnectionError
+        self.class.reap_connection!(status, stream: stream)
+
         delay = retry_delay(response, retry_count: retry_count)
         sleep(delay)
 
@@ -376,50 +388,6 @@ module ModernTreasury
           send_retry_header: send_retry_header
         )
       end
-    ensure
-      stream&.each { break } unless status.is_a?(Integer) && status < 300
-    end
-
-    # @private
-    #
-    # @param req [Hash{Symbol=>Object}] .
-    #
-    #   @option req [Symbol] :method
-    #
-    #   @option req [String, Array<String>] :path
-    #
-    #   @option req [Hash{String=>Array<String>, String, nil}, nil] :query
-    #
-    #   @option req [Hash{String=>String, nil}, nil] :headers
-    #
-    #   @option req [Object, nil] :body
-    #
-    #   @option req [Symbol, nil] :unwrap
-    #
-    #   @option req [Class, nil] :page
-    #
-    #   @option req [ModernTreasury::Converter, Class, nil] :model
-    #
-    #   @option req [ModernTreasury::RequestOptions, Hash{Symbol=>Object}, nil] :options
-    #
-    # @param headers [Hash{String=>String}, Net::HTTPHeader]
-    #
-    # @param stream [Enumerable]
-    #
-    # @return [Object]
-    #
-    private def parse_response(req, headers:, stream:)
-      decoded = ModernTreasury::Util.decode_content(headers, stream: stream)
-      unwrapped = ModernTreasury::Util.dig(decoded, req[:unwrap])
-
-      case [req[:page], req.fetch(:model, ModernTreasury::Unknown)]
-      in [Class => page, _]
-        page.new(client: self, req: req, headers: headers, unwrapped: unwrapped)
-      in [nil, Class | ModernTreasury::Converter => model]
-        ModernTreasury::Converter.coerce(model, unwrapped)
-      in [nil, nil]
-        unwrapped
-      end
     end
 
     # Execute the request specified by `req`. This is the method that all resource
@@ -433,7 +401,7 @@ module ModernTreasury
     #
     #   @option req [Hash{String=>Array<String>, String, nil}, nil] :query
     #
-    #   @option req [Hash{String=>String, nil}, nil] :headers
+    #   @option req [Hash{String=>String, Integer, Array<String, Integer, nil>, nil}, nil] :headers
     #
     #   @option req [Object, nil] :body
     #
@@ -441,35 +409,49 @@ module ModernTreasury
     #
     #   @option req [Class, nil] :page
     #
+    #   @option req [Class, nil] :stream
+    #
     #   @option req [ModernTreasury::Converter, Class, nil] :model
     #
     #   @option req [ModernTreasury::RequestOptions, Hash{Symbol=>Object}, nil] :options
     #
     # @raise [ModernTreasury::APIError]
     # @return [Object]
-    #
     def request(req)
       self.class.validate!(req)
+      model = req.fetch(:model) { ModernTreasury::Unknown }
       opts = req[:options].to_h
       ModernTreasury::RequestOptions.validate!(opts)
       request = build_request(req.except(:options), opts)
+      url = request.fetch(:url)
 
       # Don't send the current retry count in the headers if the caller modified the header defaults.
       send_retry_header = request.fetch(:headers)["x-stainless-retry-count"] == "0"
-      response, stream = send_request(
+      status, response, stream = send_request(
         request,
         redirect_count: 0,
         retry_count: 0,
         send_retry_header: send_retry_header
       )
-      parse_response(req, headers: response, stream: stream)
+
+      decoded = ModernTreasury::Util.decode_content(response, stream: stream)
+      case req
+      in { stream: Class => st }
+        st.new(model: model, url: url, status: status, response: response, stream: decoded)
+      in { page: Class => page }
+        page.new(client: self, req: req, headers: response, page_data: decoded)
+      else
+        unwrapped = ModernTreasury::Util.dig(decoded, req[:unwrap])
+        ModernTreasury::Converter.coerce(model, unwrapped)
+      end
     end
 
     # @return [String]
-    #
     def inspect
+      # rubocop:disable Layout/LineLength
       base_url = ModernTreasury::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