io-complyance-unify-sdk 3.0.0

data/lib/complyance_sdk/retry/circuit_breaker.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module ComplyanceSDK
+  module Retry
+    # Circuit breaker pattern implementation
+    # Prevents cascading failures by opening the circuit when too many failures occur
+    class CircuitBreaker
+      # Circuit breaker states
+      module State
+        CLOSED = :closed
+        OPEN = :open
+        HALF_OPEN = :half_open
+      end
+
+      attr_reader :state, :failure_count, :last_failure_time, :config
+
+      # Initialize a new circuit breaker
+      #
+      # @param config [Hash] Circuit breaker configuration
+      # @option config [Integer] :failure_threshold Number of failures before opening (default: 5)
+      # @option config [Integer] :timeout_seconds Timeout before attempting reset (default: 60)
+      # @option config [Integer] :success_threshold Successes needed to close from half-open (default: 1)
+      def initialize(config = {})
+        @config = {
+          failure_threshold: 5,
+          timeout_seconds: 60,
+          success_threshold: 1
+        }.merge(config)
+
+        @state = State::CLOSED
+        @failure_count = 0
+        @last_failure_time = nil
+        @success_count = 0
+        @mutex = Mutex.new
+      end
+
+      # Execute a block with circuit breaker protection
+      #
+      # @yield The block to execute
+      # @return The result of the block
+      # @raise [ComplyanceSDK::Exceptions::CircuitBreakerOpenError] If circuit is open
+      def execute
+        @mutex.synchronize do
+          case @state
+          when State::OPEN
+            if should_attempt_reset?
+              @state = State::HALF_OPEN
+              @success_count = 0
+            else
+              raise ComplyanceSDK::Exceptions::CircuitBreakerOpenError.new(
+                'Circuit breaker is open',
+                context: {
+                  failure_count: @failure_count,
+                  last_failure_time: @last_failure_time,
+                  timeout_seconds: @config[:timeout_seconds]
+                }
+              )
+            end
+          end
+        end
+
+        begin
+          result = yield
+          on_success
+          result
+        rescue => e
+          on_failure
+          raise e
+        end
+      end
+
+      # Check if circuit breaker is open
+      #
+      # @return [Boolean] True if open
+      def open?
+        @state == State::OPEN
+      end
+
+      # Check if circuit breaker is closed
+      #
+      # @return [Boolean] True if closed
+      def closed?
+        @state == State::CLOSED
+      end
+
+      # Check if circuit breaker is half-open
+      #
+      # @return [Boolean] True if half-open
+      def half_open?
+        @state == State::HALF_OPEN
+      end
+
+      # Get circuit breaker statistics
+      #
+      # @return [Hash] Statistics hash
+      def stats
+        {
+          state: @state,
+          failure_count: @failure_count,
+          last_failure_time: @last_failure_time,
+          success_count: @success_count,
+          config: @config
+        }
+      end
+
+      # Reset the circuit breaker to closed state
+      def reset!
+        @mutex.synchronize do
+          @state = State::CLOSED
+          @failure_count = 0
+          @last_failure_time = nil
+          @success_count = 0
+        end
+      end
+
+      private
+
+      # Handle successful execution
+      def on_success
+        @mutex.synchronize do
+          case @state
+          when State::HALF_OPEN
+            @success_count += 1
+            if @success_count >= @config[:success_threshold]
+              @state = State::CLOSED
+              @failure_count = 0
+              @last_failure_time = nil
+              @success_count = 0
+            end
+          when State::CLOSED
+            # Reset failure count on successful execution in closed state
+            @failure_count = 0 if @failure_count > 0
+          end
+        end
+      end
+
+      # Handle failed execution
+      def on_failure
+        @mutex.synchronize do
+          @failure_count += 1
+          @last_failure_time = Time.now
+
+          if @failure_count >= @config[:failure_threshold]
+            @state = State::OPEN
+          end
+        end
+      end
+
+      # Check if circuit breaker should attempt to reset
+      #
+      # @return [Boolean] True if should attempt reset
+      def should_attempt_reset?
+        return false unless @last_failure_time
+        
+        Time.now - @last_failure_time >= @config[:timeout_seconds]
+      end
+    end
+  end
+end

