schematichq 1.5.2 → 1.5.4

data/lib/schematic/internal/http/base_request.rb

@@ -28,12 +28,42 @@ module Schematic
           @query.merge(additional_query)
         end
 
+        # @return [Hash] The additional body parameters from request options, keyed by wire-format name.
+        def additional_body_parameters
+          @request_options&.dig(:additional_body_parameters) || @request_options&.dig("additional_body_parameters") || {}
+        end
+
         # Child classes should implement:
         # - encode_headers: Returns the encoded HTTP request headers.
         # - encode_body: Returns the encoded HTTP request body.
 
         private
 
+        # Merges additional_body_parameters from request_options on top of the request body.
+        # Keys are used as-is (API wire-format names) and are normalized to strings so that a
+        # caller-supplied key always overrides the SDK-serialized field with the same name.
+        # When the body is nil the additional parameters become the body, except for GET and HEAD
+        # requests, which are sent without a body (the additional parameters are ignored). Bodies
+        # that are not hash-like (arrays, primitives) are returned unchanged.
+        # @param body [Object, nil] The request body.
+        # @return [Object, nil] The merged request body.
+        def merge_additional_body_parameters(body)
+          additional_body = additional_body_parameters
+          return body if additional_body.nil? || additional_body.empty?
+          return body if body.nil? && bodyless_method?
+
+          additional_body = additional_body.to_h.transform_keys(&:to_s)
+          return additional_body if body.nil?
+          return body if body.is_a?(::Array) || !body.respond_to?(:to_h)
+
+          body.to_h.transform_keys(&:to_s).merge(additional_body)
+        end
+
+        # @return [Boolean] Whether the request method is one that is sent without a body (GET, HEAD).
+        def bodyless_method?
+          %w[GET HEAD].include?(@method.to_s.upcase)
+        end
+
         # Merges additional_headers from request_options into sdk_headers, filtering out
         # any keys that collide with SDK-set or client-protected headers (case-insensitive).
         # @param sdk_headers [Hash] Headers set by the SDK for this request type.

data/lib/schematic/internal/http/raw_client.rb

@@ -47,6 +47,7 @@ module Schematic
           # Resolve auth headers once per request (not per retry) so token-based
           # providers refresh at most once here; static providers are cheap.
           auth_headers = resolve_auth_headers
+          timeout = request_timeout(request)
           attempt = 0
           response = nil
 
@@ -60,12 +61,12 @@ module Schematic
             )
 
             conn = connect(url)
-            conn.open_timeout = @timeout
-            conn.read_timeout = @timeout
-            conn.write_timeout = @timeout
-            conn.continue_timeout = @timeout
+            conn.open_timeout = timeout
+            conn.read_timeout = timeout
+            conn.write_timeout = timeout
+            conn.continue_timeout = timeout
 
-            response = conn.request(http_request)
+            response = wrap_transport_errors { conn.request(http_request) }
 
             break unless should_retry?(response, attempt)
 
@@ -77,6 +78,35 @@ module Schematic
           response
         end
 
+        # Socket-level `Errno` failures. Other `SystemCallError`s, such as file errors raised by a
+        # custom HTTP client, are not connection failures and propagate unchanged.
+        NETWORK_ERRNOS = [
+          Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ECONNABORTED, Errno::EPIPE,
+          Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::ENETDOWN, Errno::EHOSTDOWN,
+          Errno::EADDRNOTAVAIL
+        ].freeze
+
+        # Runs a single request attempt, re-raising transport failures as SDK errors so that
+        # rescuing `Errors::ApiError` covers them. The original exception is kept as `cause`.
+        # These failures are not retried: the server may already have processed the request.
+        # @return [Net::HTTPResponse] The HTTP response.
+        def wrap_transport_errors
+          yield
+        rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Errno::ETIMEDOUT => e
+          raise Schematic::Errors::TimeoutError, e.message
+        rescue EOFError, SocketError, OpenSSL::SSL::SSLError, *NETWORK_ERRNOS,
+               Net::ProtocolError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError => e
+          raise Schematic::Errors::ConnectionError, e.message
+        end
+
+        # @param request [Schematic::Internal::Http::BaseRequest] The HTTP request.
+        # @return [Float] The request's `timeout_in_seconds` option, or the client-level timeout.
+        def request_timeout(request)
+          options = request.request_options || {}
+          timeout = options.key?(:timeout_in_seconds) ? options[:timeout_in_seconds] : options["timeout_in_seconds"]
+          (timeout.nil? ? @timeout : timeout).to_f
+        end
+
         # The client-level header names that `additional_headers` must not replace: every default
         # header except the API's global headers, which are overridable per request.
         # @return [Array<Symbol, String>] The protected header names.

