petstore_api_client 0.1.0

data/lib/petstore_api_client/authentication/oauth2.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+require "oauth2"
+require_relative "base"
+
+module PetstoreApiClient
+  module Authentication
+    # OAuth2 authentication strategy for Petstore API
+    #
+    # Implements OAuth2 Client Credentials flow for server-to-server authentication.
+    # Automatically handles token fetching, caching, and refresh on expiration.
+    #
+    # This implementation follows the same security best practices as the ApiKey strategy:
+    # - HTTPS enforcement with warnings for insecure connections
+    # - Token masking in logs and debug output
+    # - Environment variable support for secure credential storage
+    # - Thread-safe token management
+    #
+    # @example Basic usage with explicit credentials
+    #   auth = OAuth2.new(
+    #     client_id: "my-client-id",
+    #     client_secret: "my-secret",
+    #     token_url: "https://petstore.swagger.io/oauth/token"
+    #   )
+    #   auth.configured? # => true
+    #
+    # @example Loading from environment variables
+    #   ENV['PETSTORE_OAUTH2_CLIENT_ID'] = 'my-client-id'
+    #   ENV['PETSTORE_OAUTH2_CLIENT_SECRET'] = 'my-secret'
+    #   ENV['PETSTORE_OAUTH2_TOKEN_URL'] = 'https://petstore.swagger.io/oauth/token'
+    #   auth = OAuth2.from_env
+    #
+    # @example With custom scope
+    #   auth = OAuth2.new(
+    #     client_id: "my-client-id",
+    #     client_secret: "my-secret",
+    #     token_url: "https://petstore.swagger.io/oauth/token",
+    #     scope: "read:pets write:pets"
+    #   )
+    #
+    # @see https://oauth.net/2/ OAuth 2.0 Specification
+    # @see https://tools.ietf.org/html/rfc6749#section-4.4 Client Credentials Grant
+    # @since 0.2.0
+    class OAuth2 < Base
+      # Default token URL for Petstore API
+      DEFAULT_TOKEN_URL = "https://petstore.swagger.io/oauth/token"
+
+      # Default OAuth2 scope for Petstore API (supports both read and write)
+      DEFAULT_SCOPE = "read:pets write:pets"
+
+      # Environment variable names for OAuth2 credentials
+      ENV_CLIENT_ID = "PETSTORE_OAUTH2_CLIENT_ID"
+      ENV_CLIENT_SECRET = "PETSTORE_OAUTH2_CLIENT_SECRET"
+      ENV_TOKEN_URL = "PETSTORE_OAUTH2_TOKEN_URL"
+      ENV_SCOPE = "PETSTORE_OAUTH2_SCOPE"
+
+      # Minimum seconds before expiration to trigger token refresh
+      # If token expires in less than this time, fetch a new one
+      TOKEN_REFRESH_BUFFER = 60
+
+      # Minimum length requirements for credentials (security validation)
+      MIN_ID_LENGTH = 3
+      MIN_SECRET_LENGTH = 3
+
+      # @!attribute [r] client_id
+      #   @return [String, nil] OAuth2 client ID
+      attr_reader :client_id
+
+      # @!attribute [r] client_secret
+      #   @return [String, nil] OAuth2 client secret (masked in output)
+      attr_reader :client_secret
+
+      # @!attribute [r] token_url
+      #   @return [String] OAuth2 token endpoint URL
+      attr_reader :token_url
+
+      # @!attribute [r] scope
+      #   @return [String, nil] OAuth2 scope (space-separated permissions)
+      attr_reader :scope
+
+      # Initialize OAuth2 authenticator with client credentials
+      #
+      # @param client_id [String, nil] OAuth2 client ID
+      # @param client_secret [String, nil] OAuth2 client secret
+      # @param token_url [String] OAuth2 token endpoint URL
+      # @param scope [String, nil] OAuth2 scope (space-separated permissions)
+      #
+      # @raise [ValidationError] if credentials are invalid format
+      #
+      # @example
+      #   auth = OAuth2.new(
+      #     client_id: "my-app",
+      #     client_secret: "secret123",
+      #     token_url: "https://api.example.com/oauth/token",
+      #     scope: "read write"
+      #   )
+      #
+      # rubocop:disable Lint/MissingSuper
+      def initialize(client_id: nil, client_secret: nil, token_url: DEFAULT_TOKEN_URL, scope: nil)
+        @client_id = client_id&.to_s&.strip
+        @client_secret = client_secret&.to_s&.strip
+        @token_url = token_url || DEFAULT_TOKEN_URL
+        @scope = scope&.to_s&.strip
+        @access_token = nil
+        @token_mutex = Mutex.new # Thread-safe token access
+
+        validate! if configured?
+      end
+      # rubocop:enable Lint/MissingSuper
+
+      # Create OAuth2 authenticator from environment variables
+      #
+      # Loads credentials from:
+      # - PETSTORE_OAUTH2_CLIENT_ID
+      # - PETSTORE_OAUTH2_CLIENT_SECRET
+      # - PETSTORE_OAUTH2_TOKEN_URL (optional, defaults to Petstore API)
+      # - PETSTORE_OAUTH2_SCOPE (optional)
+      #
+      # @return [OAuth2] New authenticator instance
+      #
+      # @example
+      #   ENV['PETSTORE_OAUTH2_CLIENT_ID'] = 'my-id'
+      #   ENV['PETSTORE_OAUTH2_CLIENT_SECRET'] = 'my-secret'
+      #   auth = OAuth2.from_env
+      #   auth.configured? # => true
+      #
+      def self.from_env
+        new(
+          client_id: ENV.fetch(ENV_CLIENT_ID, nil),
+          client_secret: ENV.fetch(ENV_CLIENT_SECRET, nil),
+          token_url: ENV.fetch(ENV_TOKEN_URL, DEFAULT_TOKEN_URL),
+          scope: ENV.fetch(ENV_SCOPE, nil)
+        )
+      end
+
+      # Apply OAuth2 authentication to Faraday request
+      #
+      # Adds Authorization header with Bearer token.
+      # Automatically fetches or refreshes token if needed.
+      #
+      # @param env [Faraday::Env] The Faraday request environment
+      # @return [void]
+      #
+      # @raise [AuthenticationError] if token fetch fails
+      #
+      # @example
+      #   auth = OAuth2.new(client_id: "id", client_secret: "secret")
+      #   auth.apply(faraday_env)
+      #   # Request now has: Authorization: Bearer <access_token>
+      #
+      def apply(env)
+        return unless configured?
+
+        # Warn if sending credentials over insecure connection
+        warn_if_insecure!(env)
+
+        # Ensure we have a valid token
+        ensure_valid_token!
+
+        # Add Authorization header with Bearer token
+        env.request_headers["Authorization"] = "Bearer #{@access_token.token}"
+      end
+
+      # Check if OAuth2 credentials are configured
+      #
+      # @return [Boolean] true if client_id and client_secret are present
+      #
+      # @example
+      #   auth = OAuth2.new(client_id: "id", client_secret: "secret")
+      #   auth.configured? # => true
+      #
+      #   auth = OAuth2.new
+      #   auth.configured? # => false
+      #
+      def configured?
+        !@client_id.nil? && !@client_id.empty? &&
+          !@client_secret.nil? && !@client_secret.empty?
+      end
+
+      # Fetch a new access token from OAuth2 server
+      #
+      # Uses Client Credentials flow to obtain an access token.
+      # Token is cached and reused until expiration.
+      #
+      # @return [OAuth2::AccessToken] The access token object
+      #
+      # @raise [AuthenticationError] if token fetch fails
+      #
+      # @example
+      #   auth = OAuth2.new(client_id: "id", client_secret: "secret")
+      #   token = auth.fetch_token!
+      #   token.token # => "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+      #
+      def fetch_token!
+        @token_mutex.synchronize do
+          client = build_oauth2_client
+          @access_token = client.client_credentials.get_token(scope: @scope)
+        rescue ::OAuth2::Error => e
+          raise AuthenticationError,
+                "OAuth2 token fetch failed: #{e.message}"
+        end
+      end
+
+      # Check if current access token is expired or will expire soon
+      #
+      # Returns true if token is nil, already expired, or expires within
+      # TOKEN_REFRESH_BUFFER seconds.
+      #
+      # @return [Boolean] true if token needs refresh
+      #
+      # @example
+      #   auth.token_expired? # => true (no token yet)
+      #   auth.fetch_token!
+      #   auth.token_expired? # => false (fresh token)
+      #
+      def token_expired?
+        return true if @access_token.nil?
+        return true if @access_token.expired?
+
+        # Refresh if expiring soon (within buffer window)
+        return false if @access_token.expires_at.nil?
+
+        Time.now.to_i >= (@access_token.expires_at - TOKEN_REFRESH_BUFFER)
+      end
+
+      # String representation (masks client secret for security)
+      #
+      # @return [String] Masked representation of OAuth2 config
+      #
+      # @example
+      #   auth = OAuth2.new(client_id: "my-app", client_secret: "secret123")
+      #   auth.inspect # => "#<OAuth2 client_id=my-app secret=sec*******>"
+      #
+      def inspect
+        return unconfigured_inspect unless configured?
+
+        # Use base class method to mask credentials
+        masked_secret = mask_credential(@client_secret, 3)
+
+        token_status = if @access_token.nil?
+                         "no token"
+                       elsif token_expired?
+                         "token expired"
+                       else
+                         "token valid"
+                       end
+
+        "#<#{self.class.name} client_id=#{@client_id} secret=#{masked_secret} (#{token_status})>"
+      end
+      alias to_s inspect
+
+      private
+
+      # Validate OAuth2 credentials format
+      #
+      # @return [void]
+      # @raise [ValidationError] if credentials are invalid
+      #
+      def validate!
+        return unless configured?
+
+        # Use base class validation methods for DRY principle
+        validate_credential_length(@client_id, "OAuth2 client_id", MIN_ID_LENGTH)
+        validate_credential_length(@client_secret, "OAuth2 client_secret", MIN_SECRET_LENGTH)
+        validate_no_newlines(@client_id, "OAuth2 client_id")
+        validate_no_newlines(@client_secret, "OAuth2 client_secret")
+      end
+
+      # Build OAuth2 client for token operations
+      #
+      # @return [::OAuth2::Client] OAuth2 client instance
+      #
+      def build_oauth2_client
+        ::OAuth2::Client.new(
+          @client_id,
+          @client_secret,
+          site: token_site,
+          token_url: @token_url
+        )
+      end
+
+      # Extract site URL from token_url
+      # OAuth2 gem requires separate site and token_url
+      #
+      # @return [String] Base site URL
+      #
+      def token_site
+        uri = URI.parse(@token_url)
+        "#{uri.scheme}://#{uri.host}#{":#{uri.port}" if uri.port && uri.port != 80 && uri.port != 443}"
+      end
+
+      # Ensure we have a valid access token
+      # Fetches new token if needed
+      #
+      # @return [void]
+      # @raise [AuthenticationError] if token fetch fails
+      #
+      def ensure_valid_token!
+        fetch_token! if token_expired?
+      end
+
+      # Note: warn_if_insecure! method inherited from Base class
+    end
+  end
+end

