dilisense_pep_client 0.1.0

data/lib/dilisense_pep_client/circuit_breaker.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "concurrent-ruby"
+
+module DilisensePepClient
+  # Circuit breaker implementation for API resilience and fault tolerance
+  # 
+  # This class implements the Circuit Breaker pattern to protect against cascading failures
+  # when the Dilisense API becomes unavailable or starts returning errors frequently.
+  # It prevents unnecessary load on a failing service by temporarily blocking requests
+  # and allowing the service time to recover.
+  #
+  # States:
+  # - CLOSED: Normal operation, requests pass through
+  # - OPEN: Service is failing, all requests are blocked
+  # - HALF_OPEN: Testing if service has recovered, limited requests allowed
+  #
+  # The circuit breaker automatically transitions between states based on:
+  # - Failure threshold: Number of consecutive failures before opening
+  # - Recovery timeout: Time to wait before attempting to recover
+  # - Success criteria: Requirements to close the circuit after half-open
+  #
+  # Features:
+  # - Thread-safe operation using concurrent-ruby primitives
+  # - Configurable failure thresholds and recovery timeouts
+  # - Timeout protection for individual requests
+  # - Comprehensive metrics and logging
+  # - Security event logging for monitoring
+  #
+  # @example Basic usage with default settings
+  #   breaker = CircuitBreaker.new(service_name: "dilisense_api")
+  #   result = breaker.call do
+  #     # Make API request here
+  #     api_client.get("/endpoint")
+  #   end
+  #
+  # @example Custom configuration for high-availability requirements
+  #   breaker = CircuitBreaker.new(
+  #     service_name: "dilisense_api",
+  #     failure_threshold: 3,     # Open after 3 failures
+  #     recovery_timeout: 30,     # Try again after 30 seconds
+  #     timeout: 15,              # Individual request timeout
+  #     exceptions: [APIError, NetworkError]  # Only these errors count as failures
+  #   )
+  class CircuitBreaker
+    # Exception raised when the circuit breaker is in the OPEN state
+    # Indicates that requests are being blocked to protect the downstream service
+    class CircuitOpenError < StandardError
+      def initialize(service_name, next_attempt_time)
+        super("Circuit breaker is OPEN for #{service_name}. Next attempt allowed at #{next_attempt_time}")
+        @service_name = service_name
+        @next_attempt_time = next_attempt_time
+      end
+
+      attr_reader :service_name, :next_attempt_time
+    end
+
+    # Valid circuit breaker states following the standard pattern
+    STATES = %i[closed open half_open].freeze
+
+    # Initialize a new circuit breaker with specified configuration
+    #
+    # @param service_name [String] Name of the protected service (for logging and metrics)
+    # @param failure_threshold [Integer] Number of failures before opening the circuit (default: 5)
+    # @param recovery_timeout [Integer] Seconds to wait before attempting recovery (default: 60)
+    # @param timeout [Integer] Timeout for individual requests in seconds (default: 30)
+    # @param exceptions [Array<Class>] Exception types that count as failures (default: [StandardError])
+    def initialize(
+      service_name:,
+      failure_threshold: 5,
+      recovery_timeout: 60,
+      timeout: 30,
+      exceptions: [StandardError]
+    )
+      @service_name = service_name
+      @failure_threshold = failure_threshold
+      @recovery_timeout = recovery_timeout
+      @timeout = timeout
+      @exceptions = exceptions
+      
+      # Initialize state - circuit starts in CLOSED (normal) state
+      @state = :closed
+      @failure_count = Concurrent::AtomicFixnum.new(0)  # Thread-safe failure counter
+      @last_failure_time = Concurrent::AtomicReference.new  # Track when last failure occurred
+      @next_attempt_time = Concurrent::AtomicReference.new  # When to allow next attempt after opening
+      @success_count = Concurrent::AtomicFixnum.new(0)  # Track successful requests
+      @mutex = Mutex.new  # Synchronize state transitions
+    end
+
+    # Execute a block of code with circuit breaker protection
+    # This is the main method that wraps your API calls or other potentially failing operations
+    #
+    # @param block [Proc] The code to execute (typically an API call)
+    # @return [Object] Result of the executed block
+    # @raise [CircuitOpenError] When circuit is open and blocking requests
+    # @raise [Exception] Any exception raised by the protected code
+    #
+    # @example Protect an API call
+    #   result = circuit_breaker.call do
+    #     http_client.get("/api/endpoint")
+    #   end
+    def call(&block)
+      case state
+      when :open
+        # Circuit is open - check if enough time has passed to allow a test request
+        check_if_half_open_allowed
+        raise CircuitOpenError.new(@service_name, @next_attempt_time.value)
+      when :half_open
+        # Circuit is testing recovery - attempt the request and reset if successful
+        attempt_reset(&block)
+      when :closed
+        # Circuit is closed - normal operation, execute the request
+        execute(&block)
+      end
+    rescue *@exceptions => e
+      # Catch configured exception types and record as failures
+      record_failure(e)
+      raise
+    end
+
+    def state
+      @mutex.synchronize { @state }
+    end
+
+    def failure_count
+      @failure_count.value
+    end
+
+    def success_count
+      @success_count.value
+    end
+
+    def metrics
+      {
+        service_name: @service_name,
+        state: state,
+        failure_count: failure_count,
+        success_count: success_count,
+        failure_threshold: @failure_threshold,
+        recovery_timeout: @recovery_timeout,
+        last_failure_time: @last_failure_time.value,
+        next_attempt_time: @next_attempt_time.value
+      }
+    end
+
+    def reset!
+      @mutex.synchronize do
+        @state = :closed
+        @failure_count.value = 0
+        @success_count.value = 0
+        @last_failure_time.value = nil
+        @next_attempt_time.value = nil
+      end
+      
+      Logger.logger.info("Circuit breaker reset", service_name: @service_name)
+    end
+
+    def force_open!
+      @mutex.synchronize do
+        @state = :open
+        @next_attempt_time.value = Time.now + @recovery_timeout
+      end
+      
+      Logger.logger.warn("Circuit breaker forced open", service_name: @service_name)
+    end
+
+    private
+
+    def execute(&block)
+      result = Concurrent::Promises.future(executor: :io) do
+        block.call
+      end.value!(@timeout)
+
+      record_success
+      result
+    rescue Concurrent::TimeoutError
+      record_failure(StandardError.new("Request timeout after #{@timeout} seconds"))
+      raise NetworkError, "Request timeout after #{@timeout} seconds"
+    end
+
+    def attempt_reset(&block)
+      result = execute(&block)
+      reset_after_success
+      result
+    rescue *@exceptions => e
+      trip_breaker
+      raise e
+    end
+
+    def record_failure(error)
+      @failure_count.increment
+      @last_failure_time.value = Time.now
+      
+      Logger.log_security_event(
+        event_type: "circuit_breaker_failure",
+        details: {
+          service_name: @service_name,
+          error_class: error.class.name,
+          error_message: error.message,
+          failure_count: @failure_count.value
+        },
+        severity: @failure_count.value >= @failure_threshold ? :high : :medium
+      )
+
+      trip_breaker if @failure_count.value >= @failure_threshold
+    end
+
+    def record_success
+      @success_count.increment
+      
+      if state == :half_open
+        Logger.logger.info("Circuit breaker success in half-open state", 
+                          service_name: @service_name, 
+                          success_count: @success_count.value)
+      end
+    end
+
+    def trip_breaker
+      @mutex.synchronize do
+        @state = :open
+        @next_attempt_time.value = Time.now + @recovery_timeout
+      end
+      
+      Logger.log_security_event(
+        event_type: "circuit_breaker_opened",
+        details: {
+          service_name: @service_name,
+          failure_count: @failure_count.value,
+          next_attempt_time: @next_attempt_time.value
+        },
+        severity: :high
+      )
+    end
+
+    def check_if_half_open_allowed
+      return unless @next_attempt_time.value && Time.now >= @next_attempt_time.value
+      
+      @mutex.synchronize do
+        if Time.now >= @next_attempt_time.value
+          @state = :half_open
+          Logger.logger.info("Circuit breaker entering half-open state", service_name: @service_name)
+        end
+      end
+    end
+
+    def reset_after_success
+      @mutex.synchronize do
+        @state = :closed
+        @failure_count.value = 0
+        @last_failure_time.value = nil
+        @next_attempt_time.value = nil
+      end
+      
+      Logger.logger.info("Circuit breaker reset to closed after success", service_name: @service_name)
+    end
+  end
+end

