io-complyance-unify-sdk 3.0.0

data/lib/complyance/retry_strategy.rb

@@ -0,0 +1,198 @@
+require 'logger'
+require_relative 'circuit_breaker'
+require_relative 'error_detail'
+require_relative 'sdk_exception'
+
+module Complyance
+  # Advanced retry strategy with exponential backoff, jitter, and circuit breaker
+  class RetryStrategy
+    # Initialize retry strategy
+    # @param config [Hash] Retry configuration
+    # @option config [Integer] :max_attempts Maximum number of retry attempts
+    # @option config [Integer] :base_delay Base delay in milliseconds
+    # @option config [Integer] :max_delay Maximum delay in milliseconds
+    # @option config [Float] :backoff_multiplier Multiplier for exponential backoff
+    # @option config [Float] :jitter_factor Random jitter factor (0-1)
+    # @option config [Array<String>] :retryable_errors List of error codes to retry
+    # @option config [Array<Integer>] :retryable_http_codes List of HTTP status codes to retry
+    # @option config [Boolean] :circuit_breaker_enabled Whether to use circuit breaker
+    # @option config [Hash] :circuit_breaker_config Circuit breaker configuration
+    def initialize(config = {})
+      @config = {
+        max_attempts: 3,
+        base_delay: 1000,
+        max_delay: 30000,
+        backoff_multiplier: 2.0,
+        jitter_factor: 0.2,
+        retryable_errors: ['RATE_LIMIT_EXCEEDED', 'SERVICE_UNAVAILABLE'],
+        retryable_http_codes: [408, 429, 500, 502, 503, 504],
+        circuit_breaker_enabled: true,
+        circuit_breaker_config: {
+          failure_threshold: 3,
+          reset_timeout: 60
+        }
+      }.merge(config)
+
+      @logger = Logger.new(STDOUT)
+      @logger.level = Logger::INFO
+
+      if @config[:circuit_breaker_enabled]
+        @circuit_breaker = CircuitBreaker.new(@config[:circuit_breaker_config])
+      end
+    end
+
+    # Execute a function with retry logic
+    # @param operation [Proc] Function to execute
+    # @param operation_name [String] Name of operation for logging
+    # @return [Object] Result of operation
+    # @raise [SDKException] If all retries fail
+    def execute(operation_name, &operation)
+      attempt = 1
+      last_exception = nil
+
+      while attempt <= @config[:max_attempts]
+        begin
+          @logger.debug "Attempting operation '#{operation_name}' (attempt #{attempt}/#{@config[:max_attempts]})"
+
+          # Use circuit breaker if enabled
+          result = if @circuit_breaker
+            begin
+              @circuit_breaker.execute(&operation)
+            rescue RuntimeError => e
+              if e.message.include?('Circuit breaker is open')
+                raise SDKException.new(ErrorDetail.new(
+                  'CIRCUIT_BREAKER_OPEN',
+                  e.message
+                ))
+              end
+              raise e
+            end
+          else
+            operation.call
+          end
+
+          if attempt > 1
+            @logger.info "Operation '#{operation_name}' succeeded on attempt #{attempt}"
+          end
+
+          return result
+
+        rescue SDKException => e
+          last_exception = e
+
+          # Check if this error should be retried
+          unless should_retry?(e, attempt)
+            @logger.debug "Operation '#{operation_name}' failed with non-retryable error: #{e.message}"
+            raise e
+          end
+
+          # If this was the last attempt, don't wait
+          break if attempt >= @config[:max_attempts]
+
+          # Calculate delay and wait
+          delay = calculate_delay(attempt)
+          @logger.warn "Operation '#{operation_name}' failed on attempt #{attempt} (#{e.message}), retrying in #{delay}ms"
+
+          sleep(delay / 1000.0) # Convert ms to seconds
+
+        rescue StandardError => e
+          @logger.error "Unexpected error in operation '#{operation_name}': #{e.message}"
+
+          error = ErrorDetail.new(
+            'PROCESSING_ERROR',
+            "Unexpected error: #{e.message}"
+          )
+          error.suggestion = "This appears to be an unexpected error. Please contact support if it persists"
+          error.add_context_value('originalException', e.class.name)
+          raise SDKException.new(error)
+        end
+
+        attempt += 1
+      end
+
+      # All retries exhausted
+      @logger.error "Operation '#{operation_name}' failed after #{@config[:max_attempts]} attempts"
+      raise last_exception || SDKException.new(ErrorDetail.new(
+        'MAX_RETRIES_EXCEEDED',
+        "Maximum retry attempts (#{@config[:max_attempts]}) exceeded"
+      ))
+    end
+
+    # Get the current circuit breaker state (for monitoring)
+    # @return [String, nil] Current circuit breaker state
+    def circuit_breaker_state
+      @circuit_breaker&.state
+    end
+
+    # Get circuit breaker statistics (for monitoring)
+    # @return [String] Circuit breaker stats
+    def circuit_breaker_stats
+      if @circuit_breaker
+        "CircuitBreaker{state=#{@circuit_breaker.state}, failures=#{@circuit_breaker.failure_count}, " \
+        "lastFailure=#{@circuit_breaker.last_failure_time}}"
+      else
+        "Circuit breaker disabled"
+      end
+    end
+
+    private
+
+    # Determine if an error should be retried
+    # @param e [SDKException] Exception to check
+    # @param attempt [Integer] Current attempt number
+    # @return [Boolean] True if error should be retried
+    def should_retry?(e, attempt)
+      return false if attempt >= @config[:max_attempts]
+
+      detail = e.error_detail
+      return false unless detail
+
+      # If circuit breaker is open, check if we should wait for timeout
+      if detail.code == 'CIRCUIT_BREAKER_OPEN'
+        if e.message =~ /(\d+) seconds remaining/
+          remaining_seconds = $1.to_i
+          delay = remaining_seconds * 1000
+          @logger.info "Circuit breaker is open - waiting for #{remaining_seconds} seconds before retrying"
+          sleep(delay / 1000.0) # Convert ms to seconds
+          return true
+        end
+        return false
+      end
+
+      # Check if explicitly marked as retryable
+      return true if detail.retryable?
+
+      # Check if error code is in retryable list
+      return true if @config[:retryable_errors].include?(detail.code)
+
+      # Check if HTTP status is retryable
+      http_status = detail.context_value('httpStatus')
+      if http_status
+        status_code = http_status.to_i
+        return true if @config[:retryable_http_codes].include?(status_code)
+      end
+
+      false
+    end
+
+    # Calculate delay for next retry with exponential backoff and jitter
+    # @param attempt [Integer] Current attempt number
+    # @return [Integer] Delay in milliseconds
+    def calculate_delay(attempt)
+      # Start with base delay and apply exponential backoff
+      delay_ms = @config[:base_delay] * (@config[:backoff_multiplier] ** (attempt - 1))
+
+      # Apply jitter to avoid thundering herd
+      if @config[:jitter_factor] > 0
+        jitter = (rand * 2 - 1) * @config[:jitter_factor]
+        delay_ms = delay_ms * (1 + jitter)
+      end
+
+      # Cap at max delay
+      delay_ms = [delay_ms, @config[:max_delay]].min
+
+      # Ensure minimum delay
+      [delay_ms, 0].max.to_i
+    end
+  end
+end

