petstore_api_client 0.1.0

data/lib/petstore_api_client/api_client.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  # Main API client - this is what users interact with
+  class ApiClient
+    attr_reader :configuration
+
+    def initialize(config = nil)
+      @configuration = config || Configuration.new
+      @configuration.validate!
+    end
+
+    def configure
+      yield(configuration) if block_given?
+      # Reset clients when configuration changes
+      @pet_client = nil
+      @store_client = nil
+      self
+    end
+
+    # Access to Pet endpoints
+    def pets
+      @pets ||= Clients::PetClient.new(configuration)
+    end
+
+    # Access to Store endpoints
+    def store
+      @store ||= Clients::StoreClient.new(configuration)
+    end
+
+    # Convenience methods so you can do client.create_pet instead of client.pets.create_pet
+    def create_pet(pet_data)
+      pets.create_pet(pet_data)
+    end
+
+    def get_pet(pet_id)
+      pets.get_pet(pet_id)
+    end
+
+    def update_pet(pet_data)
+      pets.update_pet(pet_data)
+    end
+
+    def delete_pet(pet_id)
+      pets.delete_pet(pet_id)
+    end
+
+    def create_order(order_data)
+      store.create_order(order_data)
+    end
+
+    def get_order(order_id)
+      store.get_order(order_id)
+    end
+
+    def delete_order(order_id)
+      store.delete_order(order_id)
+    end
+  end
+end

data/lib/petstore_api_client/authentication/api_key.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PetstoreApiClient
+  module Authentication
+    # API Key authentication strategy
+    # Adds api_key header to requests
+    #
+    # The Swagger Petstore API accepts api_key in the request header.
+    # According to official docs, the special key is "special-key"
+    #
+    # Security best practices:
+    # - API keys are validated before use
+    # - Warnings issued for insecure (HTTP) connections
+    # - Supports loading from environment variables
+    #
+    # @example Direct instantiation
+    #   auth = ApiKey.new("special-key")
+    #
+    # @example From environment variable
+    #   ENV['PETSTORE_API_KEY'] = "special-key"
+    #   auth = ApiKey.from_env
+    class ApiKey < Base
+      # Header name for API key
+      # According to Swagger Petstore spec: https://petstore.swagger.io
+      HEADER_NAME = "api_key"
+
+      # Environment variable name for API key
+      ENV_VAR_NAME = "PETSTORE_API_KEY"
+
+      # Minimum length for API key (security validation)
+      MIN_KEY_LENGTH = 3
+
+      attr_reader :api_key
+
+      # Initialize API key authenticator
+      #
+      # @param api_key [String, nil] The API key to use
+      # @raise [ValidationError] if API key is invalid
+      # rubocop:disable Lint/MissingSuper
+      def initialize(api_key = nil)
+        @api_key = api_key&.to_s&.strip
+        validate! if configured?
+      end
+      # rubocop:enable Lint/MissingSuper
+
+      # Create authenticator from environment variable
+      #
+      # @return [ApiKey] New authenticator instance
+      def self.from_env
+        new(ENV.fetch(ENV_VAR_NAME, nil))
+      end
+
+      # Apply API key authentication to request
+      # Adds api_key header to the request
+      #
+      # @param env [Faraday::Env] The request environment
+      # @return [void]
+      def apply(env)
+        return unless configured?
+
+        # Warn if sending API key over insecure connection (HTTP)
+        warn_if_insecure!(env)
+
+        # Add API key header
+        env.request_headers[HEADER_NAME] = @api_key
+      end
+
+      # Check if API key is configured
+      #
+      # @return [Boolean]
+      def configured?
+        !@api_key.nil? && !@api_key.empty?
+      end
+
+      # String representation (masks API key for security)
+      #
+      # @return [String]
+      def inspect
+        return unconfigured_inspect unless configured?
+
+        # Use base class method to mask credential (show first 4 chars)
+        masked = mask_credential(@api_key, 4)
+
+        "#<#{self.class.name} api_key=#{masked}>"
+      end
+      alias to_s inspect
+
+      private
+
+      # Validate API key format and length
+      #
+      # @raise [ValidationError] if API key is invalid
+      def validate!
+        return unless configured?
+
+        # Use base class validation methods for DRY principle
+        validate_credential_length(@api_key, "API key", MIN_KEY_LENGTH)
+        validate_no_newlines(@api_key, "API key")
+        validate_no_whitespace(@api_key, "API key")
+      end
+
+      # Note: warn_if_insecure! method inherited from Base class
+    end
+  end
+end

