decision_agent 0.2.0 → 1.0.1

data/lib/decision_agent/data_enrichment/cache/memory_adapter.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../cache_adapter"
+require "monitor"
+
+module DecisionAgent
+  module DataEnrichment
+    module Cache
+      # In-memory cache adapter (default, no dependencies)
+      class MemoryAdapter < CacheAdapter
+        include MonitorMixin
+
+        def initialize
+          super
+          @cache = {}
+        end
+
+        # Get cached value
+        #
+        # @param key [String] Cache key
+        # @return [Hash, nil] Cached data or nil if not found/expired
+        def get(key)
+          synchronize do
+            entry = @cache[key]
+            return nil unless entry
+
+            # Check if expired
+            if entry[:expires_at] < Time.now
+              @cache.delete(key)
+              return nil
+            end
+
+            entry[:value]
+          end
+        end
+
+        # Set cached value
+        #
+        # @param key [String] Cache key
+        # @param value [Hash] Data to cache
+        # @param ttl [Integer] Time to live in seconds
+        def set(key, value, ttl)
+          synchronize do
+            @cache[key] = {
+              value: value,
+              expires_at: Time.now + ttl
+            }
+          end
+        end
+
+        # Delete cached value
+        #
+        # @param key [String] Cache key
+        def delete(key)
+          synchronize do
+            @cache.delete(key)
+          end
+        end
+
+        # Clear all cached values
+        def clear
+          synchronize do
+            @cache.clear
+          end
+        end
+
+        # Get cache statistics
+        #
+        # @return [Hash] Cache statistics
+        def stats
+          synchronize do
+            now = Time.now
+            valid_entries = @cache.count { |_k, v| v[:expires_at] >= now }
+            expired_entries = @cache.size - valid_entries
+
+            {
+              size: @cache.size,
+              valid: valid_entries,
+              expired: expired_entries
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/decision_agent/data_enrichment/cache_adapter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module DataEnrichment
+    # Base class for cache adapters
+    class CacheAdapter
+      # Get cached value
+      #
+      # @param key [String] Cache key
+      # @return [Hash, nil] Cached data or nil if not found/expired
+      def get(key)
+        raise NotImplementedError, "#{self.class} must implement #get"
+      end
+
+      # Set cached value
+      #
+      # @param key [String] Cache key
+      # @param value [Hash] Data to cache
+      # @param ttl [Integer] Time to live in seconds
+      def set(key, value, ttl)
+        raise NotImplementedError, "#{self.class} must implement #set"
+      end
+
+      # Delete cached value
+      #
+      # @param key [String] Cache key
+      def delete(key)
+        raise NotImplementedError, "#{self.class} must implement #delete"
+      end
+
+      # Clear all cached values
+      def clear
+        raise NotImplementedError, "#{self.class} must implement #clear"
+      end
+
+      # Generate cache key from request parameters
+      #
+      # @param endpoint_name [Symbol] Endpoint identifier
+      # @param params [Hash] Request parameters
+      # @return [String] Cache key
+      def cache_key(endpoint_name, params)
+        # Sort params for consistent key generation
+        sorted_params = params.sort.to_h
+        param_string = sorted_params.map { |k, v| "#{k}=#{v}" }.join("&")
+        "#{endpoint_name}:#{Digest::SHA256.hexdigest(param_string)}"
+      end
+    end
+  end
+end

data/lib/decision_agent/data_enrichment/circuit_breaker.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module DecisionAgent
+  module DataEnrichment
+    # Circuit breaker pattern for resilience
+    #
+    # Prevents cascading failures by opening the circuit after N failures
+    class CircuitBreaker
+      include MonitorMixin
+
+      # Circuit states
+      CLOSED = :closed    # Normal operation
+      OPEN = :open        # Circuit is open, failing fast
+      HALF_OPEN = :half_open # Testing if service recovered
+
+      def initialize(failure_threshold: 5, timeout: 60, success_threshold: 2)
+        super()
+        @failure_threshold = failure_threshold
+        @timeout = timeout
+        @success_threshold = success_threshold
+        @state = CLOSED
+        @failure_count = 0
+        @success_count = 0
+        @last_failure_time = nil
+      end
+
+      # Execute block with circuit breaker protection
+      #
+      # @yield Block to execute
+      # @return [Object] Result of block execution
+      # @raise [CircuitOpenError] If circuit is open
+      def call
+        synchronize do
+          check_state
+          raise CircuitOpenError, "Circuit is open" if @state == OPEN
+        end
+
+        begin
+          result = yield
+          record_success
+          result
+        rescue StandardError => e
+          record_failure
+          raise e
+        end
+      end
+
+      # Check if circuit is open
+      #
+      # @return [Boolean]
+      def open?
+        synchronize do
+          check_state
+          @state == OPEN
+        end
+      end
+
+      # Reset circuit breaker to closed state
+      def reset
+        synchronize do
+          @state = CLOSED
+          @failure_count = 0
+          @success_count = 0
+          @last_failure_time = nil
+        end
+      end
+
+      # Get current state
+      #
+      # @return [Symbol] Current state
+      def state
+        synchronize do
+          check_state
+          @state
+        end
+      end
+
+      private
+
+      def check_state
+        case @state
+        when OPEN
+          # Check if timeout has elapsed, move to half-open
+          if @last_failure_time && (Time.now - @last_failure_time) >= @timeout
+            @state = HALF_OPEN
+            @success_count = 0
+          end
+        when HALF_OPEN
+          # State remains half-open until success threshold is met
+        when CLOSED
+          # State remains closed until failure threshold is met
+        end
+      end
+
+      def record_success
+        synchronize do
+          case @state
+          when HALF_OPEN
+            @success_count += 1
+            if @success_count >= @success_threshold
+              @state = CLOSED
+              @failure_count = 0
+              @success_count = 0
+            end
+          when CLOSED
+            @failure_count = 0 # Reset failure count on success
+          end
+        end
+      end
+
+      def record_failure
+        synchronize do
+          @failure_count += 1
+          @last_failure_time = Time.now
+
+          case @state
+          when HALF_OPEN
+            # Failures in half-open state immediately open the circuit
+            @state = OPEN
+            @success_count = 0
+          when CLOSED
+            # Open circuit if failure threshold is met
+            @state = OPEN if @failure_count >= @failure_threshold
+          end
+        end
+      end
+
+      # Error raised when circuit is open
+      class CircuitOpenError < StandardError
+      end
+    end
+  end
+end

data/lib/decision_agent/data_enrichment/client.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "base64"
+require_relative "cache_adapter"
+require_relative "cache/memory_adapter"
+require_relative "circuit_breaker"
+require_relative "errors"
+
+module DecisionAgent
+  module DataEnrichment
+    # HTTP client for data enrichment requests
+    class Client
+      # Error classes
+      class RequestError < StandardError
+        attr_reader :status_code, :response_body
+
+        def initialize(message, status_code: nil, response_body: nil)
+          super(message)
+          @status_code = status_code
+          @response_body = response_body
+        end
+      end
+
+      class TimeoutError < RequestError
+      end
+
+      class NetworkError < RequestError
+      end
+
+      attr_reader :config, :cache_adapter, :circuit_breaker
+
+      def initialize(config:, cache_adapter: nil, circuit_breaker: nil)
+        @config = config
+        @cache_adapter = cache_adapter || Cache::MemoryAdapter.new
+        @circuit_breakers = {}
+        @circuit_breaker_default = circuit_breaker || CircuitBreaker.new
+        @circuit_breaker = @circuit_breaker_default
+      end
+
+      # Fetch data from configured endpoint
+      #
+      # @param endpoint_name [Symbol] Endpoint identifier
+      # @param params [Hash] Request parameters
+      # @param use_cache [Boolean] Whether to use cache (default: true)
+      # @return [Hash] Response data
+      # @raise [RequestError] If request fails
+      def fetch(endpoint_name, params: {}, use_cache: true)
+        endpoint_config = @config.endpoint(endpoint_name)
+        raise ArgumentError, "Unknown endpoint: #{endpoint_name}" unless endpoint_config
+
+        # Generate cache key
+        cache_key = @cache_adapter.cache_key(endpoint_name, params)
+
+        # Check cache first
+        if use_cache
+          cached = @cache_adapter.get(cache_key)
+          return cached if cached
+        end
+
+        # Execute request with circuit breaker
+        circuit_breaker = get_circuit_breaker(endpoint_name)
+        begin
+          response_data = circuit_breaker.call do
+            execute_request(endpoint_name, endpoint_config, params)
+          end
+        rescue CircuitBreaker::CircuitOpenError => e
+          # Try to return cached data on circuit open
+          cached = @cache_adapter.get(cache_key) if use_cache
+          return cached if cached
+
+          raise RequestError, "Circuit breaker is open for #{endpoint_name}: #{e.message}"
+        end
+
+        # Cache response
+        @cache_adapter.set(cache_key, response_data, endpoint_config[:cache][:ttl]) if use_cache && endpoint_config[:cache][:ttl].positive?
+
+        response_data
+      end
+
+      # Clear cache for endpoint
+      #
+      # @param endpoint_name [Symbol, nil] Endpoint identifier, or nil to clear all
+      def clear_cache(endpoint_name = nil)
+        if endpoint_name
+          # Clear cache entries for this endpoint (requires cache adapter support)
+          # For now, just clear all if endpoint-specific clearing isn't supported
+        end
+        @cache_adapter.clear
+      end
+
+      private
+
+      def execute_request(endpoint_name, endpoint_config, params)
+        uri = URI(endpoint_config[:url])
+        method = endpoint_config[:method]
+        timeout = endpoint_config[:timeout]
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.read_timeout = timeout
+        http.open_timeout = timeout
+
+        request = build_request(uri, method, endpoint_config, params)
+
+        response = http.request(request)
+
+        handle_response(response, endpoint_name)
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise TimeoutError, "Request timeout for #{endpoint_name}: #{e.message}"
+      rescue StandardError => e
+        raise NetworkError, "Network error for #{endpoint_name}: #{e.message}"
+      end
+
+      def build_request(uri, method, endpoint_config, params)
+        headers = endpoint_config[:headers].dup || {}
+        apply_auth(headers, endpoint_config[:auth])
+
+        case method
+        when :get
+          # Add params to query string for GET requests
+          if params.any?
+            query_string = URI.encode_www_form(params)
+            uri_with_query = URI("#{uri}?#{query_string}")
+            request = Net::HTTP::Get.new(uri_with_query)
+          else
+            request = Net::HTTP::Get.new(uri)
+          end
+        when :post
+          request = Net::HTTP::Post.new(uri)
+          request.body = params.to_json
+          headers["Content-Type"] ||= "application/json"
+        when :put
+          request = Net::HTTP::Put.new(uri)
+          request.body = params.to_json
+          headers["Content-Type"] ||= "application/json"
+        when :delete
+          request = Net::HTTP::Delete.new(uri)
+        else
+          raise ArgumentError, "Unsupported HTTP method: #{method}"
+        end
+
+        headers.each { |k, v| request[k] = v }
+        request
+      end
+
+      def apply_auth(headers, auth_config)
+        return unless auth_config
+
+        case auth_config[:type]
+        when :api_key
+          header_name = auth_config[:header] || "X-API-Key"
+          api_key = get_secret(auth_config[:secret_key] || "API_KEY")
+          headers[header_name] = api_key
+        when :basic
+          username = get_secret(auth_config[:username_key] || "USERNAME")
+          password = get_secret(auth_config[:password_key] || "PASSWORD")
+          credentials = Base64.strict_encode64("#{username}:#{password}")
+          headers["Authorization"] = "Basic #{credentials}"
+        when :bearer
+          token = get_secret(auth_config[:token_key] || "TOKEN")
+          headers["Authorization"] = "Bearer #{token}"
+        end
+      end
+
+      def get_secret(key)
+        # Try environment variable first
+        return ENV[key] if ENV.key?(key)
+        return ENV[key.upcase] if ENV.key?(key.upcase)
+
+        # Could extend to support vault integration here
+        raise ArgumentError, "Secret not found: #{key}. Set environment variable #{key.upcase}"
+      end
+
+      def handle_response(response, endpoint_name)
+        case response.code.to_i
+        when 200..299
+          parse_response(response)
+        when 400..499
+          raise RequestError.new(
+            "Client error for #{endpoint_name}: HTTP #{response.code}",
+            status_code: response.code.to_i,
+            response_body: response.body
+          )
+        when 500..599
+          raise RequestError.new(
+            "Server error for #{endpoint_name}: HTTP #{response.code}",
+            status_code: response.code.to_i,
+            response_body: response.body
+          )
+        else
+          raise RequestError.new(
+            "Unexpected response for #{endpoint_name}: HTTP #{response.code}",
+            status_code: response.code.to_i,
+            response_body: response.body
+          )
+        end
+      end
+
+      def parse_response(response)
+        content_type = response["Content-Type"] || ""
+        body = response.body
+
+        return {} if body.nil? || body.empty?
+
+        if content_type.include?("application/json")
+          JSON.parse(body, symbolize_names: true)
+        else
+          { body: body, content_type: content_type }
+        end
+      end
+
+      def get_circuit_breaker(endpoint_name)
+        @circuit_breakers[endpoint_name] ||= @circuit_breaker_default.dup
+      end
+    end
+  end
+end

data/lib/decision_agent/data_enrichment/config.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module DataEnrichment
+    # Configuration for data enrichment endpoints
+    class Config
+      attr_accessor :endpoints, :default_timeout, :default_retry, :default_cache
+
+      def initialize
+        @endpoints = {}
+        @default_timeout = 5 # seconds
+        @default_retry = { max_attempts: 3, backoff: :exponential }
+        @default_cache = { ttl: 3600, adapter: :memory }
+      end
+
+      # Add or update an endpoint configuration
+      #
+      # @param name [Symbol] Endpoint identifier
+      # @param url [String] Base URL for the endpoint
+      # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+      # @param auth [Hash] Authentication configuration
+      # @param cache [Hash] Cache configuration
+      # @param retry_config [Hash] Retry configuration
+      # @param timeout [Integer] Request timeout in seconds
+      # @param headers [Hash] Default headers
+      # @param rate_limit [Hash] Rate limiting configuration
+      #
+      # @example
+      #   config.add_endpoint(:credit_bureau,
+      #     url: "https://api.creditbureau.com/v1/score",
+      #     method: :post,
+      #     auth: { type: :api_key, header: "X-API-Key" },
+      #     cache: { ttl: 3600, adapter: :redis },
+      #     retry_config: { max_attempts: 3, backoff: :exponential }
+      #   )
+      def add_endpoint(name, url:, method: :get, auth: nil, cache: nil, retry_config: nil, timeout: nil, headers: {}, rate_limit: nil) # rubocop:disable Metrics/ParameterLists
+        @endpoints[name.to_sym] = {
+          url: url,
+          method: method.to_sym,
+          auth: auth,
+          cache: cache || @default_cache.dup,
+          retry: retry_config || @default_retry.dup,
+          timeout: timeout || @default_timeout,
+          headers: headers,
+          rate_limit: rate_limit
+        }
+      end
+
+      # Get endpoint configuration
+      #
+      # @param name [Symbol] Endpoint identifier
+      # @return [Hash, nil] Endpoint configuration or nil if not found
+      def endpoint(name)
+        @endpoints[name.to_sym]
+      end
+
+      # Check if endpoint exists
+      #
+      # @param name [Symbol] Endpoint identifier
+      # @return [Boolean]
+      def endpoint?(name)
+        @endpoints.key?(name.to_sym)
+      end
+
+      # Remove endpoint configuration
+      #
+      # @param name [Symbol] Endpoint identifier
+      def remove_endpoint(name)
+        @endpoints.delete(name.to_sym)
+      end
+
+      # Clear all endpoint configurations
+      def clear
+        @endpoints.clear
+      end
+    end
+  end
+end

data/lib/decision_agent/data_enrichment/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module DataEnrichment
+    # Base error class for data enrichment
+    class Error < StandardError
+    end
+
+    # Error raised when endpoint is not configured
+    class EndpointNotFoundError < Error
+    end
+
+    # Error raised when request fails
+    class RequestError < Error
+      attr_reader :status_code, :response_body
+
+      def initialize(message, status_code: nil, response_body: nil)
+        super(message)
+        @status_code = status_code
+        @response_body = response_body
+      end
+    end
+
+    # Error raised when request times out
+    class TimeoutError < RequestError
+    end
+
+    # Error raised when network error occurs
+    class NetworkError < RequestError
+    end
+
+    # Error raised when circuit breaker is open
+    class CircuitOpenError < Error
+    end
+  end
+end