data/lib/complyance_sdk/config/retry_config.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module ComplyanceSDK
+  module Config
+    # Configuration for retry behavior
+    class RetryConfig
+      # Maximum number of retry attempts
+      attr_accessor :max_attempts
+      
+      # Base delay between retries in seconds
+      attr_accessor :base_delay
+      
+      # Maximum delay between retries in seconds
+      attr_accessor :max_delay
+      
+      # Backoff multiplier for exponential backoff
+      attr_accessor :backoff_multiplier
+      
+      # Jitter factor to add randomness to retry delays
+      attr_accessor :jitter_factor
+      
+      # Whether circuit breaker is enabled
+      attr_accessor :circuit_breaker_enabled
+      
+      # Failure threshold for circuit breaker
+      attr_accessor :failure_threshold
+      
+      # Circuit breaker timeout in seconds
+      attr_accessor :circuit_breaker_timeout
+      
+      # HTTP status codes that should trigger a retry
+      attr_accessor :retryable_http_codes
+      
+      # Error codes that should trigger a retry
+      attr_accessor :retryable_error_codes
+      
+      # Initialize a new retry configuration
+      #
+      # @param options [Hash] Configuration options
+      # @option options [Integer] :max_attempts Maximum number of retry attempts
+      # @option options [Float] :base_delay Base delay between retries in seconds
+      # @option options [Float] :max_delay Maximum delay between retries in seconds
+      # @option options [Float] :backoff_multiplier Backoff multiplier for exponential backoff
+      # @option options [Float] :jitter_factor Jitter factor to add randomness to retry delays
+      # @option options [Boolean] :circuit_breaker_enabled Whether circuit breaker is enabled
+      # @option options [Integer] :failure_threshold Failure threshold for circuit breaker
+      # @option options [Float] :circuit_breaker_timeout Circuit breaker timeout in seconds
+      # @option options [Array<Integer>] :retryable_http_codes HTTP status codes that should trigger a retry
+      def initialize(options = {})
+        @max_attempts = options.fetch(:max_attempts, 3)
+        @base_delay = options.fetch(:base_delay, 1000) # Base delay in milliseconds to match Java
+        @max_delay = options.fetch(:max_delay, 30000) # Max delay in milliseconds to match Java
+        @backoff_multiplier = options.fetch(:backoff_multiplier, 2.0)
+        @jitter_factor = options.fetch(:jitter_factor, 0.2)
+        @circuit_breaker_enabled = options.fetch(:circuit_breaker_enabled, true)
+        @failure_threshold = options.fetch(:failure_threshold, 5)
+        @circuit_breaker_timeout = options.fetch(:circuit_breaker_timeout, 60.0)
+        @retryable_http_codes = options.fetch(:retryable_http_codes, [408, 429, 500, 502, 503, 504])
+        @retryable_error_codes = options.fetch(:retryable_error_codes, [:network_error, :timeout_error, :rate_limited, :temporary_error])
+      end
+      
+      # Create a default retry configuration
+      #
+      # @return [RetryConfig] The default retry configuration
+      def self.default
+        new
+      end
+      
+      # Create an aggressive retry configuration
+      #
+      # @return [RetryConfig] An aggressive retry configuration
+      def self.aggressive
+        new(
+          max_attempts: 7,
+          base_delay: 0.2,
+          max_delay: 10.0,
+          backoff_multiplier: 1.5,
+          jitter_factor: 0.1,
+          circuit_breaker_timeout: 30.0
+        )
+      end
+      
+      # Create a conservative retry configuration
+      #
+      # @return [RetryConfig] A conservative retry configuration
+      def self.conservative
+        new(
+          max_attempts: 3,
+          base_delay: 2.0,
+          max_delay: 60.0,
+          backoff_multiplier: 3.0,
+          jitter_factor: 0.3,
+          failure_threshold: 3,
+          circuit_breaker_timeout: 120.0
+        )
+      end
+      
+      # Create a retry configuration with no retries
+      #
+      # @return [RetryConfig] A retry configuration with no retries
+      def self.none
+        new(
+          max_attempts: 1,
+          circuit_breaker_enabled: false
+        )
+      end
+      
+      # Get circuit breaker configuration
+      #
+      # @return [Hash] Circuit breaker configuration hash
+      def circuit_breaker_config
+        {
+          failure_threshold: @failure_threshold,
+          timeout_seconds: @circuit_breaker_timeout.to_i,
+          success_threshold: 1
+        }
+      end
+      
+      # Check if circuit breaker is enabled
+      #
+      # @return [Boolean] True if circuit breaker is enabled
+      def circuit_breaker_enabled?
+        @circuit_breaker_enabled
+      end
+    end
+  end
+end

