onebusaway-sdk 0.1.0.pre.alpha.205 → 0.1.0.pre.alpha.207

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 429ccc3f00c50a5b1de30b48e7f6b1b050bd1b17c397a6a752c8e9e46d469184
-  data.tar.gz: fa2d71c19e522f6baa5d9b11afdd5876707e2197791d3dff8c3e1d79c82029c2
+  metadata.gz: 4afa1a6c65b03950bbef375b58bd9c893852b92f1b6a8e5d6316d41a2aede517
+  data.tar.gz: 655727298bb0188df296939c458ee293bead7cb75aef8bf662344606ca4104d2
 SHA512:
-  metadata.gz: e86dc1479c36ee96fc7ac234fbd5df45f67590f5f3854a2bf20532e6624b8e423b56ae34002f7bdfa105dddbfab46c8df07b3ab2743ecdd442518fde9d2cd422
-  data.tar.gz: a13e694db85c0bae734ca456560d1c16e107bb92caadc322154c69e14a1a8d9a8456e76ea6f1060c93192c5d2c4179ffcde3b862e047844c424b4c92dd804a2d
+  metadata.gz: 33a1c96f96d85f03dbc5d7100dbb859128b27108502b2ae2577a6e5ffb31ec89a1fc22cbdbdd0d6655e0bc441f85244a1684fb31f7341e812d004d23a34a233b
+  data.tar.gz: 044ddde2208e8ee77177a94af1003e931106a47e19e7cb51c9d7cf56e5847236d76d8e382b3285f2d3a5700e14da4d5d53d29e46c85765e687fb6e69a29a823a

data/README.md

@@ -1,20 +1,18 @@
 # Onebusaway SDK Ruby API library
 
-The Onebusaway SDK Ruby library provides convenient access to the Onebusaway SDK REST API from any Ruby 3.0.0+
-application.
+The Onebusaway SDK Ruby library provides convenient access to the Onebusaway SDK 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/onebusaway-sdk/latest).
+Documentation for released of this gem can be found [on RubyDoc](https://gemdocs.org/gems/onebusaway-sdk).
 
 The underlying REST API documentation can be found on [developer.onebusaway.org](https://developer.onebusaway.org).
 
 ## 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 "onebusaway-sdk", git: "https://github.com/OneBusAway/ruby-sdk", 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 onebusaway-sdk
@@ -44,13 +41,13 @@ onebusaway_sdk = OnebusawaySDK::Client.new(
 )
 
 current_time = onebusaway_sdk.current_time.retrieve
+
+puts(current_time)
 ```
 
 ### 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
-`OnebusawaySDK::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 `OnebusawaySDK::Error` will be thrown:
 
 ```ruby
 begin
@@ -78,10 +75,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 +94,8 @@ onebusaway_sdk.current_time.retrieve(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 +109,28 @@ onebusaway_sdk = OnebusawaySDK::Client.new(
 onebusaway_sdk.current_time.retrieve(request_options: {timeout: 5})
 ```
 
+## Sorbet Support
+
+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 `OnebusawaySDK::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 = CurrentTimeRetrieveParams.new
+
+onebusaway_sdk.current_time.retrieve(**model)
+```
+
 ## 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/onebusaway-sdk/base_client.rb

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
 module OnebusawaySDK
-  # @private
+  # @api private
   #
   # @abstract
-  #
   class BaseClient
     # from whatwg fetch spec
     MAX_REDIRECTS = 20
@@ -21,14 +20,13 @@ module OnebusawaySDK
     # 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|
@@ -41,13 +39,12 @@ module OnebusawaySDK
         end
       end
 
-      # @private
+      # @api private
       #
       # @param status [Integer]
       # @param headers [Hash{String=>String}, Net::HTTPHeader]
       #
       # @return [Boolean]
-      #
       def should_retry?(status, headers:)
         coerced = OnebusawaySDK::Util.coerce_boolean(headers["x-should-retry"])
         case [coerced, status]
@@ -65,7 +62,7 @@ module OnebusawaySDK
         end
       end
 
-      # @private
+      # @api private
       #
       # @param request [Hash{Symbol=>Object}] .
       #
@@ -86,7 +83,6 @@ module OnebusawaySDK
       # @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 +124,27 @@ module OnebusawaySDK
 
         request
       end
+
+      # @api private
+      #
+      # @param status [Integer, OnebusawaySDK::APIConnectionError]
+      # @param stream [Enumerable, nil]
+      def reap_connection!(status, stream:)
+        case status
+        in (..199) | (300..499)
+          stream&.each { next }
+        in OnebusawaySDK::APIConnectionError | (500..)
+          OnebusawaySDK::Util.close_fused!(stream)
+        else
+        end
+      end
     end
 
-    # @private
-    #
+    # @api private
     # @return [OnebusawaySDK::PooledNetRequester]
     attr_accessor :requester
 
-    # @private
+    # @api private
     #
     # @param base_url [String]
     # @param timeout [Float]
@@ -144,7 +153,6 @@ module OnebusawaySDK
     # @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 +179,17 @@ module OnebusawaySDK
       @max_retry_delay = max_retry_delay
     end
 
-    # @private
+    # @api private
     #
     # @return [Hash{String=>String}]
-    #
     private def auth_query = {}
 
-    # @private
+    # @api private
     #
     # @return [String]
-    #
     private def generate_idempotency_key = "stainless-ruby-retry-#{SecureRandom.uuid}"
 
-    # @private
+    # @api private
     #
     # @param req [Hash{Symbol=>Object}] .
     #
@@ -201,6 +207,8 @@ module OnebusawaySDK
     #
     #   @option req [Class, nil] :page
     #
+    #   @option req [Class, nil] :stream
+    #
     #   @option req [OnebusawaySDK::Converter, Class, nil] :model
     #
     # @param opts [Hash{Symbol=>Object}] .
@@ -218,7 +226,6 @@ module OnebusawaySDK
     #   @option opts [Float, nil] :timeout
     #
     # @return [Hash{Symbol=>Object}]
-    #
     private def build_request(req, opts)
       method, uninterpolated_path = req.fetch_values(:method, :path)
 
@@ -243,8 +250,8 @@ module OnebusawaySDK
       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? }
@@ -268,13 +275,12 @@ module OnebusawaySDK
       }
     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 }
