peal 0.1.0 → 0.3.0

data/lib/peal/errors/response_error.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Peal
+  module Errors
+    class ResponseError < ApiError
+      attr_reader :code, :body, :headers
+
+      # @param msg [String] The raw response body.
+      # @param code [Integer] The HTTP status code.
+      # @param body [Object, nil] The response body parsed into the endpoint's declared error type, if any.
+      # @param headers [Hash{String => Array<String>}] The response headers, with lowercase names.
+      def initialize(msg, code:, body: nil, headers: {})
+        @code = code
+        @body = body
+        @headers = headers
+        super(msg)
+      end
+
+      def inspect
+        "#<#{self.class.name} @code=#{code} @body=#{message}>"
+      end
+
+      # Parses a raw error response body into the type declared for its status code.
+      #
+      # @param code [Integer]
+      # @param raw_body [String, nil]
+      # @param types [Hash{Integer, Range => Class}] Matchers in priority order.
+      # @return [Object, nil] nil when no type matches or the body cannot be parsed.
+      def self.load_error_body(code, raw_body, types)
+        type = types.find { |matcher, _| matcher.is_a?(::Range) ? matcher.cover?(code) : matcher == code }&.last
+        return nil if type.nil? || raw_body.to_s.empty?
+
+        begin
+          type.load(raw_body)
+        rescue StandardError
+          nil
+        end
+      end
+
+      # Returns the most appropriate error class for the given code.
+      #
+      # @return [Class]
+      def self.subclass_for_code(code)
+        case code
+        when 300..399
+          RedirectError
+        when 401
+          UnauthorizedError
+        when 403
+          ForbiddenError
+        when 404
+          NotFoundError
+        when 400..499
+          ClientError
+        when 503
+          ServiceUnavailableError
+        when 500..599
+          ServerError
+        else
+          ResponseError
+        end
+      end
+    end
+  end
+end

data/lib/peal/errors/server_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Peal
+  module Errors
+    class ServerError < ResponseError
+    end
+
+    class ServiceUnavailableError < ResponseError
+    end
+  end
+end

data/lib/peal/errors/timeout_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Peal
+  module Errors
+    class TimeoutError < ApiError
+    end
+  end
+end

data/lib/peal/internal/errors/constraint_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Peal
+  module Internal
+    module Errors
+      class ConstraintError < StandardError
+      end
+    end
+  end
+end