data/lib/complyance_sdk/config/sdk_config.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module ComplyanceSDK
+  module Config
+    # Configuration class for the Complyance SDK
+    class SDKConfig
+      
+      # API key for authentication
+      attr_accessor :api_key
+      
+      # Environment (sandbox, production)
+      attr_accessor :environment
+      
+      # Array of sources
+      attr_accessor :sources
+      
+      # Retry configuration
+      attr_accessor :retry_config
+      
+      # Logging configuration
+      attr_accessor :logging_enabled
+      
+      # Log level
+      attr_accessor :log_level
+      
+      # Auto-generate tax destination flag
+      attr_accessor :auto_generate_tax_destination
+      
+      # Correlation ID for request tracking
+      attr_accessor :correlation_id
+      
+      # Initialize a new configuration
+      #
+      # @param options [Hash] Configuration options
+      # @option options [String] :api_key API key for authentication
+      # @option options [String, Symbol] :environment Environment (sandbox, production)
+      # @option options [Array<ComplyanceSDK::Models::Source>] :sources Array of sources
+      # @option options [ComplyanceSDK::Config::RetryConfig] :retry_config Retry configuration
+      # @option options [Boolean] :logging_enabled Whether logging is enabled
+      # @option options [Symbol] :log_level Log level (:debug, :info, :warn, :error)
+      def initialize(options = {})
+        @api_key = options[:api_key]
+        @environment = parse_environment(options[:environment])
+        @sources = options[:sources] || []
+        @retry_config = options[:retry_config] || RetryConfig.default
+        @logging_enabled = options.fetch(:logging_enabled, true)
+        @log_level = options.fetch(:log_level, :info)
+        @auto_generate_tax_destination = options.fetch(:auto_generate_tax_destination, true)
+        @correlation_id = options[:correlation_id]
+        @errors = {}
+      end
+      
+      # Check if the configuration is valid
+      #
+      # @return [Boolean] True if valid, false otherwise
+      def valid?
+        @errors = {}
+        validate
+        @errors.empty?
+      end
+      
+      # Get validation errors
+      #
+      # @return [Hash] Hash of validation errors
+      def errors
+        @errors ||= {}
+      end
+      
+      # Create a configuration from environment variables
+      #
+      # @return [SDKConfig] The configuration object
+      def self.from_env
+        new(
+          api_key: ENV["COMPLYANCE_API_KEY"],
+          environment: ENV["COMPLYANCE_ENVIRONMENT"],
+          logging_enabled: ENV.fetch("COMPLYANCE_LOGGING_ENABLED", "true") == "true",
+          log_level: ENV.fetch("COMPLYANCE_LOG_LEVEL", "info").to_sym
+        )
+      end
+      
+      # Create a configuration from Rails credentials
+      #
+      # @param environment [Symbol] The Rails environment (:development, :production, etc.)
+      # @return [SDKConfig] The configuration object
+      def self.from_rails(environment = nil)
+        return unless defined?(Rails)
+        
+        env = environment || Rails.env.to_sym
+        credentials = Rails.application.credentials
+        
+        config = if credentials.dig(:complyance, env)
+                  credentials.dig(:complyance, env)
+                else
+                  credentials.dig(:complyance) || {}
+                end
+        
+        new(
+          api_key: config[:api_key],
+          environment: config[:environment],
+          logging_enabled: config.fetch(:logging_enabled, true),
+          log_level: config.fetch(:log_level, :info).to_sym
+        )
+      end
+      
+      # Create a configuration from a YAML file
+      #
+      # @param path [String] Path to the YAML file
+      # @return [SDKConfig] The configuration object
+      def self.from_file(path)
+        require "erb"
+        
+        # Process ERB templates in YAML files
+        erb_content = ERB.new(File.read(path)).result
+        config = YAML.safe_load(erb_content, symbolize_names: true)
+        
+        # Handle sources array
+        if config[:sources].is_a?(Array)
+          config[:sources] = config[:sources].map do |source_config|
+            ComplyanceSDK::Models::Source.new(source_config)
+          end
+        end
+        
+        # Handle retry_config hash
+        if config[:retry_config].is_a?(Hash)
+          config[:retry_config] = RetryConfig.new(config[:retry_config])
+        end
+        
+        # Convert log_level to symbol if it's a string
+        if config[:log_level].is_a?(String)
+          config[:log_level] = config[:log_level].to_sym
+        end
+        
+        new(config)
+      end
+      
+      # Add a source to the configuration
+      #
+      # @param source [ComplyanceSDK::Models::Source] The source to add
+      # @return [Array<ComplyanceSDK::Models::Source>] The updated sources array
+      def add_source(source)
+        @sources << source
+        @sources
+      end
+      
+      # Check if auto-generate tax destination is enabled
+      #
+      # @return [Boolean] True if auto-generate is enabled
+      def auto_generate_tax_destination?
+        @auto_generate_tax_destination
+      end
+      
+      private
+      
+      def parse_environment(env)
+        return nil if env.nil?
+        
+        case env.to_s.downcase
+        when "production", "prod"
+          ComplyanceSDK::Models::Environment::PRODUCTION
+        when "sandbox", "test"
+          ComplyanceSDK::Models::Environment::SANDBOX
+        when "local", "development", "dev"
+          ComplyanceSDK::Models::Environment::LOCAL
+        else
+          # Return the original value for validation error
+          env.is_a?(Symbol) ? env : env.to_sym
+        end
+      end
+      
+      def validate
+        validate_api_key
+        validate_environment
+        validate_sources
+      end
+      
+      def validate_api_key
+        if @api_key.nil? || @api_key.empty?
+          add_error(:api_key, "can't be blank")
+        end
+      end
+      
+      def validate_environment
+        if @environment.nil?
+          add_error(:environment, "can't be blank")
+        elsif ![
+          ComplyanceSDK::Models::Environment::PRODUCTION,
+          ComplyanceSDK::Models::Environment::SANDBOX,
+          ComplyanceSDK::Models::Environment::LOCAL
+        ].include?(@environment)
+          add_error(:environment, "must be a valid environment")
+        end
+      end
+      
+      def validate_sources
+        return if @sources.nil? || @sources.empty?
+        
+        @sources.each_with_index do |source, index|
+          unless source.is_a?(ComplyanceSDK::Models::Source)
+            add_error(:sources, "item at index #{index} is not a valid Source")
+          end
+        end
+      end
+      
+      def add_error(field, message)
+        @errors[field] ||= []
+        @errors[field] << message
+      end
+    end
+  end
+end