data/lib/schematic/internal/iterators/cursor_item_iterator.rb

@@ -10,11 +10,16 @@ module Schematic
       # @param item_field [Symbol] The field in API responses to extract the items to iterate over.
       # @param block [Proc] A block which is responsible for receiving a cursor to use and returning the given page from the API.
       # @return [Schematic::Internal::CursorItemIterator]
-      def initialize(initial_cursor:, cursor_field:, item_field:, &)
+      def initialize(initial_cursor:, cursor_field:, item_field:, &block)
         super()
         @item_field = item_field
-        @page_iterator = CursorPageIterator.new(initial_cursor:, cursor_field:, &)
+        @http_response = nil
+        get_page = track_http_responses(block)
+        @page_iterator = CursorPageIterator.new(initial_cursor:, cursor_field:, &get_page)
+        # Items are read through their own page cursor so that reading `pages` never skips items.
+        @item_pages = CursorPageIterator.new(initial_cursor:, cursor_field:, &get_page)
         @page = nil
+        @item_index = 0
       end
 
       # Returns the CursorPageIterator mediating access to the underlying API.

data/lib/schematic/internal/iterators/cursor_page_iterator.rb

@@ -17,45 +17,99 @@ module Schematic
       #   The block should return a two-element array: [parsed_page, raw_http_response].
       # @return [Schematic::Internal::CursorPageIterator]
       def initialize(initial_cursor:, cursor_field:, &block)
-        @need_initial_load = initial_cursor.nil?
-        @cursor = initial_cursor
+        @initial_cursor = initial_cursor
         @cursor_field = cursor_field
         @get_next_page = block
         @http_response = nil
+        @first_page_requested = false
+        @first_page = nil
+        rewind
       end
 
-      # Iterates over each page returned by the API.
+      # Sends the request for the first page now instead of on the first iteration, so an API error for that page
+      # is raised here. The page is kept, and every loop that starts from the first page reuses it instead of
+      # requesting it again. Does nothing if the first page was already requested.
       #
-      # @param block [Proc] The block which each retrieved page is yielded to.
+      # @return [self]
+      def load_first_page
+        return self if @first_page_requested
+
+        @first_page = fetch_page(@initial_cursor)
+        rewind
+        self
+      end
+
+      # Uses the first page that `other` loaded with `load_first_page`, unless this iterator already sent a request.
+      #
+      # @param other [Schematic::Internal::CursorPageIterator]
       # @return [NilClass]
+      def reuse_first_page(other)
+        return if @first_page_requested || other.first_page.nil?
+
+        @first_page = other.first_page
+        rewind
+      end
+
+      # Iterates over each page returned by the API, starting again from the first page on every call.
+      #
+      # @param block [Proc] The block which each retrieved page is yielded to.
+      # @return [NilClass, Enumerator] An Enumerator when no block is given.
       def each(&block)
+        return enum_for(:each) unless block_given?
+
+        rewind
         while (page = next_page)
           block.call(page)
         end
       end
 
+      # Resets page-by-page iteration (`next_page` / `next?`) to the first page.
+      #
+      # @return [NilClass]
+      def rewind
+        @need_initial_load = @initial_cursor.nil?
+        @cursor = @initial_cursor
+        @at_first_page = true
+        nil
+      end
+
       # Whether another page will be available from the API.
       #
       # @return [Boolean]
       def next?
-        @need_initial_load || !@cursor.nil?
+        (@at_first_page && !@first_page.nil?) || @need_initial_load || !@cursor.nil?
       end
 
       # Retrieves the next page from the API.
       #
       # @return [Object, nil]
       def next_page