data/lib/petstore_api_client/client.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  # Base HTTP client for Petstore API
+  #
+  # Provides low-level HTTP communication with the Petstore API. This class
+  # includes Connection and Request modules to handle connection management
+  # and HTTP request execution.
+  #
+  # Most users should use the higher-level PetClient or StoreClient instead
+  # of using this class directly.
+  #
+  # @example Creating a client with default configuration
+  #   client = PetstoreApiClient::Client.new
+  #
+  # @example Creating a client with custom configuration
+  #   config = PetstoreApiClient::Configuration.new
+  #   config.api_key = "special-key"
+  #   config.timeout = 60
+  #   client = PetstoreApiClient::Client.new(config)
+  #
+  # @example Configuring an existing client
+  #   client = PetstoreApiClient::Client.new
+  #   client.configure do |c|
+  #     c.api_key = "special-key"
+  #     c.timeout = 60
+  #   end
+  #
+  # @see Connection Connection management
+  # @see Request HTTP request methods
+  # @since 0.1.0
+  class Client
+    include Connection
+    include Request
+
+    # @!attribute [r] configuration
+    #   @return [Configuration] The configuration object for this client
+    attr_reader :configuration
+
+    # Initialize a new HTTP client
+    #
+    # Creates a new client instance with the provided configuration.
+    # If no configuration is provided, uses default configuration.
+    # Validates configuration before creating the client.
+    #
+    # @param config [Configuration, nil] Optional configuration object.
+    #   If nil, creates a new Configuration with defaults.
+    #
+    # @raise [ValidationError] if configuration is invalid
+    #
+    # @example With default configuration
+    #   client = Client.new
+    #
+    # @example With custom configuration
+    #   config = Configuration.new
+    #   config.api_key = "special-key"
+    #   client = Client.new(config)
+    #
+    def initialize(config = nil)
+      @configuration = config || Configuration.new
+      @configuration.validate!
+    end
+
+    # Configure the client via block
+    #
+    # Yields the configuration object to the block for modification.
+    # Automatically resets the connection after configuration changes
+    # to ensure new settings are applied.
+    #
+    # @yieldparam [Configuration] configuration The configuration object
+    # @return [Client] self for method chaining
+    #
+    # @example
+    #   client = Client.new
+    #   client.configure do |config|
+    #     config.api_key = "special-key"
+    #     config.timeout = 60
+    #     config.retry_enabled = false
+    #   end
+    #
+    def configure
+      yield(configuration) if block_given?
+      reset_connection! # Need to reset when config changes
+      self
+    end
+  end
+end