data/lib/dilisense_pep_client/client.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module DilisensePepClient
+  # Main client class for interacting with the Dilisense PEP/Sanctions screening API
+  # This class handles all API communication and response processing
+  #
+  # @example Basic usage for individual screening
+  #   client = DilisensePepClient::Client.new
+  #   results = client.check_individual(names: "John Smith")
+  #
+  # @example Entity screening
+  #   results = client.check_entity(names: "Apple Inc")
+  class Client
+    # Initialize a new API client
+    # Validates configuration and establishes HTTP connection
+    # @raise [ConfigurationError] if API key is missing or invalid
+    def initialize
+      validate_configuration!
+      @connection = build_connection
+    end
+
+    # Screen an individual against PEP and sanctions lists
+    #
+    # @param names [String, nil] Full name to search for (e.g., "John Smith")
+    # @param search_all [String, nil] Alternative to names parameter for broader search
+    # @param dob [String, nil] Date of birth in DD/MM/YYYY format (e.g., "14/06/1982")
+    # @param gender [String, nil] Gender - either "male" or "female"
+    # @param fuzzy_search [Integer, nil] Enable fuzzy matching: 1 for fuzzy, 2 for very fuzzy
+    # @param includes [String, nil] Comma-separated source IDs to search within
+    #
+    # @return [Array<Hash>] Array of matched individuals, each hash contains:
+    #   - :name [String] Person's full name
+    #   - :source_type [String] Type of source (PEP, SANCTION, etc.)
+    #   - :pep_type [String, nil] Type of PEP if applicable
+    #   - :gender [String, nil] Person's gender if available
+    #   - :date_of_birth [Array<String>, nil] Dates of birth if available
+    #   - :citizenship [Array<String>, nil] Countries of citizenship
+    #   - :total_records [Integer] Number of matching records
+    #   - :sources [Array<String>] List of source databases
+    #
+    # @example Search with full parameters
+    #   results = client.check_individual(
+    #     names: "Vladimir Putin",
+    #     dob: "07/10/1952",
+    #     gender: "male",
+    #     fuzzy_search: 1
+    #   )
+    #
+    # @raise [ValidationError] if parameters are invalid or conflicting
+    # @raise [APIError] if the API returns an error
+    def check_individual(names: nil, search_all: nil, dob: nil, gender: nil, fuzzy_search: nil, includes: nil)
+      params = build_individual_params(names: names, search_all: search_all, dob: dob, gender: gender, fuzzy_search: fuzzy_search, includes: includes)
+      validate_individual_params(params)
+      get_request("/v1/checkIndividual", params)
+    end
+
+    # Screen an entity (company/organization) against sanctions and watchlists
+    #
+    # @param names [String, nil] Entity name to search for (e.g., "Apple Inc")
+    # @param search_all [String, nil] Alternative parameter for broader entity search
+    # @param fuzzy_search [Integer, nil] Enable fuzzy matching: 1 for fuzzy, 2 for very fuzzy
+    #
+    # @return [Array<Hash>] Array of matched entities with details
+    #
+    # @example Basic entity search
+    #   results = client.check_entity(names: "Bank Rossiya")
+    #
+    # @example Fuzzy search for entities
+    #   results = client.check_entity(names: "Gazprom", fuzzy_search: 1)
+    #
+    # @raise [ValidationError] if parameters are invalid
+    # @raise [APIError] if the API returns an error
+    def check_entity(names: nil, search_all: nil, fuzzy_search: nil)
+      params = {}
+      params[:names] = names if names
+      params[:search_all] = search_all if search_all
+      params[:fuzzy_search] = fuzzy_search if fuzzy_search
+      
+      validate_entity_params(params)
+      get_request("/v1/checkEntity", params)
+    end
+
+    private
+
+    # Validate that the API configuration is properly set
+    # Checks for presence and validity of API key
+    # @raise [ConfigurationError] if API key is missing or empty
+    def validate_configuration!
+      config = DilisensePepClient.configuration
+      raise ConfigurationError, "API key is required" if config.api_key.nil? || config.api_key.empty?
+    end
+
+    # Build parameters hash for individual screening API call
+    # Filters out nil values to keep request clean
+    #
+    # @param names [String, nil] Person's full name
+    # @param search_all [String, nil] Alternative search parameter
+    # @param dob [String, nil] Date of birth (DD/MM/YYYY)
+    # @param gender [String, nil] Gender (male/female)
+    # @param fuzzy_search [Integer, nil] Fuzzy search level (1 or 2)
+    # @param includes [String, nil] Source IDs to include
+    # @return [Hash] Parameters hash with non-nil values only
+    def build_individual_params(names:, search_all:, dob:, gender:, fuzzy_search:, includes:)
+      params = {}
+      params[:names] = names if names
+      params[:search_all] = search_all if search_all
+      params[:dob] = dob if dob
+      params[:gender] = gender if gender
+      params[:fuzzy_search] = fuzzy_search if fuzzy_search
+      params[:includes] = includes if includes
+      params
+    end
+
+    # Validate parameters for individual screening
+    # Ensures mutually exclusive parameters aren't used together
+    # and that at least one search parameter is provided
+    #
+    # @param params [Hash] Parameters to validate
+    # @raise [ValidationError] if parameters are invalid or missing
+    def validate_individual_params(params)
+      # Can't use both 'names' and 'search_all' - they're mutually exclusive
+      if params[:search_all] && params[:names]
+        raise ValidationError, "Cannot use both search_all and names parameters"
+      end
+      # Must have at least one search parameter
+      unless params[:search_all] || params[:names]
+        raise ValidationError, "Either search_all or names parameter is required"
+      end
+    end
+
+    # Validate parameters for entity screening
+    # Similar to individual validation but for entities
+    #
+    # @param params [Hash] Parameters to validate
+    # @raise [ValidationError] if parameters are invalid
+    def validate_entity_params(params)
+      # Can't use both search methods simultaneously
+      if params[:search_all] && params[:names]
+        raise ValidationError, "Cannot use both search_all and names parameters"
+      end
+      # Need at least one search parameter
+      unless params[:search_all] || params[:names]
+        raise ValidationError, "Either search_all or names parameter is required"
+      end
+    end
+
+    # Build the HTTP connection using Faraday
+    # Sets up headers, timeout, and authentication
+    #
+    # @return [Faraday::Connection] Configured HTTP client
+    def build_connection
+      config = DilisensePepClient.configuration
+      Faraday.new(url: config.base_url) do |f|
+        f.options.timeout = config.timeout
+        f.headers["x-api-key"] = config.api_key  # API authentication
+        f.headers["User-Agent"] = "DilisensePepClient/#{VERSION}"  # Identify our client
+      end
+    end
+
+    # Execute GET request to the API and process response
+    # Handles network errors and converts response to array format
+    #
+    # @param endpoint [String] API endpoint path (e.g., "/v1/checkIndividual")
+    # @param params [Hash] Query parameters for the request
+    # @return [Array<Hash>] Processed response as array of matches
+    # @raise [NetworkError] if connection fails or times out
+    # @raise [APIError] if API returns an error status
+    def get_request(endpoint, params)
+      response = @connection.get(endpoint, params)
+      raw_response = handle_response(response)
+      process_response_to_array(raw_response)
+    rescue Faraday::TimeoutError
+      raise NetworkError, "Request timeout"
+    rescue Faraday::ConnectionFailed
+      raise NetworkError, "Connection failed"
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200
+        JSON.parse(response.body)
+      when 401
+        raise AuthenticationError.new("API key not valid", status: response.status, body: response.body)
+      when 400
+        raise ValidationError.new("Bad request: #{response.body}", status: response.status, body: response.body)
+      when 403
+        raise APIError.new("Forbidden", status: response.status, body: response.body)
+      when 429
+        raise APIError.new("Rate limit exceeded", status: response.status, body: response.body)
+      when 500
+        raise APIError.new("Internal server error", status: response.status, body: response.body)
+      else
+        raise APIError.new("Unexpected response: #{response.status}", status: response.status, body: response.body)
+      end
+    rescue JSON::ParserError
+      raise APIError.new("Invalid JSON response", status: response.status, body: response.body)
+    end
+
+    def process_response_to_array(raw_response)
+      return [] if raw_response["total_hits"] == 0
+
+      # Group records by person (using name as the key)
+      person_groups = raw_response["found_records"].group_by do |record|
+        normalize_name(record["name"])
+      end
+
+      # Convert each group to a person/entity object
+      person_groups.map do |normalized_name, records|
+        primary_record = records.first
+        all_sources = records.map { |r| r["source_id"] }.uniq
+
+        {
+          name: primary_record["name"],
+          source_type: primary_record["source_type"],
+          pep_type: primary_record["pep_type"],
+          gender: primary_record["gender"],
+          date_of_birth: primary_record["date_of_birth"],
+          citizenship: primary_record["citizenship"],
+          jurisdiction: primary_record["jurisdiction"],
+          address: primary_record["address"],
+          sanction_details: primary_record["sanction_details"],
+          sources: all_sources,
+          total_records: records.length,
+          raw_records: records
+        }
+      end
+    end
+
+    # Normalize a name for comparison/grouping purposes
+    # Handles various name formats and removes titles/suffixes
+    # This ensures "Mr. John Smith Jr." and "JOHN SMITH" are treated as the same person
+    #
+    # @param name [String] Name to normalize
+    # @return [String] Normalized name for comparison
+    def normalize_name(name)
+      return "" unless name
+      
+      # Remove common variations and normalize for grouping
+      normalized = name.downcase
+        .gsub(/\s+/, " ")           # Normalize whitespace (multiple spaces -> single space)
+        .gsub(/[^\w\s]/, "")        # Remove punctuation (periods, commas, etc.)
+        .strip                       # Remove leading/trailing whitespace
+      
+      # Handle common name variations - remove suffixes that don't affect identity
+      # This helps match "John Smith Jr." with "John Smith"
+      normalized.gsub(/\b(jr|sr|iii?|iv)\b/, "")  # Remove suffixes (Jr, Sr, III, IV, etc.)
+        .gsub(/\s+/, " ")           # Clean up any double spaces from removal
+        .strip
+    end
+  end
+end

data/lib/dilisense_pep_client/configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module DilisensePepClient
+  # Simple configuration management
+  # Stores basic settings needed for API communication
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout
+
+    def initialize
+      @base_url = "https://api.dilisense.com"
+      @timeout = 30
+      @api_key = ENV["DILISENSE_API_KEY"]
+    end
+  end
+end