data/lib/complyance_sdk/retry/retry_manager.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "circuit_breaker"
+require_relative "retry_strategy"
+
+module ComplyanceSDK
+  module Retry
+    # Manager class that coordinates retry strategies and circuit breakers
+    class RetryManager
+      # Initialize a new retry manager
+      #
+      # @param config [ComplyanceSDK::Config::SDKConfig] The SDK configuration
+      # @param redis_config [Hash] Redis configuration for circuit breaker
+      def initialize(config, redis_config = {})
+        @config = config
+        @redis_config = redis_config
+        @circuit_breakers = {}
+      end
+
+      # Execute a block with retry logic and circuit breaker protection
+      #
+      # @param operation_name [String] Name of the operation for circuit breaker
+      # @param context [Hash] Context information for logging/debugging
+      # @yield The block to execute
+      # @return The result of the block
+      def execute(operation_name, context = {})
+        circuit_breaker = get_circuit_breaker(operation_name)
+        retry_strategy = RetryStrategy.new(@config.retry_config, circuit_breaker)
+        
+        retry_strategy.execute(context.merge(operation: operation_name)) do
+          yield
+        end
+      end
+
+      # Execute a block asynchronously using background jobs
+      #
+      # @param request_data [Hash] The request data
+      # @param job_type [Symbol] The job type (:active_job or :sidekiq)
+      # @param callback_url [String, nil] Optional callback URL
+      # @param callback_headers [Hash] Optional callback headers
+      # @return [String, Object] Job ID or job object
+      def execute_async(request_data, job_type: :active_job, callback_url: nil, callback_headers: {})
+        case job_type
+        when :active_job
+          if defined?(ActiveJob)
+            require_relative "../jobs/process_document_job"
+            job = Jobs::ProcessDocumentJob.perform_later(request_data, callback_url, callback_headers)
+            job.job_id
+          else
+            raise ComplyanceSDK::Exceptions::ConfigurationError.new(
+              "ActiveJob is not available. Please add 'activejob' to your Gemfile."
+            )
+          end
+        when :sidekiq
+          if defined?(Sidekiq)
+            require_relative "../jobs/sidekiq_job"
+            Jobs::SidekiqJob.perform_async(request_data, callback_url, callback_headers)
+          else
+            raise ComplyanceSDK::Exceptions::ConfigurationError.new(
+              "Sidekiq is not available. Please add 'sidekiq' to your Gemfile."
+            )
+          end
+        else
+          raise ArgumentError, "Invalid job_type: #{job_type}. Must be :active_job or :sidekiq"
+        end
+      end
+
+      # Get circuit breaker status for an operation
+      #
+      # @param operation_name [String] Name of the operation
+      # @return [Hash] Circuit breaker status information
+      def circuit_breaker_status(operation_name)
+        circuit_breaker = get_circuit_breaker(operation_name)
+        
+        {
+          name: operation_name,
+          state: circuit_breaker.current_state,
+          failure_count: circuit_breaker.failure_count,
+          last_failure_time: circuit_breaker.last_failure_time,
+          disabled: circuit_breaker.disabled?
+        }
+      end
+
+      # Reset a circuit breaker
+      #
+      # @param operation_name [String] Name of the operation
+      def reset_circuit_breaker(operation_name)
+        circuit_breaker = get_circuit_breaker(operation_name)
+        circuit_breaker.reset!
+      end
+
+      # Reset all circuit breakers
+      def reset_all_circuit_breakers
+        @circuit_breakers.each_value(&:reset!)
+      end
+
+      private
+
+      def get_circuit_breaker(operation_name)
+        @circuit_breakers[operation_name] ||= CircuitBreaker.new(
+          operation_name,
+          @config.retry_config,
+          @redis_config
+        )
+      end
+    end
+  end
+end