data/lib/peal/internal/errors/type_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Peal
+  module Internal
+    module Errors
+      class TypeError < StandardError
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Peal
+  module Internal
+    module Http
+      # @api private
+      class BaseRequest
+        attr_reader :base_url, :path, :method, :headers, :query, :request_options, :max_retries
+
+        # @param base_url [String] The base URL for the request
+        # @param path [String] The path for the request
+        # @param method [String] The HTTP method for the request (:get, :post, etc.)
+        # @param headers [Hash] Additional headers for the request (optional)
+        # @param query [Hash] Query parameters for the request (optional)
+        # @param request_options [Peal::RequestOptions, Hash{Symbol=>Object}, nil]
+        # @param max_retries [Integer, nil] Overrides the client's retry count for this request
+        def initialize(base_url:, path:, method:, headers: {}, query: {}, request_options: {}, max_retries: nil)
+          @base_url = base_url
+          @path = path
+          @method = method
+          @headers = headers
+          @query = query
+          @request_options = request_options
+          @max_retries = max_retries
+        end
+
+        # @return [Hash] The query parameters merged with additional query parameters from request options.
+        def encode_query
+          additional_query = @request_options&.dig(:additional_query_parameters) || @request_options&.dig("additional_query_parameters") || {}
+          Internal::Types::Utils.serialize_times(@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.
+        # @param protected_keys [Array<String>] Additional header keys that must not be overridden.
+        # @return [Hash] The merged headers.
+        def merge_additional_headers(sdk_headers, protected_keys: [])
+          additional_headers = @request_options&.dig(:additional_headers) || @request_options&.dig("additional_headers") || {}
+          all_protected = (sdk_headers.keys + protected_keys).to_set { |k| k.to_s.downcase }
+          filtered = additional_headers.reject { |key, _| all_protected.include?(key.to_s.downcase) }
+          sdk_headers.merge(filtered)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+module Peal
+  module Internal
+    module Http
+      # @api private
+      class RawClient
+        # Default HTTP status codes that trigger a retry
+        RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504, 521, 522, 524].freeze
+        # Initial delay between retries in seconds
+        INITIAL_RETRY_DELAY = 0.5
+        # Maximum delay between retries in seconds
+        MAX_RETRY_DELAY = 60.0
+        # Jitter factor for randomizing retry delays (20%)
+        JITTER_FACTOR = 0.2
+
+        # @return [String] The base URL for requests
+        attr_reader :base_url
+
+        # @param base_url [String] The base url for the request.
+        # @param max_retries [Integer] The number of times to retry a failed request, defaults to 2.
+        # @param timeout [Float] The timeout for the request, defaults to 60.0 seconds.
+        # @param headers [Hash] The headers for the request.
+        # @param overridable_headers [Array<String>] The names of the client-level headers a request
+        #   may replace via `additional_headers`. Holds the API's global headers; SDK metadata and
+        #   auth headers are absent from it and so stay protected.
+        # @param auth_provider [Object, nil] An optional auth provider responding to
+        #   `auth_headers`. When present its headers are resolved on every request so
+        #   token-based schemes (e.g. OAuth) can refresh an expired token mid-session.
+        def initialize(base_url:, max_retries: 2, timeout: 60.0, headers: {}, overridable_headers: [], auth_provider: nil)
+          @base_url = base_url
+          @max_retries = max_retries
+          @timeout = timeout
+          @auth_provider = auth_provider
+          @default_headers = {
+            "X-Fern-Language": "Ruby",
+            "X-Fern-SDK-Name": "peal",
+            "X-Fern-SDK-Version": Peal::VERSION
+          }.merge(headers)
+          @overridable_headers = overridable_headers.to_set { |name| name.to_s.downcase }
+        end
+
+        # @param request [Peal::Internal::Http::BaseRequest] The HTTP request.
+        # @return [HTTP::Response] The HTTP response.
+        def send(request)
+          url = build_url(request)
+          # 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
+
+          loop do
+            http_request = build_http_request(
+              url:,
+              method: request.method,
+              headers: request.encode_headers(protected_keys: protected_header_keys + auth_headers.keys),
+              body: request.encode_body,
+              auth_headers: auth_headers
+            )
+
+            conn = connect(url)
+            conn.open_timeout = timeout
+            conn.read_timeout = timeout
+            conn.write_timeout = timeout
+            conn.continue_timeout = timeout
+
+            response = wrap_transport_errors { conn.request(http_request) }
+
+            break unless should_retry?(response, attempt, max_retries: request.max_retries)
+
+            delay = retry_delay(response, attempt)
+            sleep(delay)
+            attempt += 1
+          end
+
+          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 Peal::Errors::TimeoutError, e.message
+        rescue EOFError, SocketError, OpenSSL::SSL::SSLError, *NETWORK_ERRNOS,
+               Net::ProtocolError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError => e
+          raise Peal::Errors::ConnectionError, e.message
+        end
+
+        # @param request [Peal::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.
+        def protected_header_keys
+          return @default_headers.keys if @overridable_headers.empty?
+
+          @default_headers.keys.reject { |name| @overridable_headers.include?(name.to_s.downcase) }
+        end
+
+        # Determines if a request should be retried based on the response status code.
+        # @param response [Net::HTTPResponse] The HTTP response.
+        # @param attempt [Integer] The current retry attempt (0-indexed).
+        # @param max_retries [Integer, nil] The request-level retry count, when the endpoint
+        #   overrides the client-level setting.
+        # @return [Boolean] Whether the request should be retried.
+        def should_retry?(response, attempt, max_retries: nil)
+          return false if attempt >= (max_retries || @max_retries)
+
+          status = response.code.to_i
+          RETRYABLE_STATUSES.include?(status)
+        end
+
+        # Calculates the delay before the next retry attempt using exponential backoff with jitter.
+        # Respects Retry-After header if present.
+        # @param response [Net::HTTPResponse] The HTTP response.
+        # @param attempt [Integer] The current retry attempt (0-indexed).
+        # @return [Float] The delay in seconds before the next retry.
+        def retry_delay(response, attempt)
+          # Check for Retry-After header (can be seconds or HTTP date)
+          retry_after = response["Retry-After"]
+          if retry_after
+            delay = parse_retry_after(retry_after)
+            return [delay, MAX_RETRY_DELAY].min if delay&.positive?
+          end
+
+          # Exponential backoff with jitter: base_delay * 2^attempt
+          base_delay = INITIAL_RETRY_DELAY * (2**attempt)
+          add_jitter([base_delay, MAX_RETRY_DELAY].min)
+        end
+
+        # Parses the Retry-After header value.
+        # @param value [String] The Retry-After header value (seconds or HTTP date).
+        # @return [Float, nil] The delay in seconds, or nil if parsing fails.
+        def parse_retry_after(value)
+          # Try parsing as integer (seconds)
+          seconds = Integer(value, exception: false)
+          return seconds.to_f if seconds
+
+          # Try parsing as HTTP date
+          begin
+            retry_time = Time.httpdate(value)
+            delay = retry_time - Time.now
+            delay.positive? ? delay : nil
+          rescue ArgumentError
+            nil
+          end
+        end
+
+        # Adds random jitter to a delay value.
+        # @param delay [Float] The base delay in seconds.
+        # @return [Float] The delay with jitter applied.
+        def add_jitter(delay)
+          jitter = delay * JITTER_FACTOR * (rand - 0.5) * 2
+          [delay + jitter, 0].max
+        end
+
+        LOCALHOST_HOSTS = %w[localhost 127.0.0.1 [::1]].freeze
+
+        # @param request [Peal::Internal::Http::BaseRequest] The HTTP request.
+        # @return [URI::Generic] The URL.
+        def build_url(request)
+          encoded_query = request.encode_query
+
+          # If the path is already an absolute URL, use it directly
+          if request.path.start_with?("http://", "https://")
+            url = request.path
+            url = "#{url}?#{encode_query(encoded_query)}" if encoded_query&.any?
+            parsed = URI.parse(url)
+            validate_https!(parsed)
+            return parsed
+          end
+
+          path = request.path.start_with?("/") ? request.path[1..] : request.path
+          base = request.base_url || @base_url
+          url = "#{base.chomp("/")}/#{path}"
+          url = "#{url}?#{encode_query(encoded_query)}" if encoded_query&.any?
+          parsed = URI.parse(url)
+          validate_https!(parsed)
+          parsed
+        end
+
+        # Raises if the URL uses http:// for a non-localhost host, which would
+        # send authentication credentials in plaintext.
+        # @param url [URI::Generic] The parsed URL.
+        def validate_https!(url)
+          return if url.scheme != "http"
+          return if LOCALHOST_HOSTS.include?(url.host)
+
+          raise ArgumentError,
+                "Refusing to send request to non-HTTPS URL: #{url}. " \
+                "HTTP is only allowed for localhost. Use HTTPS or pass a localhost URL."
+        end
+
+        # Resolves the auth headers to send with the next request. Delegates to the
+        # configured auth provider (if any) on every call so that token-based
+        # providers (e.g. OAuth client-credentials) can refresh an expired token
+        # before the request is sent. Returns an empty hash when no provider is set,
+        # which keeps the api-key / basic / bearer / no-auth paths unchanged.
+        # @return [Hash] The auth headers for the current request.
+        def resolve_auth_headers
+          return {} if @auth_provider.nil?
+
+          @auth_provider.auth_headers
+        end
+
+        # @param url [URI::Generic] The url to the resource.
+        # @param method [String] The HTTP method to use.
+        # @param headers [Hash] The headers for the request.
+        # @param body [String, nil] The body for the request.
+        # @param auth_headers [Hash] The auth headers resolved for this request. These
+        #   take precedence over the static default headers but not over per-request
+        #   headers, mirroring the previous baked-header precedence.
+        # @return [HTTP::Request] The HTTP request.
+        def build_http_request(url:, method:, headers: {}, body: nil, auth_headers: {})
+          request = Net::HTTPGenericRequest.new(
+            method,
+            !body.nil?,
+            method != "HEAD",
+            url
+          )
+
+          request_headers = @default_headers.merge(auth_headers).merge(headers)
+          request_headers.each { |name, value| request[name] = value }
+          request.body = body if body
+
+          # Net::HTTP disables its transparent gzip/deflate decoding as soon as an
+          # Accept-Encoding header is set explicitly on the request. Re-enable it so
+          # that compressed response bodies are still inflated.
+          request.extend(DecodeContent) if request_headers.keys.any? { |name| name.to_s.casecmp("accept-encoding").zero? }
+
+          request
+        end
+
+        # Keeps Net::HTTP's transparent gzip/deflate response decoding enabled
+        # even when an Accept-Encoding header is set explicitly on the request.
+        # @api private
+        module DecodeContent
+          def decode_content # rubocop:disable Naming/PredicateMethod
+            true
+          end
+        end
+
+        # @param query [Hash] The query for the request.
+        # @return [String, nil] The encoded query.
+        def encode_query(query)
+          query.to_h.empty? ? nil : URI.encode_www_form(query)
+        end
+
+        # @param url [URI::Generic] The url to connect to.
+        # @return [Net::HTTP] The HTTP connection.
+        def connect(url)
+          is_https = (url.scheme == "https")
+
+          port = if url.port
+                   url.port
+                 elsif is_https
+                   Net::HTTP.https_default_port
+                 else
+                   Net::HTTP.http_default_port
+                 end
+
+          http = Net::HTTP.new(url.host, port)
+          http.use_ssl = is_https
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER if is_https
+          # NOTE: We handle retries at the application level with HTTP status code awareness,
+          # so we set max_retries to 0 to disable Net::HTTP's built-in network-level retries.
+          http.max_retries = 0
+          http
+        end
+
+        # @return [String]
+        def inspect
+          "#<#{self.class.name}:0x#{object_id.to_s(16)} @base_url=#{@base_url.inspect}>"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Peal
+  module Internal
+    class CursorItemIterator < ItemIterator
+      # Instantiates a CursorItemIterator, an Enumerable class which wraps calls to a cursor-based paginated API and yields individual items from it.
+      #
+      # @param initial_cursor [String] The initial cursor to use when iterating, if any.
+      # @param cursor_field [Symbol, Array<Symbol>] The field (or nested path) in API responses to extract the next cursor from.
+      # @param item_field [Symbol, Array<Symbol>] The field (or nested path) 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 [Peal::Internal::CursorItemIterator]
+      def initialize(initial_cursor:, cursor_field:, item_field:, &block)
+        super()
+        @item_field = item_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.
+      #
+      # @return [Peal::Internal::CursorPageIterator]
+      def pages
+        @page_iterator
+      end
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Peal
+  module Internal
+    class CursorPageIterator
+      include Enumerable
+
+      # The raw HTTP response from the most recent page response.
+      # @return [Net::HTTPResponse, nil]
+      attr_reader :http_response
+
+      # Instantiates a CursorPageIterator, an Enumerable class which wraps calls to a cursor-based paginated API and yields pages of items.
+      #
+      # @param initial_cursor [String] The initial cursor to use when iterating, if any.
+      # @param cursor_field [Symbol, Array<Symbol>] The name (or nested path) of the field in API responses to extract the next cursor from.
+      # @param block [Proc] A block which is responsible for receiving a cursor to use and returning the given page from the API.
+      #   The block should return a two-element array: [parsed_page, raw_http_response].
+      # @return [Peal::Internal::CursorPageIterator]
+      def initialize(initial_cursor:, cursor_field:, &block)
+        @initial_cursor = initial_cursor
+        @cursor_field = cursor_field
+        @get_next_page = block
+        @http_response = nil
+        @first_page_requested = false
+        @first_page = nil
+        rewind
+      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 that starts from the first page reuses it instead of
+      # requesting it again. Does nothing if the first page was already requested.
+      #
+      # @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 [Peal::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?
+        (@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
+        if @at_first_page && !@first_page.nil?
+          page = @first_page
+        else
+          return if !@need_initial_load && @cursor.nil?
+
+          page = fetch_page(@cursor)
+        end
+        @at_first_page = false
+        @need_initial_load = false
+        @cursor = read_field(page, @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
+
+      # Reads a field from an API response, walking through enclosing objects when the field is nested.
+      #
+      # @param value [Object, nil] The API response.
+      # @param field [Symbol, Array<Symbol>] The field name, or the path of field names for a nested field.
+      # @return [Object, nil]
+      def read_field(value, field)
+        Array(field).reduce(value) { |object, name| object&.send(name) }
+      end
+    end
+  end
+end