data/lib/petstore_api_client/clients/concerns/pagination.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  module Clients
+    module Concerns
+      # Pagination support for list endpoints
+      # Provides utilities for handling pagination parameters and responses
+      #
+      # This module follows the Strategy pattern - it encapsulates
+      # different pagination strategies (offset-based, page-based)
+      module Pagination
+        # Default pagination settings
+        DEFAULT_PAGE = 1
+        DEFAULT_PER_PAGE = 25
+        MAX_PER_PAGE = 100
+
+        private
+
+        # Normalize pagination options from various input formats
+        # Supports both page-based (page, per_page) and offset-based (offset, limit)
+        #
+        # @param options [Hash] Input options
+        # @option options [Integer] :page Page number (1-indexed)
+        # @option options [Integer] :per_page Items per page
+        # @option options [Integer] :offset Offset for results (0-indexed)
+        # @option options [Integer] :limit Maximum number of results
+        # @return [Hash] Normalized pagination params with :page and :per_page
+        # rubocop:disable Metrics/MethodLength
+        def normalize_pagination_options(options = {})
+          # Handle offset-based pagination
+          if options.key?(:offset) || options.key?(:limit)
+            offset = (options[:offset] || 0).to_i
+            limit = (options[:limit] || DEFAULT_PER_PAGE).to_i
+
+            # Convert offset/limit to page/per_page
+            page = (offset / limit) + 1
+            per_page = limit
+          else
+            # Handle page-based pagination (default)
+            page = (options[:page] || DEFAULT_PAGE).to_i
+            per_page = (options[:per_page] || DEFAULT_PER_PAGE).to_i
+          end
+
+          # Validate and constrain values
+          page = 1 if page < 1
+          per_page = DEFAULT_PER_PAGE if per_page < 1
+          per_page = MAX_PER_PAGE if per_page > MAX_PER_PAGE
+
+          {
+            page: page,
+            per_page: per_page,
+            offset: (page - 1) * per_page,
+            limit: per_page
+          }
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        # Create a PaginatedCollection from array data
+        #
+        # @param data [Array] Array of items
+        # @param pagination_opts [Hash] Pagination options
+        # @option pagination_opts [Integer] :page Current page number
+        # @option pagination_opts [Integer] :per_page Items per page
+        # @option pagination_opts [Integer] :total_count Total items (if known)
+        # @return [PaginatedCollection] Wrapped collection with pagination metadata
+        def paginated_collection(data, pagination_opts = {})
+          PaginatedCollection.new(
+            data: data,
+            page: pagination_opts[:page] || DEFAULT_PAGE,
+            per_page: pagination_opts[:per_page] || DEFAULT_PER_PAGE,
+            total_count: pagination_opts[:total_count]
+          )
+        end
+
+        # Apply client-side pagination to an array
+        # Used when API returns all results and we need to paginate locally
+        #
+        # @param items [Array] Full array of items
+        # @param options [Hash] Pagination options
+        # @return [PaginatedCollection] Paginated subset of items
+        def apply_client_side_pagination(items, options = {})
+          pagination_opts = normalize_pagination_options(options)
+          offset = pagination_opts[:offset]
+          limit = pagination_opts[:per_page]
+
+          # Slice the array based on offset and limit
+          page_data = items[offset, limit] || []
+
+          paginated_collection(
+            page_data,
+            page: pagination_opts[:page],
+            per_page: pagination_opts[:per_page],
+            total_count: items.length
+          )
+        end
+
+        # Build query parameters for API requests with pagination
+        # Converts internal pagination format to API-specific format
+        #
+        # @param options [Hash] Pagination options
+        # @param api_format [Symbol] API pagination format (:offset_limit or :page_per_page)
+        # @return [Hash] Query parameters for API request
+        def build_pagination_params(options = {}, api_format: :offset_limit)
+          pagination_opts = normalize_pagination_options(options)
+
+          case api_format
+          when :offset_limit
+            {
+              offset: pagination_opts[:offset],
+              limit: pagination_opts[:limit]
+            }
+          when :page_per_page
+            {
+              page: pagination_opts[:page],
+              per_page: pagination_opts[:per_page]
+            }
+          else
+            raise ArgumentError, "Unknown API format: #{api_format}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/petstore_api_client/clients/concerns/resource_operations.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  module Clients
+    module Concerns
+      # Shared resource operations using Template Method pattern
+      # Eliminates duplication between PetClient and StoreClient
+      #
+      # This module provides generic CRUD operations that work for any resource type.
+      # Subclasses just need to define:
+      # - model_class: The model class (e.g., Models::Pet)
+      # - resource_name: The API path segment (e.g., "pet", "store/order")
+      # - id_field_name: Human-readable name for validation errors (e.g., "Pet ID")
+      module ResourceOperations
+        # Template method for creating a resource
+        # Pattern: build → validate → POST → parse response
+        def create_resource(resource_data)
+          resource = build_resource(resource_data)
+          validate_resource!(resource)
+
+          resp = post(create_endpoint, body: resource.to_h)
+          model_class.from_response(resp.body)
+        end
+
+        # Template method for updating a resource
+        # Pattern: build → validate → PUT → parse response
+        def update_resource(resource_data)
+          resource = build_resource(resource_data)
+          validate_resource!(resource)
+
+          resp = put(update_endpoint, body: resource.to_h)
+          model_class.from_response(resp.body)
+        end
+
+        # Template method for getting a resource by ID
+        # Pattern: validate ID → GET → parse response
+        def get_resource(resource_id)
+          validate_id!(resource_id, id_field_name)
+
+          resp = get("#{resource_name}/#{resource_id}")
+          model_class.from_response(resp.body)
+        end
+
+        # Template method for deleting a resource
+        # Pattern: validate ID → DELETE → return success
+        def delete_resource(resource_id)
+          validate_id!(resource_id, id_field_name)
+
+          delete("#{resource_name}/#{resource_id}")
+          true
+        end
+
+        private
+
+        # Build a resource object from various input types
+        # Accepts either a model instance or hash of attributes
+        def build_resource(resource_data)
+          return resource_data if resource_data.is_a?(model_class)
+
+          model_class.new(resource_data)
+        end
+
+        # Validate resource data before sending to API
+        # Raises ValidationError if the model has validation errors
+        def validate_resource!(resource)
+          return if resource.valid?
+
+          raise ValidationError, "Invalid #{resource_type_name} data: #{resource.errors.full_messages.join(", ")}"
+        end
+
+        # Validate that an ID is present and numeric
+        # Accepts integers or numeric strings like "123"
+        def validate_id!(id, field_name = "ID")
+          raise ValidationError, "#{field_name} can't be nil" if id.nil?
+
+          # String IDs are fine as long as they're numeric
+          return if id.is_a?(Integer) || id.to_s.match?(/^\d+$/)
+
+          raise ValidationError, "#{field_name} must be an integer, got #{id.class}"
+        end
+
+        # Abstract method: Subclasses must define the model class
+        # Example: Models::Pet or Models::Order
+        def model_class
+          raise NotImplementedError, "#{self.class} must implement #model_class"
+        end
+
+        # Abstract method: Subclasses must define the resource name
+        # Example: "pet" or "store/order"
+        def resource_name
+          raise NotImplementedError, "#{self.class} must implement #resource_name"
+        end
+
+        # Abstract method: Subclasses must define the endpoint for creating
+        # Default implementation uses resource_name, but can be overridden
+        def create_endpoint
+          resource_name
+        end
+
+        # Abstract method: Subclasses must define the endpoint for updating
+        # Default implementation uses resource_name, but can be overridden
+        def update_endpoint
+          resource_name
+        end
+
+        # Human-readable field name for ID validation errors
+        # Default implementation capitalizes the resource name
+        # Can be overridden for custom formatting
+        def id_field_name
+          "#{resource_type_name} ID"
+        end
+
+        # Extract resource type name from model class for error messages
+        # Example: Models::Pet → "pet", Models::Order → "order"
+        def resource_type_name
+          model_class.name.split("::").last.downcase
+        end
+      end
+    end
+  end
+end