data/lib/complyance_sdk/retry/retry_strategy.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module ComplyanceSDK
+  module Retry
+    # Advanced retry strategy with exponential backoff, jitter, and circuit breaker
+    # Ruby equivalent of the Java RetryStrategy
+    class RetryStrategy
+      attr_reader :config, :circuit_breaker, :logger
+
+      # Initialize a new retry strategy
+      #
+      # @param config [ComplyanceSDK::Config::RetryConfig] The retry configuration
+      # @param circuit_breaker [CircuitBreaker, nil] Optional circuit breaker
+      # @param logger [Logger, nil] Optional logger instance
+      def initialize(config, circuit_breaker = nil, logger = nil)
+        @config = config
+        @circuit_breaker = circuit_breaker
+        @logger = logger || Logger.new(STDOUT)
+      end
+
+      # Execute a block with retry logic
+      #
+      # @param operation_name [String] Name of the operation for logging
+      # @param context [Hash] Context information for logging/debugging
+      # @yield The block to execute
+      # @return The result of the block
+      def execute(operation_name = 'operation', context = {})
+        attempt = 1
+        last_exception = nil
+
+        while attempt <= @config.max_attempts
+          begin
+            @logger.debug("Attempting operation '#{operation_name}' (attempt #{attempt}/#{@config.max_attempts})")
+
+            result = if @circuit_breaker
+                       @circuit_breaker.execute { yield }
+                     else
+                       yield
+                     end
+
+            if attempt > 1
+              @logger.info("Operation '#{operation_name}' succeeded on attempt #{attempt}")
+            end
+
+            return result
+          rescue ComplyanceSDK::Exceptions::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 * 1000).round}ms")
+
+            sleep(delay)
+          rescue => e
+            # Handle non-SDK exceptions
+            @logger.error("Unexpected error in operation '#{operation_name}': #{e.message}")
+
+            error_detail = {
+              code: :processing_error,
+              message: "Unexpected error: #{e.message}",
+              suggestion: "This appears to be an unexpected error. Please contact support if it persists",
+              context: { original_exception: e.class.name }
+            }
+            
+            raise ComplyanceSDK::Exceptions::SDKException.new(
+              "Unexpected error: #{e.message}",
+              context: error_detail
+            )
+          end
+
+          attempt += 1
+        end
+
+        # All retries exhausted
+        @logger.error("Operation '#{operation_name}' failed after #{@config.max_attempts} attempts")
+        
+        if last_exception
+          raise last_exception
+        else
+          error_detail = {
+            code: :max_retries_exceeded,
+            message: "Max retries exceeded",
+            suggestion: "Operation failed after #{@config.max_attempts} attempts",
+            context: { attempts: @config.max_attempts }
+          }
+          
+          raise ComplyanceSDK::Exceptions::SDKException.new(
+            "Max retries exceeded",
+            context: error_detail
+          )
+        end
+      end
+
+      # Get the current circuit breaker state (for monitoring)
+      #
+      # @return [Symbol, nil] The circuit breaker state or nil if no circuit breaker
+      def circuit_breaker_state
+        @circuit_breaker&.state
+      end
+
+      # Get circuit breaker statistics (for monitoring)
+      #
+      # @return [String] Circuit breaker statistics string
+      def circuit_breaker_stats
+        if @circuit_breaker
+          stats = @circuit_breaker.stats
+          "CircuitBreaker{state=#{stats[:state]}, failures=#{stats[:failure_count]}, last_failure=#{stats[:last_failure_time]}}"
+        else
+          'Circuit breaker disabled'
+        end
+      end
+
+      # Reset the circuit breaker (for testing/administrative purposes)
+      def reset_circuit_breaker!
+        if @circuit_breaker
+          @circuit_breaker.reset!
+          @logger.info('Circuit breaker reset')
+        else
+          @logger.warn('Circuit breaker reset requested but no circuit breaker configured')
+        end
+      end
+
+      private
+
+      # Determine if an error should be retried
+      #
+      # @param error [ComplyanceSDK::Exceptions::SDKException] The error
+      # @param attempt [Integer] Current attempt number
+      # @return [Boolean] True if should retry
+      def should_retry?(error, attempt)
+        return false if attempt >= @config.max_attempts
+
+        error_detail = error.context
+        return false unless error_detail
+
+        # Check if explicitly marked as retryable
+        return true if error_detail[:retryable] == true
+
+        # Check if error code is in retryable list
+        return true if @config.retryable_error_codes.include?(error_detail[:code])
+
+        # Check if HTTP status is retryable
+        http_status = error_detail.dig(:context, :http_status) || error_detail[:http_status]
+        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 [Float] Delay in seconds
+      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 # -jitter_factor to +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 = [delay_ms, 0].max
+
+        # Convert to seconds
+        delay_ms / 1000.0
+      end
+
+      # Check if error is retryable based on class
+      #
+      # @param error [Exception] The error to check
+      # @return [Boolean] True if retryable
+      def retryable_error_class?(error)
+        retryable_classes = [
+          ComplyanceSDK::Exceptions::NetworkError,
+          Timeout::Error,
+          Errno::ECONNREFUSED,
+          Errno::ECONNRESET,
+          Errno::EHOSTUNREACH,
+          Errno::ENETUNREACH,
+          Faraday::ConnectionFailed,
+          Faraday::TimeoutError,
+          Faraday::SSLError
+        ]
+
+        retryable_classes.any? { |klass| error.is_a?(klass) }
+      end
+
+      # Check if API error is retryable based on status code
+      #
+      # @param error [ComplyanceSDK::Exceptions::APIError] The API error
+      # @return [Boolean] True if retryable
+      def retryable_api_error?(error)
+        return false unless error.respond_to?(:status_code) && error.status_code
+
+        @config.retryable_http_codes.include?(error.status_code)
+      end
+    end
+
+    # Exception raised when all retry attempts are exhausted
+    class RetryExhaustedError < ComplyanceSDK::Exceptions::SDKException
+      def initialize(message = "All retry attempts exhausted", **kwargs)
+        super(message, context: { code: :retry_exhausted, **kwargs })
+      end
+    end
+  end
+end

data/lib/complyance_sdk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ComplyanceSDK
+  VERSION = "3.0.0"
+end