release: 0.1.0-alpha.28

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0-alpha.27"
+  ".": "0.1.0-alpha.28"
 }

.rubocop.yml

@@ -58,6 +58,11 @@ Layout/MultilineMethodParameterLineBreaks:
 Layout/SpaceInsideHashLiteralBraces:
   EnforcedStyle: no_space
 
+# This option occasionally mangles identifier names
+Lint/DeprecatedConstants:
+  Exclude:
+    - "**/*.rbi"
+
 # Fairly useful in tests for pattern assertions.
 Lint/EmptyInPattern:
   Exclude:

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.0-alpha.28 (2025-03-18)
+
+Full Changelog: [v0.1.0-alpha.27...v0.1.0-alpha.28](https://github.com/orbcorp/orb-ruby/compare/v0.1.0-alpha.27...v0.1.0-alpha.28)
+
+### ⚠ BREAKING CHANGES
+
+* **model:** base model should recursively store coerced base models ([#165](https://github.com/orbcorp/orb-ruby/issues/165))
+
+### Bug Fixes
+
+* **model:** base model should recursively store coerced base models ([#165](https://github.com/orbcorp/orb-ruby/issues/165)) ([da71413](https://github.com/orbcorp/orb-ruby/commit/da71413184f24adcd89ce5bf302077a29193c14c))
+
+
+### Chores
+
+* do not label modules as abstract ([#163](https://github.com/orbcorp/orb-ruby/issues/163)) ([ac4e54c](https://github.com/orbcorp/orb-ruby/commit/ac4e54cf7a68dae174ee27b6477fd5d1a6a6b98a))
+* **internal:** codegen related update ([#160](https://github.com/orbcorp/orb-ruby/issues/160)) ([2efe526](https://github.com/orbcorp/orb-ruby/commit/2efe526cc8937e1e6c3e334edc1f09ca0b0060d8))
+* **internal:** codegen related update ([#164](https://github.com/orbcorp/orb-ruby/issues/164)) ([8b4921d](https://github.com/orbcorp/orb-ruby/commit/8b4921d27329bfbb3d4a27c8105d3dfa963b744d))
+* use generics instead of overloading for sorbet type definitions ([#162](https://github.com/orbcorp/orb-ruby/issues/162)) ([9cec19b](https://github.com/orbcorp/orb-ruby/commit/9cec19b1e001799c2b69e68d37405a30d7f85432))
+
 ## 0.1.0-alpha.27 (2025-03-14)
 
 Full Changelog: [v0.1.0-alpha.26...v0.1.0-alpha.27](https://github.com/orbcorp/orb-ruby/compare/v0.1.0-alpha.26...v0.1.0-alpha.27)

Gemfile.lock

@@ -11,7 +11,7 @@ GIT
 PATH
   remote: .
   specs:
-    orb (0.1.0.pre.alpha.27)
+    orb (0.1.0.pre.alpha.28)
       connection_pool
 
 GEM

README.md

@@ -4,7 +4,7 @@ The Orb Ruby library provides convenient access to the Orb REST API from any Rub
 
 ## Documentation
 
-Documentation for the most recent release of this gem can be found [on RubyDoc](https://gemdocs.org/gems/orb/latest).
+Documentation for released of this gem can be found [on RubyDoc](https://gemdocs.org/gems/orb).
 
 The underlying REST API documentation can be found on [docs.withorb.com](https://docs.withorb.com/reference/api-reference).
 
@@ -142,6 +142,8 @@ What this means is that while you can use Sorbet to type check your code statica
 
 Due to limitations with the Sorbet type system, where a method otherwise can take an instance of `Orb::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 = CustomerCreateParams.new(email: "example-customer@withorb.com", name: "My Customer")
 

lib/orb/base_client.rb

@@ -124,6 +124,20 @@ def follow_redirect(request, status:, response_headers:)
 
         request
       end
+
+      # @api private
+      #
+      # @param status [Integer, Orb::APIConnectionError]
+      # @param stream [Enumerable, nil]
+      def reap_connection!(status, stream:)
+        case status
+        in (..199) | (300..499)
+          stream&.each { next }
+        in Orb::APIConnectionError | (500..)
+          Orb::Util.close_fused!(stream)
+        else
+        end
+      end
     end
 
     # @api private
@@ -321,28 +335,23 @@ def initialize(
       end
 
       begin
-        response, stream = @requester.execute(input)
-        status = Integer(response.code)
+        status, response, stream = @requester.execute(input)
       rescue Orb::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 Orb::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,
@@ -352,12 +361,10 @@ def initialize(
       in Orb::APIConnectionError if retry_count >= max_retries
         raise status
       in (400..) if retry_count >= max_retries || !self.class.should_retry?(status, headers: response)
-        decoded = Orb::Util.decode_content(response, stream: stream, suppress_error: true)
-
-        if srv_fault
-          Orb::Util.close_fused!(stream)
-        else
-          stream.each { next }
+        decoded = Kernel.then do
+          Orb::Util.decode_content(response, stream: stream, suppress_error: true)
+        ensure
+          self.class.reap_connection!(status, stream: stream)
         end
 
         raise Orb::APIStatusError.for(
@@ -368,13 +375,9 @@ def initialize(
           response: response
         )
       in (400..) | Orb::APIConnectionError
-        delay = retry_delay(response, retry_count: retry_count)
+        self.class.reap_connection!(status, stream: stream)
 
-        if srv_fault
-          Orb::Util.close_fused!(stream)
-        else
-          stream&.each { next }
-        end
+        delay = retry_delay(response, retry_count: retry_count)
         sleep(delay)
 
         send_request(

lib/orb/base_model.rb

@@ -2,8 +2,6 @@
 
 module Orb
   # @api private
-  #
-  # @abstract
   module Converter
     # rubocop:disable Lint/UnusedMethodArgument
 
@@ -915,6 +913,13 @@ def known_fields
         @known_fields ||= (self < Orb::BaseModel ? superclass.known_fields.dup : {})
       end
 
+      # @api private
+      #
+      # @return [Hash{Symbol=>Symbol}]
+      def reverse_map
+        @reverse_map ||= (self < Orb::BaseModel ? superclass.reverse_map.dup : {})
+      end
+
       # @api private
       #
       # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
@@ -958,7 +963,7 @@ def defaults = (@defaults ||= {})
         fallback = info[:const]
         defaults[name_sym] = fallback if required && !info[:nil?] && info.key?(:const)
 
-        key = info.fetch(:api_name, name_sym)
+        key = info[:api_name]&.tap { reverse_map[_1] = name_sym } || name_sym
         setter = "#{name_sym}="
 
         if known_fields.key?(name_sym)
@@ -1215,7 +1220,21 @@ def deconstruct_keys(keys)
     def initialize(data = {})
       case Orb::Util.coerce_hash(data)
       in Hash => coerced
-        @data = coerced.transform_keys(&:to_sym)
+        @data = coerced.to_h do |key, value|
+          name = key.to_sym
+          mapped = self.class.reverse_map.fetch(name, name)
+          type = self.class.fields[mapped]&.fetch(:type)
+          stored =
+            case [type, value]
+            in [Class, Hash] if type <= Orb::BaseModel
+              type.new(value)
+            in [Orb::ArrayOf, Array] | [Orb::HashOf, Hash]
+              type.coerce(value)
+            else
+              value
+            end
+          [name, stored]
+        end
       else
         raise ArgumentError.new("Expected a #{Hash} or #{Orb::BaseModel}, got #{data.inspect}")
       end

lib/orb/base_page.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 module Orb
-  # @abstract
-  #
   # @example
   # ```ruby
   # if page.has_next?
@@ -53,7 +51,7 @@
     # @param req [Hash{Symbol=>Object}]
     # @param headers [Hash{String=>String}, Net::HTTPHeader]
     # @param page_data [Object]
     def initialize(client:, req:, headers:, page_data:)
       @client = client
       @req = req
       super()

lib/orb/extern.rb

@@ -2,8 +2,6 @@
 
 module Orb
   # @api private
-  #
-  # @abstract
   module Extern
   end
 end

lib/orb/page.rb

@@ -68,7 +68,8 @@
     # @return [Orb::Page]
     def next_page
       unless next_page?
-        raise RuntimeError.new("No more pages available. Please check #next_page? before calling ##{__method__}")
+        message = "No more pages available. Please check #next_page? before calling ##{__method__}"
+        raise RuntimeError.new(message)
       end
 
       req = Orb::Util.deep_merge(@req, {query: {cursor: pagination_metadata&.next_cursor}})
@@ -90,7 +91,7 @@
 
     # @return [String]
     def inspect
       "#<#{self.class}:0x#{object_id.to_s(16)} data=#{data.inspect} pagination_metadata=#{pagination_metadata.inspect}>"
     end
 
     class PaginationMetadata < Orb::BaseModel

lib/orb/pooled_net_requester.rb

@@ -61,6 +61,7 @@ def build_request(request, &)
 
         case body
         in nil
+          nil
         in String
           req["content-length"] ||= body.bytesize.to_s unless req["transfer-encoding"]
           req.body_stream = Orb::Util::ReadIOAdapter.new(body, &)
@@ -79,17 +80,19 @@ def build_request(request, &)
     # @api private
     #
     # @param url [URI::Generic]
+    # @param deadline [Float]
     # @param blk [Proc]
-    private def with_pool(url, &)
+    private def with_pool(url, deadline:, &blk)
       origin = Orb::Util.uri_origin(url)
+      timeout = deadline - Orb::Util.monotonic_secs
       pool =
         @mutex.synchronize do
           @pools[origin] ||= ConnectionPool.new(size: @size) do
             self.class.connect(url)
           end
         end
 
-      pool.with(&)
+      pool.with(timeout: timeout, &blk)
     end
 
     # @api private
@@ -106,14 +109,14 @@ def build_request(request, &)
     #
     #   @option request [Float] :deadline
     #
-    # @return [Array(Net::HTTPResponse, Enumerable)]
+    # @return [Array(Integer, Net::HTTPResponse, Enumerable)]
     def execute(request)
       url, deadline = request.fetch_values(:url, :deadline)
 
       eof = false
       finished = false
       enum = Enumerator.new do |y|
-        with_pool(url) do |conn|
+        with_pool(url, deadline: deadline) do |conn|
           next if finished
 
           req = self.class.build_request(request) do
@@ -125,7 +128,7 @@ def execute(request)
 
           self.class.calibrate_socket_timeout(conn, deadline)
           conn.request(req) do |rsp|
-            y << [conn, rsp]
+            y << [conn, req, rsp]
             break if finished
 
             rsp.read_body do |bytes|
@@ -137,9 +140,11 @@ def execute(request)
             eof = true
           end
         end
+      rescue Timeout::Error
+        raise Orb::APITimeoutError
       end
 
-      conn, response = enum.next
+      conn, _, response = enum.next
       body = Orb::Util.fused_enum(enum, external: true) do
         finished = true
         tap do
@@ -149,7 +154,7 @@ def execute(request)
         end
         conn.finish if !eof && conn&.started?
       end
-      [response, (response.body = body)]
+      [Integer(response.code), response, (response.body = body)]
     end
 
     # @api private

lib/orb/request_options.rb

@@ -2,8 +2,6 @@
 
 module Orb
   # @api private
-  #
-  # @abstract
   module RequestParameters
     # @!parse
     #   # Options to specify HTTP behaviour for this request.

lib/orb/util.rb

@@ -57,7 +57,7 @@
       #
       # @param input [Object]
       #
-      # @return [Boolean, Object]
+      # @return [Boolean]
       def primitive?(input)
         case input
         in true | false | Integer | Float | Symbol | String
@@ -458,7 +458,7 @@
       # @param boundary [String]
       # @param key [Symbol, String]
       # @param val [Object]
       private def encode_multipart_formdata(y, boundary:, key:, val:)
         y << "--#{boundary}\r\n"
         y << "Content-Disposition: form-data"
         unless key.nil?
@@ -627,6 +627,8 @@
       #
       # @param enum [Enumerable, nil]
       # @param blk [Proc]
+      #
+      # @return [Enumerable]
       def chain_fused(enum, &blk)
         iter = Enumerator.new { blk.call(_1) }
         fused_enum(iter) { close_fused!(enum) }

lib/orb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Orb
-  VERSION = "0.1.0-alpha.27"
+  VERSION = "0.1.0-alpha.28"
 end

orb.gemspec

@@ -10,10 +10,10 @@
   s.email = "team@withorb.com"
   s.files = Dir["lib/**/*.rb", "rbi/**/*.rbi", "sig/**/*.rbs", "manifest.yaml"]
   s.extra_rdoc_files = ["README.md"]
   s.required_ruby_version = ">= 3.0.0"
   s.add_dependency "connection_pool"
-  s.homepage = "https://gemdocs.org/gems/orb/latest"
+  s.homepage = "https://gemdocs.org/gems/orb"
   s.metadata["homepage_uri"] = s.homepage
   s.metadata["source_code_uri"] = "https://github.com/orbcorp/orb-ruby"
   s.metadata["rubygems_mfa_required"] = "false"
 end

rbi/lib/orb/base_client.rbi

@@ -1,6 +1,7 @@
 # typed: strong
 
 module Orb
+  # @api private
   class BaseClient
     abstract!
 
@@ -67,6 +68,13 @@ module Orb
       end
       def follow_redirect(request, status:, response_headers:)
       end
+
+      # @api private
+      sig do
+        params(status: T.any(Integer, Orb::APIConnectionError), stream: T.nilable(T::Enumerable[String])).void
+      end
+      def reap_connection!(status, stream:)
+      end
     end
 
     sig { returns(T.anything) }