data/lib/complyance_sdk/exceptions/circuit_breaker_open_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'sdk_exception'
+
+module ComplyanceSDK
+  module Exceptions
+    # Exception raised when circuit breaker is open
+    class CircuitBreakerOpenError < SDKException
+      def initialize(message = "Circuit breaker is open", **kwargs)
+        super(message, context: { code: :circuit_breaker_open, **kwargs })
+      end
+    end
+  end
+end

data/lib/complyance_sdk/exceptions/sdk_exception.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module ComplyanceSDK
+  module Exceptions
+    # Base exception class for all SDK exceptions
+    class SDKException < StandardError
+      # Error code
+      attr_reader :code
+      
+      # Error context
+      attr_reader :context
+      
+      # Suggested action to resolve the error
+      attr_reader :suggestion
+      
+      # Initialize a new SDK exception
+      #
+      # @param message [String] Error message
+      # @param code [Symbol] Error code
+      # @param context [Hash] Error context
+      # @param suggestion [String] Suggested action to resolve the error
+      def initialize(message, code: nil, context: {}, suggestion: nil)
+        super(message)
+        @code = code
+        @context = context
+        @suggestion = suggestion
+      end
+      
+      # Convert the exception to a hash
+      #
+      # @return [Hash] The exception as a hash
+      def to_h
+        {
+          code: @code,
+          message: message,
+          context: @context,
+          suggestion: @suggestion
+        }
+      end
+    end
+    
+    # Exception raised when the SDK is not configured
+    class ConfigurationError < SDKException
+      def initialize(message = "SDK is not configured", **kwargs)
+        super(message, code: :configuration_error, **kwargs)
+      end
+    end
+    
+    # Exception raised when validation fails
+    class ValidationError < SDKException
+      def initialize(message = "Validation failed", **kwargs)
+        super(message, code: :validation_error, **kwargs)
+      end
+    end
+    
+    # Exception raised when a network error occurs
+    class NetworkError < SDKException
+      def initialize(message = "Network error", **kwargs)
+        super(message, code: :network_error, **kwargs)
+      end
+    end
+    
+    # Exception raised when an API error occurs
+    class APIError < SDKException
+      # HTTP status code
+      attr_reader :status_code
+      
+      # Initialize a new API error
+      #
+      # @param message [String] Error message
+      # @param status_code [Integer] HTTP status code
+      # @param kwargs [Hash] Additional arguments
+      def initialize(message = "API error", status_code: nil, **kwargs)
+        super(message, code: :api_error, **kwargs)
+        @status_code = status_code
+      end
+      
+      # Get error detail (alias for context)
+      #
+      # @return [Hash] Error detail hash
+      def error_detail
+        @context
+      end
+
+      # Convert the exception to a hash
+      #
+      # @return [Hash] The exception as a hash
+      def to_h
+        super.merge(status_code: @status_code)
+      end
+    end
+  end
+end