vectra-client 0.2.2 → 0.3.1

data/lib/vectra/circuit_breaker.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+module Vectra
+  # Circuit Breaker pattern for handling provider failures
+  #
+  # Prevents cascading failures by temporarily stopping requests to a failing provider.
+  # The circuit has three states:
+  # - :closed - Normal operation, requests pass through
+  # - :open - Requests fail immediately without calling provider
+  # - :half_open - Limited requests allowed to test if provider recovered
+  #
+  # @example Basic usage
+  #   breaker = Vectra::CircuitBreaker.new(
+  #     failure_threshold: 5,
+  #     recovery_timeout: 30
+  #   )
+  #
+  #   breaker.call do
+  #     client.query(index: "my-index", vector: vec, top_k: 10)
+  #   end
+  #
+  # @example With fallback
+  #   breaker.call(fallback: -> { cached_results }) do
+  #     client.query(...)
+  #   end
+  #
+  # @example Per-provider circuit breakers
+  #   breakers = {
+  #     pinecone: Vectra::CircuitBreaker.new(name: "pinecone"),
+  #     qdrant: Vectra::CircuitBreaker.new(name: "qdrant")
+  #   }
+  #
+  class CircuitBreaker
+    STATES = [:closed, :open, :half_open].freeze
+
+    # Error raised when circuit is open
+    class OpenCircuitError < Vectra::Error
+      attr_reader :circuit_name, :failures, :opened_at
+
+      def initialize(circuit_name:, failures:, opened_at:)
+        @circuit_name = circuit_name
+        @failures = failures
+        @opened_at = opened_at
+        super("Circuit '#{circuit_name}' is open after #{failures} failures")
+      end
+    end
+
+    attr_reader :name, :state, :failure_count, :success_count,
+                :last_failure_at, :opened_at
+
+    # Initialize a new circuit breaker
+    #
+    # @param name [String] Circuit name for logging/metrics
+    # @param failure_threshold [Integer] Failures before opening circuit (default: 5)
+    # @param success_threshold [Integer] Successes in half-open to close (default: 3)
+    # @param recovery_timeout [Integer] Seconds before trying half-open (default: 30)
+    # @param monitored_errors [Array<Class>] Errors that count as failures
+    def initialize(
+      name: "default",
+      failure_threshold: 5,
+      success_threshold: 3,
+      recovery_timeout: 30,
+      monitored_errors: nil
+    )
+      @name = name
+      @failure_threshold = failure_threshold
+      @success_threshold = success_threshold
+      @recovery_timeout = recovery_timeout
+      @monitored_errors = monitored_errors || default_monitored_errors
+
+      @state = :closed
+      @failure_count = 0
+      @success_count = 0
+      @last_failure_at = nil
+      @opened_at = nil
+      @mutex = Mutex.new
+    end
+
+    # Execute block through circuit breaker
+    #
+    # @param fallback [Proc, nil] Fallback to call when circuit is open
+    # @yield The operation to execute
+    # @return [Object] Result of block or fallback
+    # @raise [OpenCircuitError] If circuit is open and no fallback provided
+    def call(fallback: nil, &)
+      check_state!
+
+      if open?
+        return handle_open_circuit(fallback)
+      end
+
+      execute_with_monitoring(&)
+    rescue *@monitored_errors => e
+      record_failure(e)
+      raise
+    end
+
+    # Force circuit to closed state (manual reset)
+    #
+    # @return [void]
+    def reset!
+      @mutex.synchronize do
+        transition_to(:closed)
+        @failure_count = 0
+        @success_count = 0
+        @last_failure_at = nil
+        @opened_at = nil
+      end
+    end
+
+    # Force circuit to open state (manual trip)
+    #
+    # @return [void]
+    def trip!
+      @mutex.synchronize do
+        transition_to(:open)
+        @opened_at = Time.now
+      end
+    end
+
+    # Check if circuit is closed (normal operation)
+    #
+    # @return [Boolean]
+    def closed?
+      state == :closed
+    end
+
+    # Check if circuit is open (blocking requests)
+    #
+    # @return [Boolean]
+    def open?
+      state == :open
+    end
+
+    # Check if circuit is half-open (testing recovery)
+    #
+    # @return [Boolean]
+    def half_open?
+      state == :half_open
+    end
+
+    # Get circuit statistics
+    #
+    # @return [Hash]
+    def stats
+      {
+        name: name,
+        state: state,
+        failure_count: failure_count,
+        success_count: success_count,
+        failure_threshold: @failure_threshold,
+        success_threshold: @success_threshold,
+        recovery_timeout: @recovery_timeout,
+        last_failure_at: last_failure_at,
+        opened_at: opened_at
+      }
+    end
+
+    private
+
+    def default_monitored_errors
+      [
+        Vectra::ServerError,
+        Vectra::ConnectionError,
+        Vectra::TimeoutError
+      ]
+    end
+
+    def check_state!
+      @mutex.synchronize do
+        # Check if we should transition from open to half-open
+        if open? && recovery_timeout_elapsed?
+          transition_to(:half_open)
+          @success_count = 0
+        end
+      end
+    end
+
+    def recovery_timeout_elapsed?
+      return false unless opened_at
+
+      Time.now - opened_at >= @recovery_timeout
+    end
+
+    def handle_open_circuit(fallback)
+      if fallback
+        log_fallback
+        fallback.call
+      else
+        raise OpenCircuitError.new(
+          circuit_name: name,
+          failures: failure_count,
+          opened_at: opened_at
+        )
+      end
+    end
+
+    def execute_with_monitoring
+      result = yield
+      record_success
+      result
+    end
+
+    def record_success
+      @mutex.synchronize do
+        @success_count += 1
+
+        # In half-open, check if we should close
+        if half_open? && @success_count >= @success_threshold
+          transition_to(:closed)
+          @failure_count = 0
+          log_circuit_closed
+        end
+      end
+    end
+
+    def record_failure(error)
+      @mutex.synchronize do
+        @failure_count += 1
+        @last_failure_at = Time.now
+
+        # In half-open, immediately open again
+        if half_open?
+          transition_to(:open)
+          @opened_at = Time.now
+          log_circuit_reopened(error)
+          return
+        end
+
+        # In closed, check threshold
+        if closed? && @failure_count >= @failure_threshold
+          transition_to(:open)
+          @opened_at = Time.now
+          log_circuit_opened(error)
+        end
+      end
+    end
+
+    def transition_to(new_state)
+      @state = new_state
+    end
+
+    def log_circuit_opened(error)
+      logger&.error(
+        "[Vectra::CircuitBreaker] Circuit '#{name}' opened after #{failure_count} failures. " \
+        "Last error: #{error.class} - #{error.message}"
+      )
+    end
+
+    def log_circuit_closed
+      logger&.info(
+        "[Vectra::CircuitBreaker] Circuit '#{name}' closed after #{success_count} successes"
+      )
+    end
+
+    def log_circuit_reopened(error)
+      logger&.warn(
+        "[Vectra::CircuitBreaker] Circuit '#{name}' reopened. " \
+        "Recovery failed: #{error.class} - #{error.message}"
+      )
+    end
+
+    def log_fallback
+      logger&.info(
+        "[Vectra::CircuitBreaker] Circuit '#{name}' open, using fallback"
+      )
+    end
+
+    def logger
+      Vectra.configuration.logger
+    end
+  end
+
+  # Circuit breaker registry for managing multiple circuits
+  #
+  # @example
+  #   Vectra::CircuitBreakerRegistry.register(:pinecone, failure_threshold: 3)
+  #   Vectra::CircuitBreakerRegistry.register(:qdrant, failure_threshold: 5)
+  #
+  #   Vectra::CircuitBreakerRegistry[:pinecone].call { ... }
+  #
+  module CircuitBreakerRegistry
+    class << self
+      # Get or create a circuit breaker
+      #
+      # @param name [Symbol, String] Circuit name
+      # @return [CircuitBreaker]
+      def [](name)
+        circuits[name.to_sym]
+      end
+
+      # Register a new circuit breaker
+      #
+      # @param name [Symbol, String] Circuit name
+      # @param options [Hash] CircuitBreaker options
+      # @return [CircuitBreaker]
+      def register(name, **options)
+        circuits[name.to_sym] = CircuitBreaker.new(name: name.to_s, **options)
+      end
+
+      # Get all registered circuits
+      #
+      # @return [Hash<Symbol, CircuitBreaker>]
+      def all
+        circuits.dup
+      end
+
+      # Reset all circuits
+      #
+      # @return [void]
+      def reset_all!
+        circuits.each_value(&:reset!)
+      end
+
+      # Get stats for all circuits
+      #
+      # @return [Hash<Symbol, Hash>]
+      def stats
+        circuits.transform_values(&:stats)
+      end
+
+      # Clear all registered circuits
+      #
+      # @return [void]
+      def clear!
+        @circuits = {}
+      end
+
+      private
+
+      def circuits
+        @circuits ||= {}
+      end
+    end
+  end
+end