data/lib/petstore_api_client/authentication/base.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  module Authentication
+    # Base class for authentication strategies
+    # Implements Strategy Pattern - allows different authentication methods
+    # to be swapped without changing client code
+    #
+    # This follows the same pattern as battle-tested gems like:
+    # - Octokit (GitHub API client)
+    # - Slack-ruby-client
+    # - Stripe Ruby library
+    class Base
+      # Apply authentication to a Faraday request environment
+      #
+      # @param env [Faraday::Env] The request environment
+      # @return [void]
+      def apply(env)
+        raise NotImplementedError, "#{self.class.name} must implement #apply"
+      end
+
+      # Check if this authentication strategy is configured
+      # Used to determine if auth should be applied
+      #
+      # @return [Boolean]
+      def configured?
+        raise NotImplementedError, "#{self.class.name} must implement #configured?"
+      end
+
+      # Human-readable description of authentication type
+      # Useful for logging and debugging
+      #
+      # @return [String]
+      def type
+        self.class.name.split("::").last
+      end
+
+      protected
+
+      # Validates that a credential meets minimum length requirements
+      #
+      # @param value [String] The credential value to validate
+      # @param field_name [String] Name of the field for error messages
+      # @param min_length [Integer] Minimum required length
+      # @raise [ValidationError] if credential is too short
+      # @return [void]
+      def validate_credential_length(value, field_name, min_length)
+        return if value.length >= min_length
+
+        raise ValidationError,
+              "#{field_name} must be at least #{min_length} characters (got #{value.length})"
+      end
+
+      # Validates that a credential doesn't contain newline characters
+      # Newlines can cause security issues and are never valid in credentials
+      #
+      # @param value [String] The credential value to validate
+      # @param field_name [String] Name of the field for error messages
+      # @raise [ValidationError] if credential contains newlines
+      # @return [void]
+      def validate_no_newlines(value, field_name)
+        return unless value.include?("\n") || value.include?("\r")
+
+        raise ValidationError, "#{field_name} contains newline characters"
+      end
+
+      # Validates that a credential doesn't have leading/trailing whitespace
+      # Whitespace usually indicates copy-paste errors
+      #
+      # @param value [String] The credential value to validate
+      # @param field_name [String] Name of the field for error messages
+      # @raise [ValidationError] if credential has whitespace
+      # @return [void]
+      def validate_no_whitespace(value, field_name)
+        return if value == value.strip
+
+        raise ValidationError,
+              "#{field_name} has leading/trailing whitespace (did you copy-paste incorrectly?)"
+      end
+
+      # Warns if authentication is being sent over insecure HTTP connection
+      # This is a security risk as credentials can be intercepted
+      #
+      # @param env [Faraday::Env] The request environment
+      # @return [void]
+      def warn_if_insecure!(env)
+        return if env.url.scheme == "https"
+
+        warn "[PetstoreApiClient] WARNING: Sending credentials over insecure HTTP connection! " \
+             "Use HTTPS in production to protect credentials."
+      end
+
+      # Masks a credential for safe display in logs and inspect output
+      # Shows first few characters and masks the rest
+      #
+      # @param value [String] The credential to mask
+      # @param visible_chars [Integer] Number of characters to show (default: 3)
+      # @return [String] Masked credential string
+      def mask_credential(value, visible_chars = 3)
+        return "***" if value.length <= visible_chars
+
+        "#{value[0...visible_chars]}#{"*" * (value.length - visible_chars)}"
+      end
+
+      # Standard inspect message for unconfigured authenticators
+      #
+      # @return [String] Inspect message
+      def unconfigured_inspect
+        "#<#{self.class.name} (not configured)>"
+      end
+    end
+  end
+end

