terminal-shop 1.7.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66d749e7fcafbb6c6cb6edd0f9d3e380a207c09940b8c05617d2699005baa37e
-  data.tar.gz: a8e5b3220f034724bc107d7271675d004dd56ee604f79d2fa867c9f896602925
+  metadata.gz: bd8072a075bff0dc001f6aaabb37415cada6dfc11b82cb2362fd78400ef2fd69
+  data.tar.gz: 69a0df094ac931a412378137fe036c50b11d36ae628fe526e7392c985ef79466
 SHA512:
-  metadata.gz: f15b618ed726ffdac155669ed4b39a752b85296e3c06512c2ff058aec200e5aa5801c2264107cdf52523c66503386e4cb400f40fa1316394bef2a4e4a3ea1392
-  data.tar.gz: 8e7c4abf3f9827f0ac18f40b5d31f725c963b81e92c70ffe8e1b252f33d49f293b84d3ca89bd305e395bae1ed1487ed268c3c4bc400ff14e274bb9786d0d37b1
+  metadata.gz: b29c0d30aa9ec41963e5aa21d24e2821741868cb591fbec9fd1e015eef059ec06ae2adda746de1c2584b2b20e8babd6382058d85ae89e6948e4998b484c0042a
+  data.tar.gz: cb9eb1e052ec4b94b46523bc698b689fc425fd6ff66b036337138bdfa59108acddcf59ce088876db204eb61284e81643a825ddf43f0d74835c28f52000aef7f9

data/README.md

@@ -6,7 +6,7 @@ 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/terminal-shop/latest).
+Documentation for released of this gem can be found [on RubyDoc](https://gemdocs.org/gems/terminal-shop).
 
 The underlying REST API documentation can be found on [terminal.shop](https://terminal.shop/docs).
 
@@ -112,18 +112,34 @@ terminal.product.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 `TerminalShop::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 = ProductListParams.new
 
 terminal.product.list(**model)
 ```
 
+## Advanced
+
+### Concurrency & Connection Pooling
+
+The `TerminalShop::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, `TerminalShop::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.

data/lib/terminal-shop/base_client.rb

@@ -1,32 +1,31 @@
 # frozen_string_literal: true
 
 module TerminalShop
-  # @private
+  # @api private
   #
   # @abstract
-  #
   class BaseClient
     # from whatwg fetch spec
     MAX_REDIRECTS = 20
 
     # rubocop:disable Style/MutableConstant
-    PLATFORM_HEADERS = {
-      "x-stainless-arch" => TerminalShop::Util.arch,
-      "x-stainless-lang" => "ruby",
-      "x-stainless-os" => TerminalShop::Util.os,
-      "x-stainless-package-version" => TerminalShop::VERSION,
-      "x-stainless-runtime" => ::RUBY_ENGINE,
-      "x-stainless-runtime-version" => ::RUBY_ENGINE_VERSION
-    }
+    PLATFORM_HEADERS =
+      {
+        "x-stainless-arch" => TerminalShop::Util.arch,
+        "x-stainless-lang" => "ruby",
+        "x-stainless-os" => TerminalShop::Util.os,
+        "x-stainless-package-version" => TerminalShop::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 TerminalShop
         end
       end
 
-      # @private
+      # @api private
       #
       # @param status [Integer]
       # @param headers [Hash{String=>String}, Net::HTTPHeader]
       #
       # @return [Boolean]
-      #
       def should_retry?(status, headers:)
         coerced = TerminalShop::Util.coerce_boolean(headers["x-should-retry"])
         case [coerced, status]
@@ -65,7 +63,7 @@ module TerminalShop
         end
       end
 
-      # @private
+      # @api private
       #
       # @param request [Hash{Symbol=>Object}] .
       #
@@ -86,7 +84,6 @@ module TerminalShop
       # @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 TerminalShop
 
         request
       end
+
+      # @api private
+      #
+      # @param status [Integer, TerminalShop::APIConnectionError]
+      # @param stream [Enumerable, nil]
+      def reap_connection!(status, stream:)
+        case status
+        in (..199) | (300..499)
+          stream&.each { next }
+        in TerminalShop::APIConnectionError | (500..)
+          TerminalShop::Util.close_fused!(stream)
+        else
+        end
+      end
     end
 
-    # @private
-    #
+    # @api private
     # @return [TerminalShop::PooledNetRequester]
     attr_accessor :requester
 
-    # @private
+    # @api private
     #
     # @param base_url [String]
     # @param timeout [Float]
@@ -144,7 +154,6 @@ module TerminalShop
     # @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 TerminalShop
       @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 TerminalShop
     #
     #   @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)
 
@@ -271,13 +277,12 @@ module TerminalShop
       }
     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 TerminalShop
       (@initial_retry_delay * scale * jitter).clamp(0, @max_retry_delay)
     end
 
-    # @private
+    # @api private
     #
     # @param request [Hash{Symbol=>Object}] .
     #
@@ -322,7 +327,6 @@ module TerminalShop
     #
     # @raise [TerminalShop::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: TerminalShop::Util.monotonic_secs + timeout}
@@ -332,28 +336,23 @@ module TerminalShop
       end
 
       begin
-        response, stream = @requester.execute(input)
-        status = Integer(response.code)
+        status, response, stream = @requester.execute(input)
       rescue TerminalShop::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 TerminalShop::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 TerminalShop
       in TerminalShop::APIConnectionError if retry_count >= max_retries
         raise status
       in (400..) if retry_count >= max_retries || !self.class.should_retry?(status, headers: response)
-        decoded = TerminalShop::Util.decode_content(response, stream: stream, suppress_error: true)
-
-        if srv_fault
-          TerminalShop::Util.close_fused!(stream)
-        else
-          stream.each { next }
+        decoded = Kernel.then do
+          TerminalShop::Util.decode_content(response, stream: stream, suppress_error: true)
+        ensure
+          self.class.reap_connection!(status, stream: stream)
         end
 
         raise TerminalShop::APIStatusError.for(
@@ -379,13 +376,9 @@ module TerminalShop
           response: response
         )
       in (400..) | TerminalShop::APIConnectionError
-        delay = retry_delay(response, retry_count: retry_count)
+        self.class.reap_connection!(status, stream: stream)
 
-        if srv_fault
-          TerminalShop::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 TerminalShop
     #
     # @raise [TerminalShop::APIError]
     # @return [Object]
-    #
     def request(req)
       self.class.validate!(req)
       model = req.fetch(:model) { TerminalShop::Unknown }
@@ -445,7 +437,7 @@ module TerminalShop
       decoded = TerminalShop::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, page_data: decoded)
       else
@@ -455,7 +447,6 @@ module TerminalShop
     end
 
     # @return [String]
-    #
     def inspect
       # rubocop:disable Layout/LineLength
       base_url = TerminalShop::Util.unparse_uri(@base_url)