vectra-client 0.3.0 → 0.3.2

data/lib/vectra/audit_log.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module Vectra
+  # Audit logging for security and compliance
+  #
+  # Provides structured audit logs for security-sensitive operations,
+  # including authentication, authorization, and data access.
+  #
+  # @example Basic usage
+  #   audit = Vectra::AuditLog.new(output: "log/audit.json.log")
+  #
+  #   audit.log_access(
+  #     user_id: "user123",
+  #     operation: "query",
+  #     index: "sensitive-data",
+  #     result_count: 10
+  #   )
+  #
+  class AuditLog
+    # Audit event types
+    EVENT_TYPES = %i[
+      access
+      authentication
+      authorization
+      configuration_change
+      credential_rotation
+      data_modification
+      error
+    ].freeze
+
+    attr_reader :logger, :enabled
+
+    # Initialize audit logger
+    #
+    # @param output [IO, String] Log output destination
+    # @param enabled [Boolean] Enable/disable audit logging
+    # @param metadata [Hash] Default metadata for all events
+    def initialize(output: $stdout, enabled: true, **metadata)
+      @enabled = enabled
+      @logger = enabled ? Vectra::JsonLogger.new(output, **metadata) : nil
+    end
+
+    # Log access event
+    #
+    # @param user_id [String, nil] User identifier
+    # @param operation [Symbol, String] Operation type
+    # @param index [String] Index accessed
+    # @param result_count [Integer, nil] Number of results
+    # @param metadata [Hash] Additional metadata
+    def log_access(operation:, index: nil, result_count: nil, user_id: nil, **metadata)
+      log_event(
+        type: :access,
+        user_id: user_id,
+        operation: operation.to_s,
+        resource: index,
+        result_count: result_count,
+        **metadata
+      )
+    end
+
+    # Log authentication event
+    #
+    # @param user_id [String, nil] User identifier
+    # @param success [Boolean] Authentication success
+    # @param provider [String, nil] Provider name
+    # @param metadata [Hash] Additional metadata
+    def log_authentication(success:, provider: nil, user_id: nil, **metadata)
+      log_event(
+        type: :authentication,
+        user_id: user_id,
+        success: success,
+        provider: provider,
+        **metadata
+      )
+    end
+
+    # Log authorization event
+    #
+    # @param user_id [String] User identifier
+    # @param resource [String] Resource accessed
+    # @param allowed [Boolean] Authorization result
+    # @param reason [String, nil] Reason if denied
+    def log_authorization(user_id:, resource:, allowed:, reason: nil)
+      log_event(
+        type: :authorization,
+        user_id: user_id,
+        resource: resource,
+        allowed: allowed,
+        reason: reason
+      )
+    end
+
+    # Log configuration change
+    #
+    # @param user_id [String] User who made change
+    # @param change_type [String] Type of change
+    # @param old_value [Object, nil] Previous value
+    # @param new_value [Object, nil] New value
+    def log_configuration_change(user_id:, change_type:, old_value: nil, new_value: nil)
+      log_event(
+        type: :configuration_change,
+        user_id: user_id,
+        change_type: change_type,
+        old_value: sanitize_value(old_value),
+        new_value: sanitize_value(new_value)
+      )
+    end
+
+    # Log credential rotation
+    #
+    # @param provider [String] Provider name
+    # @param success [Boolean] Rotation success
+    # @param rotated_by [String, nil] User who initiated rotation
+    def log_credential_rotation(provider:, success:, rotated_by: nil)
+      log_event(
+        type: :credential_rotation,
+        provider: provider,
+        success: success,
+        rotated_by: rotated_by
+      )
+    end
+
+    # Log data modification
+    #
+    # @param user_id [String, nil] User identifier
+    # @param operation [String] Operation (upsert, delete, update)
+    # @param index [String] Index modified
+    # @param record_count [Integer] Number of records affected
+    def log_data_modification(operation:, index:, record_count:, user_id: nil)
+      log_event(
+        type: :data_modification,
+        user_id: user_id,
+        operation: operation.to_s,
+        resource: index,
+        record_count: record_count
+      )
+    end
+
+    # Log error event
+    #
+    # @param error [Exception] Error that occurred
+    # @param context [Hash] Error context
+    def log_error(error:, **context)
+      log_event(
+        type: :error,
+        error_class: error.class.name,
+        error_message: error.message,
+        severity: error_severity(error),
+        **context
+      )
+    end
+
+    private
+
+    def log_event(type:, **data)
+      return unless @enabled && @logger
+
+      @logger.info(
+        "audit.#{type}",
+        event_type: type.to_s,
+        timestamp: Time.now.utc.iso8601(3),
+        **data
+      )
+    end
+
+    def sanitize_value(value)
+      case value
+      when String
+        # Mask sensitive values: keep a short prefix and suffix, hide the middle
+        return value unless value.length >= 10
+
+        prefix = value[0, 9]
+        suffix = value[-4, 4]
+        "#{prefix}...#{suffix}"
+      when Hash
+        value.transform_values { |v| sanitize_value(v) }
+      else
+        value
+      end
+    end
+
+    def error_severity(error)
+      case error
+      when Vectra::AuthenticationError
+        "critical"
+      when Vectra::ServerError, Vectra::ConnectionError
+        "high"
+      when Vectra::RateLimitError
+        "medium"
+      else
+        "low"
+      end
+    end
+  end
+
+  # Global audit log instance
+  module AuditLogging
+    class << self
+      attr_accessor :audit_log
+
+      # Setup global audit logging
+      #
+      # @param output [IO, String] Log output
+      # @param enabled [Boolean] Enable audit logging
+      # @param metadata [Hash] Default metadata
+      # @return [AuditLog]
+      def setup!(output: "log/audit.json.log", enabled: true, **metadata)
+        @audit_log = AuditLog.new(output: output, enabled: enabled, **metadata)
+      end
+
+      # Log audit event
+      #
+      # @param type [Symbol] Event type
+      # @param data [Hash] Event data
+      def log(type, **data)
+        return unless @audit_log
+
+        @audit_log.public_send("log_#{type}", **data)
+      rescue NoMethodError
+        # Event type not supported
+        @audit_log.instance_variable_get(:@logger)&.info("audit.#{type}", **data)
+      end
+    end
+  end
+end

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