data/lib/petstore_api_client/authentication/composite.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PetstoreApiClient
+  module Authentication
+    # Composite authentication strategy for applying multiple auth methods simultaneously
+    #
+    # This authenticator implements the Composite pattern, allowing multiple authentication
+    # strategies to be applied to a single request. This is particularly useful during
+    # migration periods when transitioning from one auth method to another, or when an
+    # API accepts multiple authentication methods.
+    #
+    # The Petstore API accepts both API Key and OAuth2 authentication. Using this composite
+    # authenticator, you can send both headers simultaneously, allowing the server to
+    # accept either authentication method.
+    #
+    # All configured strategies are applied in the order they were added. Each strategy's
+    # apply() method is called, allowing it to add its own headers to the request.
+    #
+    # @example Using both API Key and OAuth2
+    #   api_key_auth = ApiKey.new("special-key")
+    #   oauth2_auth = OAuth2.new(client_id: "id", client_secret: "secret")
+    #   composite = Composite.new([api_key_auth, oauth2_auth])
+    #
+    #   composite.apply(env)
+    #   # Request now has both:
+    #   # - api_key: special-key
+    #   # - Authorization: Bearer <token>
+    #
+    # @example Building from configuration
+    #   strategies = []
+    #   strategies << ApiKey.new(config.api_key) if config.api_key
+    #   strategies << OAuth2.new(...) if config.oauth2_client_id
+    #   composite = Composite.new(strategies)
+    #
+    # @see https://refactoring.guru/design-patterns/composite Composite Pattern
+    # @since 0.2.0
+    class Composite < Base
+      # @!attribute [r] strategies
+      #   @return [Array<Base>] List of authentication strategies to apply
+      attr_reader :strategies
+
+      # Initialize composite authenticator with multiple strategies
+      #
+      # @param strategies [Array<Base>] List of authentication strategies
+      #   Each strategy must respond to #apply(env) and #configured?
+      #
+      # @raise [ArgumentError] if strategies is not an array
+      # @raise [ArgumentError] if any strategy doesn't inherit from Base
+      #
+      # @example
+      #   api_key = ApiKey.new("my-key")
+      #   oauth2 = OAuth2.new(client_id: "id", client_secret: "secret")
+      #   composite = Composite.new([api_key, oauth2])
+      #
+      # rubocop:disable Lint/MissingSuper
+      def initialize(strategies = [])
+        raise ArgumentError, "strategies must be an Array (got #{strategies.class})" unless strategies.is_a?(Array)
+
+        validate_strategies!(strategies)
+        @strategies = strategies
+        # Performance optimization: cache configured strategies to avoid repeated checks
+        @configured_strategies = @strategies.select(&:configured?)
+      end
+      # rubocop:enable Lint/MissingSuper
+
+      # Apply all configured authentication strategies to the request
+      #
+      # Iterates through all strategies and calls apply() on each one if it's configured.
+      # This allows multiple authentication headers to be added to the same request.
+      #
+      # @param env [Faraday::Env] The Faraday request environment
+      # @return [void]
+      #
+      # @example
+      #   composite = Composite.new([api_key_auth, oauth2_auth])
+      #   composite.apply(env)
+      #   # Both authentication methods are now applied
+      #
+      def apply(env)
+        # Performance optimization: use cached configured strategies
+        # Avoids checking configured? on every request
+        @configured_strategies.each { |strategy| strategy.apply(env) }
+      end
+
+      # Check if any authentication strategy is configured
+      #
+      # Returns true if at least one strategy in the composite is configured.
+      # Returns false if no strategies are configured or if strategies array is empty.
+      #
+      # @return [Boolean] true if at least one strategy is configured
+      #
+      # @example
+      #   # No strategies configured
+      #   composite = Composite.new([])
+      #   composite.configured? # => false
+      #
+      #   # One strategy configured
+      #   api_key = ApiKey.new("my-key")
+      #   composite = Composite.new([api_key])
+      #   composite.configured? # => true
+      #
+      #   # Mixed (one configured, one not)
+      #   oauth2 = OAuth2.new # Not configured (no credentials)
+      #   composite = Composite.new([api_key, oauth2])
+      #   composite.configured? # => true (at least one is configured)
+      #
+      def configured?
+        # Performance optimization: use cached configured strategies
+        !@configured_strategies.empty?
+      end
+
+      # Get list of configured strategy types
+      #
+      # Returns array of type names for strategies that are actually configured.
+      # Useful for debugging and logging.
+      #
+      # @return [Array<String>] List of configured strategy type names
+      #
+      # @example
+      #   api_key = ApiKey.new("key")
+      #   oauth2 = OAuth2.new # Not configured
+      #   composite = Composite.new([api_key, oauth2])
+      #   composite.configured_types # => ["ApiKey"]
+      #
+      def configured_types
+        @strategies.select(&:configured?).map(&:type)
+      end
+
+      # String representation showing all configured strategies
+      #
+      # @return [String] Human-readable representation
+      #
+      # @example
+      #   composite = Composite.new([api_key, oauth2])
+      #   composite.inspect
+      #   # => "#<Composite strategies=[ApiKey, OAuth2] configured=[ApiKey, OAuth2]>"
+      #
+      def inspect
+        all_types = @strategies.map(&:type).join(", ")
+        configured = configured_types.join(", ")
+        configured = "none" if configured.empty?
+
+        "#<#{self.class.name} strategies=[#{all_types}] configured=[#{configured}]>"
+      end
+      alias to_s inspect
+
+      private
+
+      # Validate that all strategies are valid authentication strategy objects
+      #
+      # @param strategies [Array] List of strategies to validate
+      # @return [void]
+      # @raise [ArgumentError] if any strategy is invalid
+      #
+      def validate_strategies!(strategies)
+        strategies.each_with_index do |strategy, index|
+          unless strategy.is_a?(Base)
+            raise ArgumentError,
+                  "Strategy at index #{index} must inherit from Authentication::Base " \
+                  "(got #{strategy.class})"
+          end
+
+          unless strategy.respond_to?(:apply)
+            raise ArgumentError,
+                  "Strategy at index #{index} (#{strategy.class}) must respond to #apply"
+          end
+
+          unless strategy.respond_to?(:configured?)
+            raise ArgumentError,
+                  "Strategy at index #{index} (#{strategy.class}) must respond to #configured?"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/petstore_api_client/authentication/none.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PetstoreApiClient
+  module Authentication
+    # No authentication strategy (Null Object pattern)
+    # Used when no authentication is configured
+    #
+    # This allows the authentication system to always have an authenticator
+    # without needing nil checks everywhere
+    #
+    # @example
+    #   auth = None.new
+    #   auth.configured? # => false
+    #   auth.apply(env)  # Does nothing
+    class None < Base
+      # Apply no authentication (does nothing)
+      #
+      # @param _env [Faraday::Env] The request environment (unused)
+      # @return [void]
+      def apply(_env)
+        # Intentionally empty - no authentication to apply
+      end
+
+      # Check if authentication is configured
+      #
+      # @return [Boolean] Always false
+      def configured?
+        false
+      end
+
+      # String representation
+      #
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} (no authentication)>"
+      end
+      alias to_s inspect
+    end
+  end
+end