-        return if !@need_initial_load && @cursor.nil?
-
-        @need_initial_load = false
-        result = @get_next_page.call(@cursor)
-        if result.is_a?(Array)
-          fetched_page, raw_response = result
-          @http_response = raw_response
+        if @at_first_page && !@first_page.nil?
+          page = @first_page
         else
-          fetched_page = result
+          return if !@need_initial_load && @cursor.nil?
+
+          page = fetch_page(@cursor)
         end
-        @cursor = fetched_page.send(@cursor_field)
+        @at_first_page = false
+        @need_initial_load = false
+        @cursor = page.send(@cursor_field)
+        page
+      end
+
+      protected
+
+      attr_reader :first_page
+
+      private
+
+      def fetch_page(cursor)
+        result = @get_next_page.call(cursor)
+        @first_page_requested = true
+        return result unless result.is_a?(Array)
+
+        fetched_page, raw_response = result
+        @http_response = raw_response
         fetched_page
       end
     end

data/lib/schematic/internal/iterators/item_iterator.rb

@@ -5,20 +5,35 @@ module Schematic
     class ItemIterator
       include Enumerable
 
-      # The raw HTTP response from the most recent page response.
+      # The raw HTTP response from the most recent page request made by this pager or its `pages`.
       # @return [Net::HTTPResponse, nil]
-      def http_response
-        @page_iterator&.http_response
-      end
+      attr_reader :http_response
 
-      # Iterates over each item returned by the API.
+      # Iterates over each item returned by the API, starting again from the first page on every call.
+      # Each loop is independent of other loops and of `next_element`.
       #
       # @param block [Proc] The block which each retrieved item is yielded to.
-      # @return [NilClass]
-      def each(&block)
-        while (item = next_element)
-          block.call(item)
+      # @return [NilClass, Enumerator] An Enumerator when no block is given.
+      def each(&)
+        return enum_for(:each) unless block_given?
+
+        # Each loop reads through its own copy of the page stream, so repeated or nested loops never
+        # share a position with each other or with `next_element`.
+        pass = @item_pages.dup.tap(&:rewind)
+        while (page = pass.next_page)
+          (page.send(@item_field) || []).each(&)
         end
+        nil
+      end
+
+      # Resets manual item-by-item iteration (`next_element` / `next?`) to the first page.
+      #
+      # @return [NilClass]
+      def rewind
+        @item_pages.rewind
+        @page = nil
+        @item_index = 0
+        nil
       end
 
       # Whether another item will be available from the API.
@@ -34,6 +49,19 @@ module Schematic
         any_items_in_cached_page?
       end
 
+      # Sends the request for the first page now instead of on the first iteration, so an API error for that page
+      # is raised here. The page is kept, and every loop (over items or `pages`) that starts from the first page
+      # reuses it instead of requesting it again. Does nothing if this pager already sent a request.
+      #
+      # @return [self]
+      def load_first_page
+        return self if @requested
+
+        @item_pages.load_first_page
+        @page_iterator.reuse_first_page(@item_pages)
+        self
+      end
+
       # Retrieves the next item from the API.
       def next_element
         item = next_item_from_cached_page
@@ -45,20 +73,38 @@ module Schematic
 
       private
 
+      # Wraps the page-fetching block so that `http_response` reflects the most recent request.
+      def track_http_responses(get_page)
+        proc do |*args|
+          result = get_page.call(*args)
+          @requested = true
+          @http_response = result[1] if result.is_a?(Array)
+          result
+        end
+      end
+
+      def cached_page_items
+        return [] unless @page
+
+        @page.send(@item_field) || []
+      end
+
       def next_item_from_cached_page
-        return unless @page
+        items = cached_page_items
+        return if @item_index >= items.length
 
-        @page.send(@item_field).shift
+        item = items[@item_index]
+        @item_index += 1
+        item
       end
 
       def any_items_in_cached_page?
-        return false unless @page
-
-        !@page.send(@item_field).empty?
+        @item_index < cached_page_items.length
       end
 
       def load_next_page
-        @page = @page_iterator.next_page
+        @page = @item_pages.next_page
+        @item_index = 0
       end
     end
   end

data/lib/schematic/internal/iterators/offset_item_iterator.rb

@@ -12,11 +12,16 @@ module Schematic
       # @param block [Proc] A block which is responsible for receiving a page number to use and returning the given page from the API.
       #
       # @return [Schematic::Internal::OffsetItemIterator]