@@ -295,7 +301,7 @@ module OnebusawaySDK
       (@initial_retry_delay * scale * jitter).clamp(0, @max_retry_delay)
     end
 
-    # @private
+    # @api private
     #
     # @param request [Hash{Symbol=>Object}] .
     #
@@ -318,8 +324,7 @@ module OnebusawaySDK
     # @param send_retry_header [Boolean]
     #
     # @raise [OnebusawaySDK::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: OnebusawaySDK::Util.monotonic_secs + timeout}
@@ -329,28 +334,23 @@ module OnebusawaySDK
       end
 
       begin
-        response, stream = @requester.execute(input)
-        status = Integer(response.code)
+        status, response, stream = @requester.execute(input)
       rescue OnebusawaySDK::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
-        [response, stream]
+        [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 OnebusawaySDK::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,
@@ -359,13 +359,13 @@ module OnebusawaySDK
         )
       in OnebusawaySDK::APIConnectionError if retry_count >= max_retries
         raise status
-      in (400..) if retry_count >= max_retries || (response && !self.class.should_retry?(
-        status,
-        headers: response
-      ))
-        decoded = OnebusawaySDK::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
+          OnebusawaySDK::Util.decode_content(response, stream: stream, suppress_error: true)
+        ensure
+          self.class.reap_connection!(status, stream: stream)
+        end
 
-        stream.each { srv_fault ? break : next }
         raise OnebusawaySDK::APIStatusError.for(
           url: url,
           status: status,
@@ -374,9 +374,9 @@ module OnebusawaySDK
           response: response
         )
       in (400..) | OnebusawaySDK::APIConnectionError
-        delay = retry_delay(response, retry_count: retry_count)
+        self.class.reap_connection!(status, stream: stream)
 
-        stream&.each { srv_fault ? break : next }
+        delay = retry_delay(response, retry_count: retry_count)
         sleep(delay)
 
         send_request(
@@ -388,48 +388,6 @@ module OnebusawaySDK
       end
     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, Integer, Array<String, Integer, nil>, nil}, nil] :headers
-    #
-    #   @option req [Object, nil] :body
-    #
-    #   @option req [Symbol, nil] :unwrap
-    #
-    #   @option req [Class, nil] :page
-    #
-    #   @option req [OnebusawaySDK::Converter, Class, nil] :model
-    #
-    #   @option req [OnebusawaySDK::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 = OnebusawaySDK::Util.decode_content(headers, stream: stream)
-      unwrapped = OnebusawaySDK::Util.dig(decoded, req[:unwrap])
-
-      case [req[:page], req.fetch(:model, OnebusawaySDK::Unknown)]
-      in [Class => page, _]
-        page.new(client: self, req: req, headers: headers, unwrapped: unwrapped)
-      in [nil, Class | OnebusawaySDK::Converter => model]
-        OnebusawaySDK::Converter.coerce(model, unwrapped)
-      in [nil, nil]
-        unwrapped
-      end
-    end
-
     # Execute the request specified by `req`. This is the method that all resource
     #   methods call into.
     #
@@ -449,35 +407,49 @@ module OnebusawaySDK
     #
     #   @option req [Class, nil] :page
     #
+    #   @option req [Class, nil] :stream
+    #
     #   @option req [OnebusawaySDK::Converter, Class, nil] :model
     #
     #   @option req [OnebusawaySDK::RequestOptions, Hash{Symbol=>Object}, nil] :options
     #
     # @raise [OnebusawaySDK::APIError]
     # @return [Object]
-    #
     def request(req)
       self.class.validate!(req)
+      model = req.fetch(:model) { OnebusawaySDK::Unknown }
       opts = req[:options].to_h
       OnebusawaySDK::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 = OnebusawaySDK::Util.decode_content(response, stream: stream)
+      case req
+      in { stream: Class => st }
+        st.new(model: model, url: url, status: status, response: response, messages: decoded)
+      in { page: Class => page }
+        page.new(client: self, req: req, headers: response, page_data: decoded)
+      else
+        unwrapped = OnebusawaySDK::Util.dig(decoded, req[:unwrap])
+        OnebusawaySDK::Converter.coerce(model, unwrapped)
+      end
     end
 
     # @return [String]
-    #
     def inspect
+      # rubocop:disable Layout/LineLength
       base_url = OnebusawaySDK::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