data/lib/vectra/client.rb

@@ -25,6 +25,8 @@ module Vectra
   #   )
   #
   class Client
+    include HealthCheck
+
     attr_reader :config, :provider
 
     # Initialize a new Client

data/lib/vectra/configuration.rb

@@ -15,7 +15,8 @@ module Vectra
 
     attr_accessor :api_key, :environment, :host, :timeout, :open_timeout,
                   :max_retries, :retry_delay, :logger, :pool_size, :pool_timeout,
-                  :batch_size, :instrumentation
+                  :batch_size, :instrumentation, :cache_enabled, :cache_ttl,
+                  :cache_max_size, :async_concurrency
 
     attr_reader :provider
 
@@ -33,6 +34,10 @@ module Vectra
       @pool_timeout = 5
       @batch_size = 100
       @instrumentation = false
+      @cache_enabled = false
+      @cache_ttl = 300
+      @cache_max_size = 1000
+      @async_concurrency = 4
     end
 
     # Set the provider

data/lib/vectra/health_check.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Vectra
+  # Health check functionality for Vectra clients
+  #
+  # Provides health check methods to verify connectivity and status
+  # of vector database providers.
+  #
+  # @example Basic health check
+  #   client = Vectra::Client.new(provider: :pinecone, ...)
+  #   result = client.health_check
+  #   puts result[:healthy]  # => true/false
+  #
+  # @example Detailed health check
+  #   result = client.health_check(
+  #     index: "my-index",
+  #     include_stats: true
+  #   )
+  #
+  module HealthCheck
+    # Perform health check on the provider
+    #
+    # @param index [String, nil] Index to check (uses first available if nil)
+    # @param include_stats [Boolean] Include index statistics
+    # @param timeout [Float] Health check timeout in seconds
+    # @return [HealthCheckResult]
+    def health_check(index: nil, include_stats: false, timeout: 5)
+      start_time = Time.now
+
+      indexes = with_timeout(timeout) { list_indexes }
+      index_name = index || indexes.first&.dig(:name)
+
+      result = base_result(start_time, indexes)
+      add_index_stats(result, index_name, include_stats, timeout)
+      add_pool_stats(result)
+
+      HealthCheckResult.new(**result)
+    rescue StandardError => e
+      failure_result(start_time, e)
+    end
+
+    # Quick health check - just tests connectivity
+    #
+    # @param timeout [Float] Timeout in seconds
+    # @return [Boolean] true if healthy
+    def healthy?(timeout: 5)
+      health_check(timeout: timeout).healthy?
+    end
+
+    private
+
+    def with_timeout(seconds, &)
+      Timeout.timeout(seconds, &)
+    rescue Timeout::Error
+      raise Vectra::TimeoutError, "Health check timed out after #{seconds}s"
+    end
+
+    def base_result(start_time, indexes)
+      {
+        healthy: true,
+        provider: provider_name,
+        latency_ms: latency_since(start_time),
+        indexes_available: indexes.size,
+        checked_at: current_time_iso
+      }
+    end
+
+    def add_index_stats(result, index_name, include_stats, timeout)
+      return unless include_stats && index_name
+
+      stats = with_timeout(timeout) { stats(index: index_name) }
+      result[:index] = index_name
+      result[:stats] = {
+        vector_count: stats[:total_vector_count],
+        dimension: stats[:dimension]
+      }.compact
+    end
+
+    def add_pool_stats(result)
+      return unless provider.respond_to?(:pool_stats)
+
+      pool = provider.pool_stats
+      result[:pool] = pool unless pool[:status] == "not_initialized"
+    end
+
+    def failure_result(start_time, error)
+      HealthCheckResult.new(
+        healthy: false,
+        provider: provider_name,
+        latency_ms: latency_since(start_time),
+        error: error.class.name,
+        error_message: error.message,
+        checked_at: current_time_iso
+      )
+    end
+
+    def latency_since(start_time)
+      ((Time.now - start_time) * 1000).round(2)
+    end
+
+    def current_time_iso
+      Time.now.utc.iso8601
+    end
+  end
+
+  # Health check result object
+  #
+  # @example
+  #   result = client.health_check
+  #   if result.healthy?
+  #     puts "All good! Latency: #{result.latency_ms}ms"
+  #   else
+  #     puts "Error: #{result.error_message}"
+  #   end
+  #
+  class HealthCheckResult
+    attr_reader :provider, :latency_ms, :indexes_available, :checked_at,
+                :index, :stats, :pool, :error, :error_message
+
+    def initialize(healthy:, provider:, latency_ms:, checked_at:,
+                   indexes_available: nil, index: nil, stats: nil,
+                   pool: nil, error: nil, error_message: nil)
+      @healthy = healthy
+      @provider = provider
+      @latency_ms = latency_ms
+      @checked_at = checked_at
+      @indexes_available = indexes_available
+      @index = index
+      @stats = stats
+      @pool = pool
+      @error = error
+      @error_message = error_message
+    end
+
+    # Check if the health check passed
+    #
+    # @return [Boolean]
+    def healthy?
+      @healthy
+    end
+
+    # Check if the health check failed
+    #
+    # @return [Boolean]
+    def unhealthy?
+      !@healthy
+    end
+
+    # Convert to hash
+    #
+    # @return [Hash]
+    def to_h
+      {
+        healthy: @healthy,
+        provider: provider,
+        latency_ms: latency_ms,
+        checked_at: checked_at,
+        indexes_available: indexes_available,
+        index: index,
+        stats: stats,
+        pool: pool,
+        error: error,
+        error_message: error_message
+      }.compact
+    end
+
+    # Convert to JSON
+    #
+    # @return [String]
+    def to_json(*)
+      JSON.generate(to_h)
+    end
+  end
+
+  # Aggregate health checker for multiple providers
+  #
+  # @example
+  #   checker = Vectra::AggregateHealthCheck.new(
+  #     pinecone: pinecone_client,
+  #     qdrant: qdrant_client,
+  #     pgvector: pgvector_client
+  #   )
+  #
+  #   result = checker.check_all
+  #   puts result[:overall_healthy]
+  #
+  class AggregateHealthCheck
+    attr_reader :clients
+
+    # Initialize aggregate health checker
+    #
+    # @param clients [Hash<Symbol, Client>] Named clients to check
+    def initialize(**clients)
+      @clients = clients
+    end
+
+    # Check health of all clients
+    #
+    # @param parallel [Boolean] Run checks in parallel
+    # @param timeout [Float] Timeout per check
+    # @return [Hash] Aggregate results
+    def check_all(parallel: true, timeout: 5)
+      start_time = Time.now
+
+      results = if parallel
+                  check_parallel(timeout)
+                else
+                  check_sequential(timeout)
+                end
+
+      healthy_count = results.count { |_, r| r.healthy? }
+      all_healthy = healthy_count == results.size
+
+      {
+        overall_healthy: all_healthy,
+        healthy_count: healthy_count,
+        total_count: results.size,
+        total_latency_ms: ((Time.now - start_time) * 1000).round(2),
+        checked_at: Time.now.utc.iso8601,
+        results: results.transform_values(&:to_h)
+      }
+    end
+
+    # Check if all providers are healthy
+    #
+    # @return [Boolean]
+    def all_healthy?(timeout: 5)
+      check_all(timeout: timeout)[:overall_healthy]
+    end
+
+    # Check if any provider is healthy
+    #
+    # @return [Boolean]
+    def any_healthy?(timeout: 5)
+      check_all(timeout: timeout)[:healthy_count].positive?
+    end
+
+    private
+
+    def check_parallel(timeout)
+      threads = clients.map do |name, client|
+        Thread.new { [name, client.health_check(timeout: timeout)] }
+      end
+
+      threads.to_h(&:value)
+    end
+
+    def check_sequential(timeout)
+      clients.transform_values { |client| client.health_check(timeout: timeout) }
+    end
+  end
+end