fsdk-2237-ruby-e2e 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8ce767b2edadc2f777a42dfa66fef226a51c2a5c570f1e189237aeca7af0a4fd
+  data.tar.gz: 4d7ffe98c283f2d621dc7074518df798b765343d625bb7d570f5ad1baf1c4d93
+SHA512:
+  metadata.gz: aa142530404fff5df7f75017176159e0f5996fc9766c00a7f7a22e17438a37a38dcceff6640e48e0087cb4da12e66e5354916c05ba3895770749f142d618a2a3
+  data.tar.gz: 4faf1824d38721b134040739a3f8e6262bd58f67525c59b9071852f12f30c7e09e844babed6422b031201305ca0c3197a5b1af4ff28cc1bb0860d1afbebdbc7d

data/README.md

@@ -0,0 +1,107 @@
+# Petstore Ruby Library
+
+![Generated by Postman](https://img.shields.io/badge/generated%20by-Postman-orange)
+
+The Petstore Ruby library provides convenient access to the API from Ruby.
+
+## Table of Contents
+
+- [Reference](#reference)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Errors](#errors)
+- [Advanced](#advanced)
+  - [Retries](#retries)
+  - [Per-request Options](#per-request-options)
+- [Contributing](#contributing)
+
+## Reference
+
+A full reference for this library is available [here](./reference.md).
+
+## Installation
+
+```sh
+gem install fsdk-2237-ruby-e2e
+```
+
+## Usage
+
+```ruby
+require "petstore"
+
+client = Petstore::PetstoreClient.new
+# See reference.md for the available resources and methods, e.g.:
+# client.some_resource.some_method(...)
+```
+
+## Errors
+
+When the API returns a non-success status code (4xx or 5xx), the SDK raises a subclass of
+`Petstore::Errors::ResponseError`. The HTTP status code is
+available via `#code` and the raw response body via `#message`.
+
+```ruby
+begin
+  client.some_resource.some_method(...)
+rescue Petstore::Errors::NotFoundError => e
+  # handle a 404 specifically
+rescue Petstore::Errors::ResponseError => e
+  puts e.code
+  puts e.message
+end
+```
+
+## Advanced
+
+### Retries
+
+Requests that fail with a retryable status code (408, 429, and 5xx) are automatically retried with
+exponential backoff, up to `max_retries` times. A request that times out is retried on the same
+terms. Configure the limit on the client:
+
+```ruby
+client = Petstore::PetstoreClient.new(max_retries: 3)
+```
+
+### Timeouts
+
+The open, read and write timeout defaults to 60 seconds. Set it on the client, or per call:
+
+```ruby
+client = Petstore::PetstoreClient.new(timeout: 10)
+client.some_resource.some_method(request_options: { timeout: 2.5 })
+```
+
+A request that exhausts its retries after timing out raises
+`Petstore::Errors::TimeoutError`, and one that never reached the
+server at all — refused connection, unresolvable host, failed TLS handshake — raises
+`Petstore::Errors::ConnectionError`. Both are subclasses of
+`Petstore::Errors::ApiError`, carry no status code (there was no
+response), and keep the underlying transport exception on `#cause`.
+
+### Per-request Options
+
+Every method accepts a `request_options:` hash to override behavior for a single call — a different
+base URL, additional headers, or additional query parameters:
+
+```ruby
+client.some_resource.some_method(
+  request_options: {
+    base_url: "https://staging.example.com",
+    timeout: 5,
+    additional_headers: { "X-Custom-Header" => "value" },
+    additional_query_parameters: { "trace" => "true" }
+  }
+)
+```
+
+## Contributing
+
+While we value open-source contributions to this SDK, this library is generated programmatically.
+Additions made directly to this library would have to be moved over to our generation code,
+otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
+a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
+an issue first to discuss with us!
+
+On the other hand, contributions to the README are always very welcome!

data/lib/petstore/client.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Petstore
+  class PetstoreClient
+    DEFAULT_BASE_URL = Environment::DEFAULT
+    TOKEN_URL = ''
+
+    def initialize(client_id:, client_secret:, base_url: nil, max_retries: 2, timeout: nil, token_url: TOKEN_URL)
+      @token_manager = HTTP::OAuthTokenManager.new(
+        client_id: client_id,
+        client_secret: client_secret,
+        token_url: token_url,
+        base_url: base_url || DEFAULT_BASE_URL,
+      )
+      headers = { 'X-Fern-Language' => 'Ruby' }
+      @raw_client = Internal::Http::RawClient.new(
+        base_url: base_url || DEFAULT_BASE_URL,
+        headers: headers,
+        max_retries: max_retries,
+        timeout: timeout,
+        token_provider: -> { @token_manager.headers['Authorization'] },
+      )
+    end
+
+    def pet
+      @pet ||= Pet::Client.new(client: @raw_client)
+    end
+
+    def store
+      @store ||= Store::Client.new(client: @raw_client)
+    end
+
+    def user
+      @user ||= User::Client.new(client: @raw_client)
+    end
+
+    def client_id=(client_id)
+      @token_manager.client_id = client_id
+    end
+
+    def client_secret=(client_secret)
+      @token_manager.client_secret = client_secret
+    end
+  end
+end

data/lib/petstore/config.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Petstore
+  class Config
+    attr_reader :base_url, :timeout, :enable_response_validation, :return_raw, :additional_headers, :additional_query_parameters, :retry_config, :token, :api_key
+
+    def initialize(
+      base_url: nil,
+      timeout: nil,
+      timeout_ms: nil,
+      enable_response_validation: false,
+      return_raw: false,
+      additional_headers: nil,
+      additional_query_parameters: nil,
+      retry_config: nil,
+      token: nil,
+      api_key: nil
+    )
+      unless timeout_ms.nil?
+        warn '[DEPRECATION] `timeout_ms` is deprecated; use `timeout` (seconds) instead.', uplevel: 1
+        timeout = timeout_ms / 1000.0 if timeout.nil?
+      end
+      @base_url = base_url
+      @timeout = timeout
+      @enable_response_validation = enable_response_validation
+      @return_raw = return_raw
+      @additional_headers = additional_headers
+      @additional_query_parameters = additional_query_parameters
+      @retry_config = retry_config
+      @token = token
+      @api_key = api_key
+    end
+
+    def with(**overrides)
+      base = to_h
+      base.delete(:timeout) if overrides.key?(:timeout_ms) && !overrides.key?(:timeout)
+      self.class.new(**base, **overrides)
+    end
+
+    def to_h
+      {
+        base_url: @base_url,
+        timeout: @timeout,
+        enable_response_validation: @enable_response_validation,
+        return_raw: @return_raw,
+        additional_headers: @additional_headers,
+        additional_query_parameters: @additional_query_parameters,
+        retry_config: @retry_config,
+        token: @token,
+        api_key: @api_key,
+      }
+    end
+  end
+end

data/lib/petstore/environment.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Environment
+    DEFAULT = '/api/v3'
+  end
+end

data/lib/petstore/error.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Petstore
+  class Error < StandardError; end
+
+  class APIError < Error
+    attr_reader :status, :body, :headers
+
+    def initialize(status, body, headers = {})
+      @status  = status
+      @body    = body
+      @headers = headers || {}
+      super("HTTP #{status}: #{body}")
+    end
+  end
+
+  class TimeoutError < Error
+    def initialize(msg = 'Request timed out')
+      super
+    end
+  end
+
+  # The request never reached the server: connection refused, host unresolvable, socket closed by
+  # the peer, or a failed TLS handshake. The underlying transport exception is on `#cause`.
+  class ConnectionError < Error
+    def initialize(msg = 'Failed to connect')
+      super
+    end
+  end
+
+  class ValidationError < Error
+    attr_reader :field, :validation_message
+
+    def initialize(field, message)
+      @field              = field
+      @validation_message = message
+      super("Validation failed for #{field}: #{message}")
+    end
+  end
+end

data/lib/petstore/errors/api_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Errors
+    # Base class for all errors raised by this SDK.
+    class ApiError < StandardError
+    end
+  end
+end

data/lib/petstore/errors/client_error.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Errors
+    # A 4xx response.
+    class ClientError < ResponseError
+    end
+
+    # One class per status a spec commonly declares, so a caller can rescue the exact response
+    # rather than the whole 4xx range. A 400 and a 422 are different failures — a malformed
+    # request against a well-formed one the server refuses — and collapsing them onto ClientError
+    # left no way to branch on which had happened. Any other 4xx still falls back to ClientError.
+    class BadRequestError < ClientError
+    end
+
+    class UnauthorizedError < ClientError
+    end
+
+    class PaymentRequiredError < ClientError
+    end
+
+    class ForbiddenError < ClientError
+    end
+
+    class NotFoundError < ClientError
+    end
+
+    class MethodNotAllowedError < ClientError
+    end
+
+    class ConflictError < ClientError
+    end
+
+    class UnsupportedMediaTypeError < ClientError
+    end
+
+    class UnprocessableEntityError < ClientError
+    end
+
+    class TooManyRequestsError < ClientError
+    end
+  end
+end

data/lib/petstore/errors/connection_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Errors
+    # Raised when the request never reached the server: the connection was refused, the host could
+    # not be resolved, the peer closed the socket, or the TLS handshake failed. The underlying
+    # transport exception is available on `#cause`.
+    class ConnectionError < ApiError
+    end
+  end
+end

data/lib/petstore/errors/redirect_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Errors
+    # A 3xx response.
+    class RedirectError < ResponseError
+    end
+  end
+end

data/lib/petstore/errors/response_error.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Errors
+    # An error returned by the API. The raw response body is the exception message and the HTTP
+    # status code is available via #code, as before; #body adds the body deserialized into the
+    # type the spec declares for that status, so a field the spec declares on an error response is
+    # reachable as `error.body.retry_after_seconds` instead of only by parsing #message by hand.
+    #
+    # #body is nil when the response carried no body, or a body that is not the declared shape.
+    class ResponseError < ApiError
+      attr_reader :code, :body
+
+      # @param msg [String] The raw response body.
+      # @param code [Integer] The HTTP status code.
+      # @param body [Object, nil] The deserialized error body.
+      def initialize(msg, code:, body: nil)
+        @code = code
+        @body = body
+        super(msg)
+      end
+
+      # Deserializes a raw error body with +type+, or nil when there is nothing to deserialize or
+      # the body is not the declared shape.
+      #
+      # An error response is the one place a server is most likely to answer off-spec — an HTML
+      # page from a proxy, an empty 500, a plain-text gateway message — and a raise site must not
+      # turn that into a parse failure that hides the status code the caller needs. So this
+      # rescues and degrades to nil rather than propagating.
+      #
+      # @param raw [String, nil] The raw response body.
+      # @param type [Class, nil] The model declared for this status, or nil if none is.
+      # @return [Object, nil]
+      def self.load_body(raw, type)
+        return nil if type.nil? || raw.nil? || raw.to_s.strip.empty?
+
+        parsed = type.load(raw)
+        deserialized?(parsed) ? parsed : nil
+      rescue StandardError
+        nil
+      end
+
+      # True when +load+ actually deserialized the body into the declared type, rather than handing
+      # back the raw parsed JSON — which is what it does for an off-spec body, since a model's
+      # #coerce returns a non-Hash untouched and a union's returns a value matching no member
+      # untouched.
+      #
+      # This deliberately does NOT ask +is_a?(type)+. A oneOf/anyOf error model is generated as a
+      # MODULE and its +load+ returns the matching MEMBER, whose class does not include that
+      # module, so +is_a?+ is false for every VALID union body; an enum's +load+ returns a Symbol,
+      # which is likewise not an instance of the enum. Both would have silently nil'd #body.
+      # Everything successfully deserialized is a model instance or an enum's Symbol, and neither
+      # is a shape ::JSON.parse can produce on its own.
+      private_class_method def self.deserialized?(value)
+        value.is_a?(Internal::Types::Model) || value.is_a?(::Symbol)
+      end
+
+      def inspect
+        "#<#{self.class.name} @code=#{code} @body=#{message}>"
+      end
+
+      # Maps an HTTP status code to the most specific error subclass. Status-specific classes come
+      # first so a caller can rescue the exact response the spec declares; the range classes are
+      # the fallback for a status without one.
+      #
+      # Resolved inside the method body rather than from a constant map, so the subclasses only
+      # have to be loaded by the time a request actually fails, not by the time this file is read.
+      def self.subclass_for_code(code)
+        case code
+        when 300..399 then RedirectError
+        when 400 then BadRequestError
+        when 401 then UnauthorizedError
+        when 402 then PaymentRequiredError
+        when 403 then ForbiddenError
+        when 404 then NotFoundError
+        when 405 then MethodNotAllowedError
+        when 409 then ConflictError
+        when 415 then UnsupportedMediaTypeError
+        when 422 then UnprocessableEntityError
+        when 429 then TooManyRequestsError
+        when 400..499 then ClientError
+        when 500 then InternalServerError
+        when 502 then BadGatewayError
+        when 503 then ServiceUnavailableError
+        when 504 then GatewayTimeoutError
+        when 500..599 then ServerError
+        else ResponseError
+        end
+      end
+    end
+  end
+end

data/lib/petstore/errors/server_error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Errors
+    # A 5xx response.
+    class ServerError < ResponseError
+    end
+
+    class InternalServerError < ServerError
+    end
+
+    class BadGatewayError < ServerError
+    end
+
+    # Was `< ApiError`, which is not a ResponseError and so takes no `code:` — a 503 therefore
+    # raised `ArgumentError: wrong number of arguments` from the raise site itself, and the typed
+    # error was unreachable. It is also now inside the 5xx subtree, so `rescue ServerError`
+    # catches it.
+    class ServiceUnavailableError < ServerError
+    end
+
+    class GatewayTimeoutError < ServerError
+    end
+  end
+end

data/lib/petstore/errors/timeout_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Errors
+    # Raised when a request times out.
+    class TimeoutError < ApiError
+    end
+  end
+end

data/lib/petstore/http/auth.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Petstore
+  module HTTP
+    class Auth
+      def initialize(token: nil, api_key: nil)
+        @token = token
+        @api_key = api_key
+      end
+
+      def headers
+        result = {}
+        result['Authorization'] = "Bearer #{@token}" unless @token.nil?
+        result['api_key'] = @api_key unless @api_key.nil?
+        result
+      end
+    end
+  end
+end

data/lib/petstore/http/oauth_token_manager.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module Petstore
+  module HTTP
+    class OAuthError < StandardError; end
+
+    # Manages OAuth 2.0 client credentials tokens: fetches, caches, and refreshes them.
+    # Token refresh is triggered when the token is absent or within REFRESH_BUFFER_SECS
+    # of expiry. A Mutex ensures thread-safe access to the cached token.
+    # Note: token refresh blocks all threads calling `headers` until the HTTP request
+    # completes. This is intentional — only one fetch occurs and others reuse the result.
+    class OAuthTokenManager
+      REFRESH_BUFFER_SECS = 30
+
+      # @param token_url [String] The token endpoint; a relative URL is joined to `base_url`.
+      # @param base_url [String, nil] The URL a relative `token_url` is resolved against.
+      def initialize(client_id:, client_secret:, token_url:, base_url: nil)
+        @client_id     = client_id
+        @client_secret = client_secret
+        @token_url     = token_url
+        @base_url      = base_url
+        @access_token  = nil
+        @expires_at    = nil
+        @mutex         = Mutex.new
+      end
+
+      attr_writer :client_id, :client_secret
+
+      # @return [Boolean] Whether both a client ID and a client secret are set.
+      def credentials?
+        [@client_id, @client_secret].none? { |value| value.nil? || value.to_s.empty? }
+      end
+
+      def headers
+        { 'Authorization' => "Bearer #{token}" }
+      end
+
+      # Force the next call to re-fetch a fresh token.
+      def invalidate
+        @mutex.synchronize { @access_token = nil }
+      end
+
+      private
+
+      def token
+        @mutex.synchronize do
+          fetch_token if token_expired?
+          @access_token
+        end
+      end
+
+      def token_expired?
+        @access_token.nil? || (@expires_at && Time.now + REFRESH_BUFFER_SECS >= @expires_at)
+      end
+
+      def token_uri
+        url = @token_url.to_s
+        return URI.parse(url) if @base_url.nil? || url.match?(%r{\A[a-z][a-z0-9+.-]*://}i)
+
+        URI.parse("#{@base_url.to_s.chomp('/')}/#{url.delete_prefix('/')}")
+      end
+
+      def fetch_token
+        uri = token_uri
+        req = Net::HTTP::Post.new(uri.request_uri)
+        req.set_form_data(
+          grant_type: 'client_credentials',
+          client_id: @client_id,
+          client_secret: @client_secret,
+        )
+
+        # Net::HTTP.start with a block opens and closes the connection automatically.
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+          http.request(req)
+        end
+        raise OAuthError, "token request failed (HTTP #{response.code}): #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+
+        body = JSON.parse(response.body)
+        raise OAuthError, 'access_token missing from token response' unless body.key?('access_token')
+
+        @access_token = body['access_token']
+        expires_in    = body['expires_in']
+        @expires_at   = expires_in ? Time.now + expires_in.to_i : nil
+      end
+    end
+  end
+end

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

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

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

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