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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75896ea053e81f2065eafd3e5dca608343251ec36a36f651f784fee694daf5a8
-  data.tar.gz: 548e74e04af38ba29427750afe087efe67582b4f25af60493a331abb656c74ac
+  metadata.gz: 4afa1a6c65b03950bbef375b58bd9c893852b92f1b6a8e5d6316d41a2aede517
+  data.tar.gz: 655727298bb0188df296939c458ee293bead7cb75aef8bf662344606ca4104d2
 SHA512:
-  metadata.gz: 63c34916992cb26b12ec8d3ad2a067608d5d2fd912e916cc6db8f340ba89a11f5ae3d03dfa2de2dee6bb2bf8f855f6313cda9a7c7aa7a1d76351d8200609ddc6
-  data.tar.gz: 33b8ddc65ca3dd17ba252facdb4515c8f41508b9ad1f0ecbee755957bb2dd42b25d108e795ecfc098339b22ea61c47174532679545971c88787e3153dc4ab6ab
+  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,12 +20,11 @@ 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, :stream, :model, :options]
         case req
@@ -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}] .
     #
@@ -220,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)
 
@@ -245,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? }
@@ -270,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 }
@@ -297,7 +301,7 @@ module OnebusawaySDK
       (@initial_retry_delay * scale * jitter).clamp(0, @max_retry_delay)
     end
 
-    # @private
+    # @api private
     #
     # @param request [Hash{Symbol=>Object}] .
     #
@@ -321,7 +325,6 @@ module OnebusawaySDK
     #
     # @raise [OnebusawaySDK::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: OnebusawaySDK::Util.monotonic_secs + timeout}
@@ -331,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
         [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,
@@ -362,12 +360,10 @@ module OnebusawaySDK
       in OnebusawaySDK::APIConnectionError if retry_count >= max_retries
         raise status
       in (400..) if retry_count >= max_retries || !self.class.should_retry?(status, headers: response)
-        decoded = OnebusawaySDK::Util.decode_content(response, stream: stream, suppress_error: true)
-
-        if srv_fault
-          OnebusawaySDK::Util.close_fused!(stream)
-        else
-          stream.each { next }
+        decoded = Kernel.then do
+          OnebusawaySDK::Util.decode_content(response, stream: stream, suppress_error: true)
+        ensure
+          self.class.reap_connection!(status, stream: stream)
         end
 
         raise OnebusawaySDK::APIStatusError.for(
@@ -378,13 +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)
 
-        if srv_fault
-          OnebusawaySDK::Util.close_fused!(stream)
-        else
-          stream&.each { next }
-        end
+        delay = retry_delay(response, retry_count: retry_count)
         sleep(delay)
 
         send_request(
@@ -423,7 +415,6 @@ module OnebusawaySDK
     #
     # @raise [OnebusawaySDK::APIError]
     # @return [Object]
-    #
     def request(req)
       self.class.validate!(req)
       model = req.fetch(:model) { OnebusawaySDK::Unknown }
@@ -446,7 +437,7 @@ module OnebusawaySDK
       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, unwrapped: decoded)
+        page.new(client: self, req: req, headers: response, page_data: decoded)
       else
         unwrapped = OnebusawaySDK::Util.dig(decoded, req[:unwrap])
         OnebusawaySDK::Converter.coerce(model, unwrapped)
@@ -454,10 +445,11 @@ module OnebusawaySDK
     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