-      def initialize(initial_page:, item_field:, has_next_field:, step:, &)
+      def initialize(initial_page:, item_field:, has_next_field:, step:, &block)
         super()
         @item_field = item_field
-        @page_iterator = OffsetPageIterator.new(initial_page:, item_field:, has_next_field:, step:, &)
+        @http_response = nil
+        get_page = track_http_responses(block)
+        @page_iterator = OffsetPageIterator.new(initial_page:, item_field:, has_next_field:, step:, &get_page)
+        # Items are read through their own page cursor so that reading `pages` never skips items.
+        @item_pages = OffsetPageIterator.new(initial_page:, item_field:, has_next_field:, step:, &get_page)
         @page = nil
+        @item_index = 0
       end
 
       # Returns the OffsetPageIterator that is mediating access to the underlying API.

data/lib/schematic/internal/iterators/offset_page_iterator.rb

@@ -19,36 +19,74 @@ module Schematic
       #   The block should return a two-element array: [parsed_page, raw_http_response].
       # @return [Schematic::Internal::OffsetPageIterator]
       def initialize(initial_page:, item_field:, has_next_field:, step:, &block)
-        @page_number = initial_page || (step ? 0 : 1)
+        @initial_page = initial_page || (step ? 0 : 1)
         @item_field = item_field
         @has_next_field = has_next_field
         @step = step
         @get_next_page = block
+        @http_response = nil
+        @first_page_requested = false
+        @first_page = nil
+        rewind
+      end
 
-        # A cache of whether the API has another page, if it gives us that information...
-        @next_page = nil
-        # ...or the actual next page, preloaded, if it doesn't.
-        @has_next_page = nil
+      # Sends the request for the first page now instead of on the first iteration, so an API error for that page
+      # is raised here. The page is kept, and every loop that starts from the first page reuses it instead of
+      # requesting it again (an empty first page ends those loops without a new request). Does nothing if the first
+      # page was already requested.
+      #
+      # @return [self]
+      def load_first_page
+        return self if @first_page_requested
 
-        @http_response = nil
+        @first_page = fetch_page(@initial_page)
+        rewind
+        self
       end
 
-      # Iterates over each page returned by the API.
+      # Uses the first page that `other` loaded with `load_first_page`, unless this iterator already sent a request.
       #
-      # @param block [Proc] The block which each retrieved page is yielded to.
+      # @param other [Schematic::Internal::OffsetPageIterator]
       # @return [NilClass]
+      def reuse_first_page(other)
+        return if @first_page_requested || other.first_page.nil?
+
+        @first_page = other.first_page
+        rewind
+      end
+
+      # Iterates over each page returned by the API, starting again from the first page on every call.
+      #
+      # @param block [Proc] The block which each retrieved page is yielded to.
+      # @return [NilClass, Enumerator] An Enumerator when no block is given.
       def each(&block)
+        return enum_for(:each) unless block_given?
+
+        rewind
         while (page = next_page)
           block.call(page)
         end
       end
 
+      # Resets page-by-page iteration (`next_page` / `next?`) to the first page.
+      #
+      # @return [NilClass]
+      def rewind
+        @page_number = @initial_page
+        # A cache of whether the API has another page, if it gives us that information...
+        @has_next_page = nil
+        # ...or the actual next page, preloaded, if it doesn't. A first page kept by `load_first_page` is reused.
+        @next_page = @first_page
+        nil
+      end
+
       # Whether another page will be available from the API.
       #
       # @return [Boolean]
       def next?
         return @has_next_page unless @has_next_page.nil?
-        return true if @next_page
+        return true if @next_page && page_has_items?(@next_page)
+        return @has_next_page = false if @next_page
 
         fetched_page = fetch_page(@page_number)
         fetched_page_items = fetched_page&.send(@item_field)
@@ -86,10 +124,20 @@ module Schematic
         this_page
       end
 
+      protected
+
+      attr_reader :first_page
+
       private
 
+      def page_has_items?(page)
+        items = page.send(@item_field)
+        !items.nil? && !items.empty?
+      end
+
       def fetch_page(page_number)
         result = @get_next_page.call(page_number)
+        @first_page_requested = true
         if result.is_a?(Array)
           fetched_page, raw_response = result
           @http_response = raw_response

data/lib/schematic/internal/json/request.rb

@@ -31,9 +31,18 @@ module Schematic
           merge_additional_headers(sdk_headers, protected_keys:)
         end
 
-        # @return [String, nil] The encoded HTTP request body.
+        # @return [String, nil] The encoded HTTP request body, including any additional_body_parameters
+        #   from request_options.
         def encode_body
-          @body.nil? ? nil : ::JSON.generate(@body)
+          body = request_body
+          body.nil? ? nil : ::JSON.generate(body)
+        end
+
+        private
+
+        # @return [Object, nil] The request body merged with additional_body_parameters.
+        def request_body
+          merge_additional_body_parameters(@body)
         end
       end
     end

data/lib/schematic/internal/multipart/multipart_request.rb

@@ -31,6 +31,7 @@ module Schematic
         end
 
         # @return [String, nil] The encoded HTTP request body.
+        # Note: additional_body_parameters from request_options are not applied to multipart requests.
         def encode_body
           @body&.encode
         end

data/lib/schematic/internal/types/model.rb

@@ -108,6 +108,7 @@ module Schematic
             method_name = :"#{name}="
 
             define_method(method_name) do |val|
+              @explicit_fields[name] = true
               @data[name] = val
             end
           end
@@ -137,6 +138,7 @@ module Schematic
         # @return [self]
         def initialize(values = {})
           @data = {}
+          @explicit_fields = {}
 
           values = Utils.symbolize_keys(values.dup)
 
@@ -145,6 +147,7 @@ module Schematic
             [field.api_name.to_sym, field_name].uniq.each do |key|
               next unless values.key?(key)
 
+              @explicit_fields[field_name] = true
               candidate = values.delete(key)
               value = candidate if value.nil?
             end
@@ -173,14 +176,15 @@ module Schematic
             # If there is a value present in the data, use that value
             # If there is a `nil` value present in the data, and it is optional but NOT nullable, exclude key altogether
             # If there is a `nil` value present in the data, and it is optional and nullable, use the nil value
+            # only when it was explicitly provided; an omitted optional field is excluded
 
             value = @data[name]
 
-            next if value.nil? && field.optional && !field.nullable
+            next if value.nil? && field.optional && (!field.nullable || !@explicit_fields&.key?(name))
 
             if value.is_a?(::Array)
-              value = value.map { |item| item.respond_to?(:to_h) ? item.to_h : item }
-            elsif value.respond_to?(:to_h)
+              value = value.map { |item| !item.nil? && item.respond_to?(:to_h) ? item.to_h : item }
+            elsif !value.nil? && value.respond_to?(:to_h)
               value = value.to_h
             end
 

data/lib/schematic/internal/types/utils.rb

@@ -60,11 +60,18 @@ module Schematic
             case value
             when Numeric, String, Time
               return value.to_i
+            when Symbol
+              # JSON object keys are parsed as symbols, so numeric map keys arrive as e.g. :"1"
+              parsed = Integer(value.to_s, 10, exception: false)
+              return parsed unless parsed.nil?
             end
           in ->(t) { t <= Float }
             case value
             when Numeric, Time, String
               return value.to_f
+            when Symbol
+              parsed = Float(value.to_s, exception: false)
+              return parsed unless parsed.nil?
             end
           in ->(t) { t <= Model }
             case value

data/lib/schematic/licenses/client.rb

@@ -59,7 +59,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Licenses::Types::ListLicensesResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            400 => Schematic::Types::ApiError,
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -94,7 +102,14 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Licenses::Types::GetSingleLicenseResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -147,7 +162,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Licenses::Types::CountLicensesResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            400 => Schematic::Types::ApiError,
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
     end

data/lib/schematic/planbundle/client.rb

@@ -53,7 +53,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planbundle::Types::CreateCustomPlanBundleResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            400 => Schematic::Types::ApiError,
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -96,7 +104,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planbundle::Types::CreatePlanBundleResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            400 => Schematic::Types::ApiError,
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -144,7 +160,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planbundle::Types::UpdatePlanBundleResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            400 => Schematic::Types::ApiError,
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
     end